Create a bus search
curl --request POST \
--url https://api.travel.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/bus/searches \
--header 'Content-Type: application/json' \
--data '
{
"from": "terminal-rodoviario-tiete",
"to": "rodoviaria-novo-rio",
"departureDate": "2026-11-02",
"returnDate": "2026-11-05",
"serviceClass": "EXECUTIVE"
}
'import requests
url = "https://api.travel.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/bus/searches"
payload = {
"from": "terminal-rodoviario-tiete",
"to": "rodoviaria-novo-rio",
"departureDate": "2026-11-02",
"returnDate": "2026-11-05",
"serviceClass": "EXECUTIVE"
}
headers = {"Content-Type": "application/json"}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify({
from: 'terminal-rodoviario-tiete',
to: 'rodoviaria-novo-rio',
departureDate: '2026-11-02',
returnDate: '2026-11-05',
serviceClass: 'EXECUTIVE'
})
};
fetch('https://api.travel.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/bus/searches', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.travel.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/bus/searches",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'from' => 'terminal-rodoviario-tiete',
'to' => 'rodoviaria-novo-rio',
'departureDate' => '2026-11-02',
'returnDate' => '2026-11-05',
'serviceClass' => 'EXECUTIVE'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.travel.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/bus/searches"
payload := strings.NewReader("{\n \"from\": \"terminal-rodoviario-tiete\",\n \"to\": \"rodoviaria-novo-rio\",\n \"departureDate\": \"2026-11-02\",\n \"returnDate\": \"2026-11-05\",\n \"serviceClass\": \"EXECUTIVE\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.travel.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/bus/searches")
.header("Content-Type", "application/json")
.body("{\n \"from\": \"terminal-rodoviario-tiete\",\n \"to\": \"rodoviaria-novo-rio\",\n \"departureDate\": \"2026-11-02\",\n \"returnDate\": \"2026-11-05\",\n \"serviceClass\": \"EXECUTIVE\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.travel.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/bus/searches")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n \"from\": \"terminal-rodoviario-tiete\",\n \"to\": \"rodoviaria-novo-rio\",\n \"departureDate\": \"2026-11-02\",\n \"returnDate\": \"2026-11-05\",\n \"serviceClass\": \"EXECUTIVE\"\n}"
response = http.request(request)
puts response.read_body{
"id": "srch_Fg4Ju9SaPe2Wx6TnCi5Oz",
"searchParams": {
"from": "terminal-rodoviario-tiete",
"to": "rodoviaria-novo-rio",
"departureDate": "2026-11-02",
"returnDate": "2026-11-05",
"serviceClass": "EXECUTIVE"
},
"type": "BUS",
"status": "PROCESSING",
"warning": {
"code": "ALL_SUCCESS",
"message": "All suppliers answered."
},
"ttl": 900,
"facets": {},
"createdAt": "2026-10-19T15:00:00.000Z"
}{
"traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b",
"code": "BAD_REQUEST",
"origin": "TRAVEL",
"message": "Bad Request: Your request is invalid or incomplete. Please make sure you are requesting with the right fields.",
"fields": [
{
"field": "from",
"message": "Invalid input: expected string, received undefined",
"code": "FROM_REQUIRED"
}
]
}{
"traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b",
"code": "PROVIDER_UNAVAILABLE",
"origin": "TRAVEL",
"message": "Travel provider temporarily unavailable, please retry."
}Create a bus search
Starts a search for bus trips between two stations, one way or round trip.
POST
/
realms
/
{realmId}
/
organizations
/
{organizationId}
/
bus
/
searches
Create a bus search
curl --request POST \
--url https://api.travel.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/bus/searches \
--header 'Content-Type: application/json' \
--data '
{
"from": "terminal-rodoviario-tiete",
"to": "rodoviaria-novo-rio",
"departureDate": "2026-11-02",
"returnDate": "2026-11-05",
"serviceClass": "EXECUTIVE"
}
'import requests
url = "https://api.travel.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/bus/searches"
payload = {
"from": "terminal-rodoviario-tiete",
"to": "rodoviaria-novo-rio",
"departureDate": "2026-11-02",
"returnDate": "2026-11-05",
"serviceClass": "EXECUTIVE"
}
headers = {"Content-Type": "application/json"}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify({
from: 'terminal-rodoviario-tiete',
to: 'rodoviaria-novo-rio',
departureDate: '2026-11-02',
returnDate: '2026-11-05',
serviceClass: 'EXECUTIVE'
})
};
fetch('https://api.travel.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/bus/searches', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.travel.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/bus/searches",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'from' => 'terminal-rodoviario-tiete',
'to' => 'rodoviaria-novo-rio',
'departureDate' => '2026-11-02',
'returnDate' => '2026-11-05',
'serviceClass' => 'EXECUTIVE'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.travel.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/bus/searches"
payload := strings.NewReader("{\n \"from\": \"terminal-rodoviario-tiete\",\n \"to\": \"rodoviaria-novo-rio\",\n \"departureDate\": \"2026-11-02\",\n \"returnDate\": \"2026-11-05\",\n \"serviceClass\": \"EXECUTIVE\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.travel.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/bus/searches")
.header("Content-Type", "application/json")
.body("{\n \"from\": \"terminal-rodoviario-tiete\",\n \"to\": \"rodoviaria-novo-rio\",\n \"departureDate\": \"2026-11-02\",\n \"returnDate\": \"2026-11-05\",\n \"serviceClass\": \"EXECUTIVE\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.travel.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/bus/searches")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n \"from\": \"terminal-rodoviario-tiete\",\n \"to\": \"rodoviaria-novo-rio\",\n \"departureDate\": \"2026-11-02\",\n \"returnDate\": \"2026-11-05\",\n \"serviceClass\": \"EXECUTIVE\"\n}"
response = http.request(request)
puts response.read_body{
"id": "srch_Fg4Ju9SaPe2Wx6TnCi5Oz",
"searchParams": {
"from": "terminal-rodoviario-tiete",
"to": "rodoviaria-novo-rio",
"departureDate": "2026-11-02",
"returnDate": "2026-11-05",
"serviceClass": "EXECUTIVE"
},
"type": "BUS",
"status": "PROCESSING",
"warning": {
"code": "ALL_SUCCESS",
"message": "All suppliers answered."
},
"ttl": 900,
"facets": {},
"createdAt": "2026-10-19T15:00:00.000Z"
}{
"traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b",
"code": "BAD_REQUEST",
"origin": "TRAVEL",
"message": "Bad Request: Your request is invalid or incomplete. Please make sure you are requesting with the right fields.",
"fields": [
{
"field": "from",
"message": "Invalid input: expected string, received undefined",
"code": "FROM_REQUIRED"
}
]
}{
"traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b",
"code": "PROVIDER_UNAVAILABLE",
"origin": "TRAVEL",
"message": "Travel provider temporarily unavailable, please retry."
}Searches are asynchronous: this answers
202 at once with the search in PROCESSING status while the travel suppliers answer in the background. Poll the search with its id until status is COMPLETED — or FAILED — to read the results. A bus search lasts 15 minutes (see ttl); after that, create it again. Creating the same search again while it lasts returns the same id, and only your organization can read the searches it created.
Find from and to with the locations endpoint. To book a result, open the item for its segments and seat map, then create a trip with the item’s id as searchItemId, the segments’ id as segmentId and a bookable seat’s number as seatNumber.
An error the travel provider reports about the request — an unknown station, say — is returned with its own status, code and message.Path Parameters
ID of your realm.
Format: UUID
ID of your organization.
Format: UUID
Body
application/json
Origin bus station: its id or its slug from the locations endpoint. Must differ from to.
Minimum string length:
1Example:
"terminal-rodoviario-tiete"
Destination bus station: its id or its slug from the locations endpoint. Must differ from from.
Minimum string length:
1Example:
"rodoviaria-novo-rio"
Outbound trip date (YYYY-MM-DD). Today or later.
Minimum string length:
1Example:
"2026-11-02"
Return trip date (YYYY-MM-DD), on or after departureDate. Omit it for a one-way trip.
Minimum string length:
1Example:
"2026-11-05"
Preferred service class: SLEEPER_BED, BED, SEMI_BED, EXECUTIVE, CONVENTIONAL or UNDEFINED. Omit it to search every class.
Minimum string length:
1Example:
"EXECUTIVE"
Response
Successful response
A search just created for bus trips. Results come later: poll the search.
ID of the search. The same search parameters, within the time the search lasts, return the same ID.
Example:
"srch_Fg4Ju9SaPe2Wx6TnCi5Oz"
What the search was made for.
Show child attributes
Show child attributes
Always BUS.
Available options:
BUS Example:
"BUS"
PROCESSING right after creation. It becomes COMPLETED or FAILED on its own: poll the search.
Available options:
PROCESSING, FAILED, COMPLETED Example:
"PROCESSING"
How the search went across the suppliers. null while it is processing.
Show child attributes
Show child attributes
Seconds until the search expires.
Example:
900
Facets to build filters from (companies, service classes, price ranges). null until the search completes.
Show child attributes
Show child attributes
When the search was created.
Example:
"2026-10-19T15:00:00.000Z"