{ "openapi": "3.0.3", "info": { "title": "Travel", "version": "1.0.0", "description": "Portão 3 travel API. Every endpoint requires a bearer token in the Authorization header (Authorization: Bearer ) unless its page states otherwise; see the Authentication guide. That requirement is not repeated per endpoint. Generated by tools/openapi from code (routes + security) and the hand-written spec (request/response bodies). Passenger directory, trips and the search proxy (air/hotel/bus/vehicle). Every route validates path, query and body through a zod Input class (`travel/src/domain/*/input`), which documents its parameters and body; responses are the named interfaces in `travel/src/domain/*/response.ts`. Confidence tiers: generated:typed=53 copied:manual=0 unknown=0." }, "servers": [ { "url": "https://api.travel.v2.portao3.com.br/", "description": "production" }, { "url": "https://api.travel.dev.3pers.com.br/", "description": "development" } ], "x-p3-surface": "public", "tags": [ { "name": "Passengers" }, { "name": "Trips" }, { "name": "Air search" }, { "name": "Hotel search" }, { "name": "Bus search" }, { "name": "Vehicle search" } ], "components": {}, "paths": { "/realms/{realmId}/organizations/{organizationId}/passengers": { "get": { "operationId": "getRealmsByRealmIdOrganizationsByOrganizationIdPassengers", "summary": "List passengers", "tags": [ "Passengers" ], "x-p3-sidebar-order": 1, "description": "Lists the organization's passengers, followed by its users who are not passengers yet.", "x-mint": { "content": "Passengers come first, sorted by name. Once they run out, the list continues with the organization's active users who have no passenger (`source: USER`, `profileComplete: false`), also sorted by name — create a passenger linked to one of them (`userId`) before booking them on a trip. The `name`, `email` and `document` filters apply to both kinds of row." }, "parameters": [ { "name": "realmId", "in": "path", "required": true, "description": "ID of your realm.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b" }, { "name": "organizationId", "in": "path", "required": true, "description": "ID of the organization whose passengers you want to list.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410" }, { "name": "name", "in": "query", "required": false, "description": "Only rows whose name contains this text (case-insensitive).", "schema": { "type": "string", "maxLength": 120 }, "example": "mariana" }, { "name": "email", "in": "query", "required": false, "description": "Only rows whose e-mail contains this text (case-insensitive).", "schema": { "type": "string", "maxLength": 254 }, "example": "acme.com.br" }, { "name": "document", "in": "query", "required": false, "description": "Only rows whose CPF contains these digits, with or without punctuation.", "schema": { "type": "string", "maxLength": 30 }, "example": "52998224725" }, { "name": "next", "in": "query", "required": false, "description": "Cursor returned as `next` by the previous page. Omit for the first page.", "schema": { "type": "string" }, "example": "eyJwIjoiNjcxMGEzZjJjOWU3N2IwMDEyYTRkNWUxIn0=" }, { "name": "limit", "in": "query", "required": false, "description": "Page size.", "schema": { "default": 15, "type": "integer", "minimum": 1, "maximum": 100 }, "example": 15 } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the passenger.", "example": "6710a3f2c9e77b0012a4d5e1" }, "realmId": { "type": "string", "description": "ID of the realm the passenger belongs to.", "example": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b", "format": "uuid" }, "organizationId": { "type": "string", "description": "ID of the organization the passenger belongs to.", "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410", "format": "uuid" }, "source": { "type": "string", "enum": [ "PASSENGER" ], "description": "Always `PASSENGER` for a passenger. In the passenger list, it tells a passenger apart from a user who is not a passenger yet (`USER`).", "example": "PASSENGER" }, "profileComplete": { "type": "boolean", "enum": [ true ], "description": "Always `true`: a passenger has every field a booking needs.", "example": true }, "userId": { "type": "string", "description": "ID of the organization user this passenger is linked to. Omitted for a passenger who is not a user. A linked passenger's `name`, first e-mail and CPF come from the user and can't be changed.", "example": "e3553bc1-5e20-4e17-b22a-a796fda0aa99", "format": "uuid" }, "name": { "type": "string", "description": "Full name, as it appears on the passenger's travel documents.", "example": "Mariana Costa" }, "gender": { "type": "string", "enum": [ "MALE", "FEMALE" ], "description": "Gender.", "example": "FEMALE" }, "birthDate": { "type": "string", "description": "Date of birth (`YYYY-MM-DD`).", "example": "1990-04-17" }, "emails": { "type": "array", "items": { "type": "string", "example": "mariana.costa@acme.com.br" }, "description": "Contact e-mails. The first one is the main contact.\n\n---\n\nExample: `[\"mariana.costa@acme.com.br\"]`" }, "phoneNumbers": { "type": "array", "items": { "type": "string", "example": "+5511987654321" }, "description": "Contact phone numbers, in international format.\n\n---\n\nExample: `[\"+5511987654321\"]`" }, "documents": { "type": "object", "properties": { "CPF": { "description": "Brazilian taxpayer ID (CPF), 11 digits.", "type": "object", "properties": { "code": { "type": "string", "description": "Document number as printed, digits and letters only (no punctuation).", "example": "52998224725" }, "issueCountry": { "type": "string", "description": "Country that issued the document (ISO 3166-1 alpha-2). Always `BR` for `CPF`, `RG` and `CNH`.", "example": "BR" } }, "required": [ "code", "issueCountry" ], "nullable": true }, "RG": { "description": "Brazilian national identity card (RG).", "type": "object", "properties": { "code": { "type": "string", "description": "Document number as printed, digits and letters only (no punctuation).", "example": "52998224725" }, "issueCountry": { "type": "string", "description": "Country that issued the document (ISO 3166-1 alpha-2). Always `BR` for `CPF`, `RG` and `CNH`.", "example": "BR" } }, "required": [ "code", "issueCountry" ], "nullable": true }, "PASSPORT": { "description": "Passport.", "type": "object", "properties": { "code": { "type": "string", "description": "Document number as printed, digits and letters only (no punctuation).", "example": "52998224725" }, "issueCountry": { "type": "string", "description": "Country that issued the document (ISO 3166-1 alpha-2). Always `BR` for `CPF`, `RG` and `CNH`.", "example": "BR" }, "expirationDate": { "type": "string", "nullable": true, "description": "Expiration date (`YYYY-MM-DD`). `null` for a passport registered before the date was required.", "example": "2031-04-17" } }, "required": [ "code", "expirationDate", "issueCountry" ], "nullable": true }, "CNH": { "description": "Brazilian driver's license (CNH).", "type": "object", "properties": { "code": { "type": "string", "description": "Document number as printed, digits and letters only (no punctuation).", "example": "52998224725" }, "issueCountry": { "type": "string", "description": "Country that issued the document (ISO 3166-1 alpha-2). Always `BR` for `CPF`, `RG` and `CNH`.", "example": "BR" } }, "required": [ "code", "issueCountry" ], "nullable": true } }, "description": "Identity documents." }, "address": { "type": "object", "properties": { "shortAddress": { "type": "string", "description": "The address in a single line.", "example": "Av. Paulista, 1000 - Bela Vista, São Paulo - SP" }, "adressLines": { "type": "array", "items": { "type": "string", "example": "Av. Paulista, 1000" }, "description": "The address in postal lines. The field name is spelled `adressLines`.\n\n---\n\nExample: `[\"Av. Paulista, 1000\",\"Bela Vista\"]`" }, "locality": { "type": "string", "description": "City.", "example": "São Paulo" }, "administrativeArea": { "type": "string", "description": "State or province code.", "example": "SP" }, "administrativeAreaName": { "type": "string", "description": "State or province name.", "example": "São Paulo" }, "postalCode": { "type": "string", "description": "Postal code.", "example": "01310-100" }, "country": { "type": "string", "description": "Country (ISO 3166-1 alpha-2).", "example": "BR" }, "timezone": { "type": "string", "description": "IANA time zone of the address.", "example": "America/Sao_Paulo" }, "coordinates": { "type": "object", "properties": { "lat": { "type": "number", "description": "Latitude.", "example": -23.5614 }, "lng": { "type": "number", "description": "Longitude.", "example": -46.6559 } }, "required": [ "lat", "lng" ], "description": "Location of the address." } }, "required": [ "shortAddress", "adressLines", "locality", "administrativeArea", "administrativeAreaName", "postalCode", "country", "timezone", "coordinates" ], "description": "Home address." }, "loyalty": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Loyalty program numbers, keyed by carrier code. Omitted when there are none.\n\n---\n\nExample: `{\"LA\":\"123456789\"}`", "example": { "LA": "123456789" } }, "customFields": { "type": "object", "additionalProperties": {}, "description": "Values of the organization's passenger custom fields, keyed by the custom field's `slug`. Empty when none were set.\n\n---\n\nExample: `{\"cost-center\":\"CC-1020\"}`", "example": { "cost-center": "CC-1020" } }, "status": { "type": "string", "enum": [ "ACTIVE", "DELETED" ], "description": "Status of the passenger. Only `ACTIVE` passengers are returned.", "example": "ACTIVE" }, "createdAt": { "type": "string", "description": "When the passenger was created.", "example": "2026-10-01T13:45:12.000Z", "format": "date-time" }, "updatedAt": { "type": "string", "description": "When the passenger was last changed.", "example": "2026-10-01T13:45:12.000Z", "format": "date-time" } }, "required": [ "id", "realmId", "organizationId", "source", "profileComplete", "name", "gender", "birthDate", "emails", "phoneNumbers", "documents", "address", "customFields", "status" ], "description": "A passenger of the organization: a traveler who can be booked on trips." }, { "type": "object", "properties": { "realmId": { "type": "string", "description": "ID of the realm the user belongs to.", "example": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b", "format": "uuid" }, "organizationId": { "type": "string", "description": "ID of the organization the user belongs to.", "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410", "format": "uuid" }, "source": { "type": "string", "enum": [ "USER" ], "description": "Always `USER`: a user who is not a passenger yet.", "example": "USER" }, "profileComplete": { "type": "boolean", "enum": [ false ], "description": "Always `false`: a user lacks fields a booking needs (gender, phone and address at least).", "example": false }, "userId": { "type": "string", "description": "ID of the user.", "example": "9b2d4f6a-1c3e-4a5b-8d7f-0e1a2b3c4d5e", "format": "uuid" }, "name": { "type": "string", "description": "Full name of the user.", "example": "Rafael Lima" }, "email": { "type": "string", "description": "E-mail of the user.", "example": "rafael.lima@acme.com.br" }, "document": { "type": "string", "description": "CPF of the user, digits only. Omitted when the user has none.", "example": "39053344705" }, "birthDate": { "type": "string", "description": "Date of birth (`YYYY-MM-DD`). Omitted when the user has none.", "example": "1987-11-02" } }, "required": [ "realmId", "organizationId", "source", "profileComplete", "userId", "name" ], "description": "A user of the organization who is not a passenger yet. Create a passenger linked to them (`userId`) before booking them on a trip." } ] }, "description": "Passengers first, sorted by name; once they run out, users of the organization who are not passengers yet (`source: USER`), also sorted by name." }, "next": { "type": "string", "nullable": true, "description": "Cursor for the next page. `null` on the last page.", "example": "eyJwIjoiNjcxMGEzZjJjOWU3N2IwMDEyYTRkNWUxIn0=" } }, "required": [ "items", "next" ], "description": "One page of the passenger list." } } } }, "422": { "description": "`BAD_REQUEST` — A path or query parameter is invalid; `fields` lists each one.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "BAD_REQUEST" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "TRAVEL" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." }, "fields": { "type": "array", "description": "One entry per invalid request field (validation errors only).", "items": { "type": "object", "properties": { "field": { "type": "string", "description": "Path of the invalid field, e.g. `label` or `values[0].value`.", "example": "label" }, "message": { "type": "string", "description": "Why the field was rejected.", "example": "label is required" }, "code": { "type": "string", "description": "`_` — e.g. `LABEL_REQUIRED`, `TYPE_ONE_OF`, `VALUES_VALUE_TYPE_ERROR`.", "example": "LABEL_REQUIRED" }, "values": { "type": "array", "items": { "type": "string" }, "description": "The accepted values, when the field is an enumeration." } }, "required": [ "field", "message", "code" ] } } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "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": "name", "message": "Too big: expected string to have <=120 characters", "code": "NAME_MAX" } ] } } } } }, "x-p3-confidence": { "response": "generated:typed", "parameters": "generated:typed" } }, "post": { "operationId": "postRealmsByRealmIdOrganizationsByOrganizationIdPassengers", "summary": "Create a passenger", "tags": [ "Passengers" ], "x-p3-sidebar-order": 3, "description": "Registers a passenger in the organization, so they can be booked on trips.", "x-mint": { "content": "Send `userId` to register one of the organization's users: their name, e-mail and CPF are copied from the user and can't be changed later. Without `userId`, you register someone who is not a user, and the full profile is required: `name`, `birthDate`, `emails` and at least one document.\n\nEvery required passenger custom field of the organization must be in `customFields`. An error the travel provider reports about the passenger's data — a document number it rejects, say — is returned with its own status, `code` and `message`." }, "parameters": [ { "name": "realmId", "in": "path", "required": true, "description": "ID of your realm.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b" }, { "name": "organizationId", "in": "path", "required": true, "description": "ID of the organization to register the passenger in.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "userId": { "description": "ID of an active user of the organization to link the passenger to. The passenger's name, e-mail and CPF are then copied from the user — don't send `name`, `emails` or `documents.CPF` — and `birthDate` is needed only when the user has none. Omit it to register someone who is not a user; `name`, `birthDate`, `emails` and at least one document are then required. A user can have only one passenger.\n\nFormat: `UUID`", "example": "e3553bc1-5e20-4e17-b22a-a796fda0aa99", "type": "string", "format": "uuid" }, "name": { "description": "Full name, as it appears on the passenger's travel documents. Required without `userId`; don't send it with `userId`.", "example": "Mariana Costa", "type": "string", "minLength": 1 }, "gender": { "type": "string", "enum": [ "MALE", "FEMALE" ], "description": "Gender.", "example": "FEMALE" }, "birthDate": { "description": "Date of birth (`YYYY-MM-DD`). Required without `userId`; with `userId`, used only when the user has none.", "example": "1990-04-17", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "emails": { "description": "Contact e-mails; the first one is the main contact. Required without `userId`; don't send it with `userId`.\n\n---\n\nExample: `[\"mariana.costa@acme.com.br\"]`", "minItems": 1, "type": "array", "items": { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$", "example": "mariana.costa@acme.com.br" } }, "phoneNumbers": { "minItems": 1, "type": "array", "items": { "anyOf": [ { "type": "string", "pattern": "^\\d{10,15}$" }, { "type": "string", "pattern": "^\\+[1-9]\\d{9,14}$" } ], "example": "+5511987654321" }, "description": "Contact phone numbers in international format (`+5511987654321`). Digits only with the country code (`5511987654321`) is also accepted.\n\n---\n\nExample: `[\"+5511987654321\"]`" }, "documents": { "description": "Identity documents, by type. Without `userId`, at least one is required. With `userId`, the CPF comes from the user; you may add the others (an empty object is fine).", "type": "object", "properties": { "CPF": { "description": "Brazilian taxpayer ID. Don't send it with `userId` — it comes from the user.", "type": "object", "properties": { "code": { "type": "string", "minLength": 1, "description": "CPF number, 11 digits.", "example": "52998224725" }, "issueCountry": { "type": "string", "minLength": 2, "maxLength": 2, "description": "Issuing country. Always `BR`.", "example": "BR" } }, "required": [ "code", "issueCountry" ], "nullable": true }, "RG": { "description": "Brazilian national identity card.", "type": "object", "properties": { "code": { "type": "string", "minLength": 1, "description": "RG number, digits and letters only.", "example": "123456789" }, "issueCountry": { "type": "string", "minLength": 2, "maxLength": 2, "description": "Issuing country. Always `BR`.", "example": "BR" } }, "required": [ "code", "issueCountry" ], "nullable": true }, "PASSPORT": { "description": "Passport.", "type": "object", "properties": { "code": { "type": "string", "minLength": 1, "description": "Passport number.", "example": "FX123456" }, "issueCountry": { "type": "string", "minLength": 2, "maxLength": 2, "description": "Issuing country (ISO 3166-1 alpha-2).", "example": "BR" }, "expirationDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Expiration date (`YYYY-MM-DD`).", "example": "2031-04-17" } }, "required": [ "code", "issueCountry", "expirationDate" ], "nullable": true }, "CNH": { "description": "Brazilian driver's license.", "type": "object", "properties": { "code": { "type": "string", "minLength": 1, "description": "Driver's license number.", "example": "01234567890" }, "issueCountry": { "type": "string", "minLength": 2, "maxLength": 2, "description": "Issuing country. Always `BR`.", "example": "BR" } }, "required": [ "code", "issueCountry" ], "nullable": true } } }, "address": { "type": "object", "properties": { "shortAddress": { "type": "string", "minLength": 1, "description": "The address in a single line.", "example": "Av. Paulista, 1000 - Bela Vista, São Paulo - SP" }, "adressLines": { "minItems": 1, "type": "array", "items": { "type": "string", "minLength": 1, "example": "Av. Paulista, 1000" }, "description": "The address in postal lines. The field name is spelled `adressLines`.\n\n---\n\nExample: `[\"Av. Paulista, 1000\",\"Bela Vista\"]`" }, "locality": { "type": "string", "minLength": 1, "description": "City.", "example": "São Paulo" }, "administrativeArea": { "type": "string", "minLength": 1, "description": "State or province code.", "example": "SP" }, "administrativeAreaName": { "type": "string", "minLength": 1, "description": "State or province name.", "example": "São Paulo" }, "postalCode": { "type": "string", "minLength": 1, "description": "Postal code.", "example": "01310-100" }, "country": { "type": "string", "minLength": 2, "maxLength": 2, "description": "Country (ISO 3166-1 alpha-2).", "example": "BR" }, "timezone": { "type": "string", "minLength": 1, "description": "IANA time zone of the address.", "example": "America/Sao_Paulo" }, "coordinates": { "type": "object", "properties": { "lat": { "type": "number", "description": "Latitude.", "example": -23.5614 }, "lng": { "type": "number", "description": "Longitude.", "example": -46.6559 } }, "required": [ "lat", "lng" ], "description": "Location of the address." } }, "required": [ "shortAddress", "adressLines", "locality", "administrativeArea", "administrativeAreaName", "postalCode", "country", "timezone", "coordinates" ], "description": "Home address." }, "loyalty": { "description": "Loyalty program numbers, keyed by carrier code.\n\n---\n\nExample: `{\"LA\":\"123456789\"}`", "example": { "LA": "123456789" }, "type": "object", "additionalProperties": { "type": "string" } }, "customFields": { "description": "Values of the organization's passenger custom fields, keyed by the custom field's `slug`. Every required one must be present.\n\n---\n\nExample: `{\"cost-center\":\"CC-1020\"}`", "example": { "cost-center": "CC-1020" }, "type": "object", "additionalProperties": {} } }, "required": [ "gender", "phoneNumbers", "address" ] } } } }, "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the passenger.", "example": "6710a3f2c9e77b0012a4d5e1" }, "realmId": { "type": "string", "description": "ID of the realm the passenger belongs to.", "example": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b", "format": "uuid" }, "organizationId": { "type": "string", "description": "ID of the organization the passenger belongs to.", "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410", "format": "uuid" }, "source": { "type": "string", "enum": [ "PASSENGER" ], "description": "Always `PASSENGER` for a passenger. In the passenger list, it tells a passenger apart from a user who is not a passenger yet (`USER`).", "example": "PASSENGER" }, "profileComplete": { "type": "boolean", "enum": [ true ], "description": "Always `true`: a passenger has every field a booking needs.", "example": true }, "userId": { "type": "string", "description": "ID of the organization user this passenger is linked to. Omitted for a passenger who is not a user. A linked passenger's `name`, first e-mail and CPF come from the user and can't be changed.", "example": "e3553bc1-5e20-4e17-b22a-a796fda0aa99", "format": "uuid" }, "name": { "type": "string", "description": "Full name, as it appears on the passenger's travel documents.", "example": "Mariana Costa" }, "gender": { "type": "string", "enum": [ "MALE", "FEMALE" ], "description": "Gender.", "example": "FEMALE" }, "birthDate": { "type": "string", "description": "Date of birth (`YYYY-MM-DD`).", "example": "1990-04-17" }, "emails": { "type": "array", "items": { "type": "string", "example": "mariana.costa@acme.com.br" }, "description": "Contact e-mails. The first one is the main contact.\n\n---\n\nExample: `[\"mariana.costa@acme.com.br\"]`" }, "phoneNumbers": { "type": "array", "items": { "type": "string", "example": "+5511987654321" }, "description": "Contact phone numbers, in international format.\n\n---\n\nExample: `[\"+5511987654321\"]`" }, "documents": { "type": "object", "properties": { "CPF": { "description": "Brazilian taxpayer ID (CPF), 11 digits.", "type": "object", "properties": { "code": { "type": "string", "description": "Document number as printed, digits and letters only (no punctuation).", "example": "52998224725" }, "issueCountry": { "type": "string", "description": "Country that issued the document (ISO 3166-1 alpha-2). Always `BR` for `CPF`, `RG` and `CNH`.", "example": "BR" } }, "required": [ "code", "issueCountry" ], "nullable": true }, "RG": { "description": "Brazilian national identity card (RG).", "type": "object", "properties": { "code": { "type": "string", "description": "Document number as printed, digits and letters only (no punctuation).", "example": "52998224725" }, "issueCountry": { "type": "string", "description": "Country that issued the document (ISO 3166-1 alpha-2). Always `BR` for `CPF`, `RG` and `CNH`.", "example": "BR" } }, "required": [ "code", "issueCountry" ], "nullable": true }, "PASSPORT": { "description": "Passport.", "type": "object", "properties": { "code": { "type": "string", "description": "Document number as printed, digits and letters only (no punctuation).", "example": "52998224725" }, "issueCountry": { "type": "string", "description": "Country that issued the document (ISO 3166-1 alpha-2). Always `BR` for `CPF`, `RG` and `CNH`.", "example": "BR" }, "expirationDate": { "type": "string", "nullable": true, "description": "Expiration date (`YYYY-MM-DD`). `null` for a passport registered before the date was required.", "example": "2031-04-17" } }, "required": [ "code", "expirationDate", "issueCountry" ], "nullable": true }, "CNH": { "description": "Brazilian driver's license (CNH).", "type": "object", "properties": { "code": { "type": "string", "description": "Document number as printed, digits and letters only (no punctuation).", "example": "52998224725" }, "issueCountry": { "type": "string", "description": "Country that issued the document (ISO 3166-1 alpha-2). Always `BR` for `CPF`, `RG` and `CNH`.", "example": "BR" } }, "required": [ "code", "issueCountry" ], "nullable": true } }, "description": "Identity documents." }, "address": { "type": "object", "properties": { "shortAddress": { "type": "string", "description": "The address in a single line.", "example": "Av. Paulista, 1000 - Bela Vista, São Paulo - SP" }, "adressLines": { "type": "array", "items": { "type": "string", "example": "Av. Paulista, 1000" }, "description": "The address in postal lines. The field name is spelled `adressLines`.\n\n---\n\nExample: `[\"Av. Paulista, 1000\",\"Bela Vista\"]`" }, "locality": { "type": "string", "description": "City.", "example": "São Paulo" }, "administrativeArea": { "type": "string", "description": "State or province code.", "example": "SP" }, "administrativeAreaName": { "type": "string", "description": "State or province name.", "example": "São Paulo" }, "postalCode": { "type": "string", "description": "Postal code.", "example": "01310-100" }, "country": { "type": "string", "description": "Country (ISO 3166-1 alpha-2).", "example": "BR" }, "timezone": { "type": "string", "description": "IANA time zone of the address.", "example": "America/Sao_Paulo" }, "coordinates": { "type": "object", "properties": { "lat": { "type": "number", "description": "Latitude.", "example": -23.5614 }, "lng": { "type": "number", "description": "Longitude.", "example": -46.6559 } }, "required": [ "lat", "lng" ], "description": "Location of the address." } }, "required": [ "shortAddress", "adressLines", "locality", "administrativeArea", "administrativeAreaName", "postalCode", "country", "timezone", "coordinates" ], "description": "Home address." }, "loyalty": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Loyalty program numbers, keyed by carrier code. Omitted when there are none.\n\n---\n\nExample: `{\"LA\":\"123456789\"}`", "example": { "LA": "123456789" } }, "customFields": { "type": "object", "additionalProperties": {}, "description": "Values of the organization's passenger custom fields, keyed by the custom field's `slug`. Empty when none were set.\n\n---\n\nExample: `{\"cost-center\":\"CC-1020\"}`", "example": { "cost-center": "CC-1020" } }, "status": { "type": "string", "enum": [ "ACTIVE", "DELETED" ], "description": "Status of the passenger. Only `ACTIVE` passengers are returned.", "example": "ACTIVE" }, "createdAt": { "type": "string", "description": "When the passenger was created.", "example": "2026-10-01T13:45:12.000Z", "format": "date-time" }, "updatedAt": { "type": "string", "description": "When the passenger was last changed.", "example": "2026-10-01T13:45:12.000Z", "format": "date-time" } }, "required": [ "id", "realmId", "organizationId", "source", "profileComplete", "name", "gender", "birthDate", "emails", "phoneNumbers", "documents", "address", "customFields", "status" ], "description": "A passenger of the organization: a traveler who can be booked on trips." } } } }, "404": { "description": "`USER_NOT_FOUND` — `userId` is not an active user of the organization.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "USER_NOT_FOUND" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "TRAVEL" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b", "code": "USER_NOT_FOUND", "origin": "TRAVEL", "message": "User not found in this organization" } } } }, "409": { "description": "`PASSENGER_ALREADY_EXISTS_FOR_USER` — The user in `userId` is already registered as a passenger.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "PASSENGER_ALREADY_EXISTS_FOR_USER" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "TRAVEL" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b", "code": "PASSENGER_ALREADY_EXISTS_FOR_USER", "origin": "TRAVEL", "message": "This user already has a passenger in this organization" } } } }, "422": { "description": "`LINKED_USER_MISSING_BIRTHDATE` — The user in `userId` has no date of birth; send `birthDate`.\n\n`INVALID_CUSTOM_FIELD` — A custom field value is invalid or a required one is missing — or, with `userId`, the user has no CPF and `documents` has no other document.\n\n`BAD_REQUEST` — A path parameter is not a valid ID or the body failed validation; `fields` lists each offending field.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "LINKED_USER_MISSING_BIRTHDATE", "INVALID_CUSTOM_FIELD", "BAD_REQUEST" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "TRAVEL" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." }, "fields": { "type": "array", "description": "One entry per invalid request field (validation errors only).", "items": { "type": "object", "properties": { "field": { "type": "string", "description": "Path of the invalid field, e.g. `label` or `values[0].value`.", "example": "label" }, "message": { "type": "string", "description": "Why the field was rejected.", "example": "label is required" }, "code": { "type": "string", "description": "`_` — e.g. `LABEL_REQUIRED`, `TYPE_ONE_OF`, `VALUES_VALUE_TYPE_ERROR`.", "example": "LABEL_REQUIRED" }, "values": { "type": "array", "items": { "type": "string" }, "description": "The accepted values, when the field is an enumeration." } }, "required": [ "field", "message", "code" ] } } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b", "code": "LINKED_USER_MISSING_BIRTHDATE", "origin": "TRAVEL", "message": "The linked user has no birth date on record — provide birthDate in the request body" } } } }, "503": { "description": "`PROVIDER_UNAVAILABLE` — The travel provider could not be reached; no passenger was created. Retry later.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "PROVIDER_UNAVAILABLE" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "TRAVEL" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b", "code": "PROVIDER_UNAVAILABLE", "origin": "TRAVEL", "message": "Travel provider temporarily unavailable, please retry." } } } } }, "x-p3-confidence": { "response": "generated:typed", "request": "generated:typed", "note": "`.superRefine(…)` constraint not represented (runtime-dependent value)" } } }, "/realms/{realmId}/organizations/{organizationId}/passengers/{passengerId}": { "delete": { "operationId": "deleteRealmsByRealmIdOrganizationsByOrganizationIdPassengersByPassengerId", "summary": "Delete a passenger", "tags": [ "Passengers" ], "x-p3-sidebar-order": 5, "description": "Deletes a passenger from the organization.", "x-mint": { "content": "Trips the passenger is already booked on keep the passenger's data as it was at booking time. The passenger is no longer listed and can't be booked again." }, "parameters": [ { "name": "realmId", "in": "path", "required": true, "description": "ID of your realm.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b" }, { "name": "organizationId", "in": "path", "required": true, "description": "ID of the organization the passenger belongs to.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410" }, { "name": "passengerId", "in": "path", "required": true, "description": "ID of the passenger (24 hexadecimal characters).", "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$" }, "example": "6710a3f2c9e77b0012a4d5e1" } ], "responses": { "204": { "description": "No Content. The operation succeeded and the response has no body." }, "404": { "description": "`PASSENGER_NOT_FOUND` — No active passenger with this ID exists in the organization.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "PASSENGER_NOT_FOUND" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "TRAVEL" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b", "code": "PASSENGER_NOT_FOUND", "origin": "TRAVEL", "message": "Passenger not found" } } } }, "422": { "description": "`BAD_REQUEST` — A path parameter is not a valid ID; `fields` lists each one.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "BAD_REQUEST" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "TRAVEL" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." }, "fields": { "type": "array", "description": "One entry per invalid request field (validation errors only).", "items": { "type": "object", "properties": { "field": { "type": "string", "description": "Path of the invalid field, e.g. `label` or `values[0].value`.", "example": "label" }, "message": { "type": "string", "description": "Why the field was rejected.", "example": "label is required" }, "code": { "type": "string", "description": "`_` — e.g. `LABEL_REQUIRED`, `TYPE_ONE_OF`, `VALUES_VALUE_TYPE_ERROR`.", "example": "LABEL_REQUIRED" }, "values": { "type": "array", "items": { "type": "string" }, "description": "The accepted values, when the field is an enumeration." } }, "required": [ "field", "message", "code" ] } } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "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": "organizationId", "message": "Invalid UUID", "code": "ORGANIZATIONID_UUID" } ] } } } }, "503": { "description": "`PROVIDER_UNAVAILABLE` — The travel provider could not be reached; nothing was deleted. Retry later.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "PROVIDER_UNAVAILABLE" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "TRAVEL" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b", "code": "PROVIDER_UNAVAILABLE", "origin": "TRAVEL", "message": "Travel provider temporarily unavailable, please retry." } } } } }, "x-p3-confidence": { "response": "generated:typed" } }, "get": { "operationId": "getRealmsByRealmIdOrganizationsByOrganizationIdPassengersByPassengerId", "summary": "Get a passenger", "tags": [ "Passengers" ], "x-p3-sidebar-order": 2, "description": "Returns a passenger of the organization.", "x-mint": { "content": "Deleted passengers are not returned." }, "parameters": [ { "name": "realmId", "in": "path", "required": true, "description": "ID of your realm.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b" }, { "name": "organizationId", "in": "path", "required": true, "description": "ID of the organization the passenger belongs to.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410" }, { "name": "passengerId", "in": "path", "required": true, "description": "ID of the passenger (24 hexadecimal characters).", "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$" }, "example": "6710a3f2c9e77b0012a4d5e1" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the passenger.", "example": "6710a3f2c9e77b0012a4d5e1" }, "realmId": { "type": "string", "description": "ID of the realm the passenger belongs to.", "example": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b", "format": "uuid" }, "organizationId": { "type": "string", "description": "ID of the organization the passenger belongs to.", "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410", "format": "uuid" }, "source": { "type": "string", "enum": [ "PASSENGER" ], "description": "Always `PASSENGER` for a passenger. In the passenger list, it tells a passenger apart from a user who is not a passenger yet (`USER`).", "example": "PASSENGER" }, "profileComplete": { "type": "boolean", "enum": [ true ], "description": "Always `true`: a passenger has every field a booking needs.", "example": true }, "userId": { "type": "string", "description": "ID of the organization user this passenger is linked to. Omitted for a passenger who is not a user. A linked passenger's `name`, first e-mail and CPF come from the user and can't be changed.", "example": "e3553bc1-5e20-4e17-b22a-a796fda0aa99", "format": "uuid" }, "name": { "type": "string", "description": "Full name, as it appears on the passenger's travel documents.", "example": "Mariana Costa" }, "gender": { "type": "string", "enum": [ "MALE", "FEMALE" ], "description": "Gender.", "example": "FEMALE" }, "birthDate": { "type": "string", "description": "Date of birth (`YYYY-MM-DD`).", "example": "1990-04-17" }, "emails": { "type": "array", "items": { "type": "string", "example": "mariana.costa@acme.com.br" }, "description": "Contact e-mails. The first one is the main contact.\n\n---\n\nExample: `[\"mariana.costa@acme.com.br\"]`" }, "phoneNumbers": { "type": "array", "items": { "type": "string", "example": "+5511987654321" }, "description": "Contact phone numbers, in international format.\n\n---\n\nExample: `[\"+5511987654321\"]`" }, "documents": { "type": "object", "properties": { "CPF": { "description": "Brazilian taxpayer ID (CPF), 11 digits.", "type": "object", "properties": { "code": { "type": "string", "description": "Document number as printed, digits and letters only (no punctuation).", "example": "52998224725" }, "issueCountry": { "type": "string", "description": "Country that issued the document (ISO 3166-1 alpha-2). Always `BR` for `CPF`, `RG` and `CNH`.", "example": "BR" } }, "required": [ "code", "issueCountry" ], "nullable": true }, "RG": { "description": "Brazilian national identity card (RG).", "type": "object", "properties": { "code": { "type": "string", "description": "Document number as printed, digits and letters only (no punctuation).", "example": "52998224725" }, "issueCountry": { "type": "string", "description": "Country that issued the document (ISO 3166-1 alpha-2). Always `BR` for `CPF`, `RG` and `CNH`.", "example": "BR" } }, "required": [ "code", "issueCountry" ], "nullable": true }, "PASSPORT": { "description": "Passport.", "type": "object", "properties": { "code": { "type": "string", "description": "Document number as printed, digits and letters only (no punctuation).", "example": "52998224725" }, "issueCountry": { "type": "string", "description": "Country that issued the document (ISO 3166-1 alpha-2). Always `BR` for `CPF`, `RG` and `CNH`.", "example": "BR" }, "expirationDate": { "type": "string", "nullable": true, "description": "Expiration date (`YYYY-MM-DD`). `null` for a passport registered before the date was required.", "example": "2031-04-17" } }, "required": [ "code", "expirationDate", "issueCountry" ], "nullable": true }, "CNH": { "description": "Brazilian driver's license (CNH).", "type": "object", "properties": { "code": { "type": "string", "description": "Document number as printed, digits and letters only (no punctuation).", "example": "52998224725" }, "issueCountry": { "type": "string", "description": "Country that issued the document (ISO 3166-1 alpha-2). Always `BR` for `CPF`, `RG` and `CNH`.", "example": "BR" } }, "required": [ "code", "issueCountry" ], "nullable": true } }, "description": "Identity documents." }, "address": { "type": "object", "properties": { "shortAddress": { "type": "string", "description": "The address in a single line.", "example": "Av. Paulista, 1000 - Bela Vista, São Paulo - SP" }, "adressLines": { "type": "array", "items": { "type": "string", "example": "Av. Paulista, 1000" }, "description": "The address in postal lines. The field name is spelled `adressLines`.\n\n---\n\nExample: `[\"Av. Paulista, 1000\",\"Bela Vista\"]`" }, "locality": { "type": "string", "description": "City.", "example": "São Paulo" }, "administrativeArea": { "type": "string", "description": "State or province code.", "example": "SP" }, "administrativeAreaName": { "type": "string", "description": "State or province name.", "example": "São Paulo" }, "postalCode": { "type": "string", "description": "Postal code.", "example": "01310-100" }, "country": { "type": "string", "description": "Country (ISO 3166-1 alpha-2).", "example": "BR" }, "timezone": { "type": "string", "description": "IANA time zone of the address.", "example": "America/Sao_Paulo" }, "coordinates": { "type": "object", "properties": { "lat": { "type": "number", "description": "Latitude.", "example": -23.5614 }, "lng": { "type": "number", "description": "Longitude.", "example": -46.6559 } }, "required": [ "lat", "lng" ], "description": "Location of the address." } }, "required": [ "shortAddress", "adressLines", "locality", "administrativeArea", "administrativeAreaName", "postalCode", "country", "timezone", "coordinates" ], "description": "Home address." }, "loyalty": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Loyalty program numbers, keyed by carrier code. Omitted when there are none.\n\n---\n\nExample: `{\"LA\":\"123456789\"}`", "example": { "LA": "123456789" } }, "customFields": { "type": "object", "additionalProperties": {}, "description": "Values of the organization's passenger custom fields, keyed by the custom field's `slug`. Empty when none were set.\n\n---\n\nExample: `{\"cost-center\":\"CC-1020\"}`", "example": { "cost-center": "CC-1020" } }, "status": { "type": "string", "enum": [ "ACTIVE", "DELETED" ], "description": "Status of the passenger. Only `ACTIVE` passengers are returned.", "example": "ACTIVE" }, "createdAt": { "type": "string", "description": "When the passenger was created.", "example": "2026-10-01T13:45:12.000Z", "format": "date-time" }, "updatedAt": { "type": "string", "description": "When the passenger was last changed.", "example": "2026-10-01T13:45:12.000Z", "format": "date-time" } }, "required": [ "id", "realmId", "organizationId", "source", "profileComplete", "name", "gender", "birthDate", "emails", "phoneNumbers", "documents", "address", "customFields", "status" ], "description": "A passenger of the organization: a traveler who can be booked on trips." } } } }, "404": { "description": "`PASSENGER_NOT_FOUND` — No active passenger with this ID exists in the organization.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "PASSENGER_NOT_FOUND" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "TRAVEL" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b", "code": "PASSENGER_NOT_FOUND", "origin": "TRAVEL", "message": "Passenger not found" } } } }, "422": { "description": "`BAD_REQUEST` — A path parameter is not a valid ID; `fields` lists each one.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "BAD_REQUEST" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "TRAVEL" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." }, "fields": { "type": "array", "description": "One entry per invalid request field (validation errors only).", "items": { "type": "object", "properties": { "field": { "type": "string", "description": "Path of the invalid field, e.g. `label` or `values[0].value`.", "example": "label" }, "message": { "type": "string", "description": "Why the field was rejected.", "example": "label is required" }, "code": { "type": "string", "description": "`_` — e.g. `LABEL_REQUIRED`, `TYPE_ONE_OF`, `VALUES_VALUE_TYPE_ERROR`.", "example": "LABEL_REQUIRED" }, "values": { "type": "array", "items": { "type": "string" }, "description": "The accepted values, when the field is an enumeration." } }, "required": [ "field", "message", "code" ] } } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "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": "organizationId", "message": "Invalid UUID", "code": "ORGANIZATIONID_UUID" } ] } } } } }, "x-p3-confidence": { "response": "generated:typed" } }, "put": { "operationId": "putRealmsByRealmIdOrganizationsByOrganizationIdPassengersByPassengerId", "summary": "Update a passenger", "tags": [ "Passengers" ], "x-p3-sidebar-order": 4, "description": "Replaces a passenger's data.", "x-mint": { "content": "This is a full replace: send every field, as on create. An omitted `loyalty` or `customFields` is cleared. For a passenger linked to a user, `name`, `emails` and `documents.CPF` come from the user — send their current values unchanged; any change is rejected. Custom fields are validated as on create." }, "parameters": [ { "name": "realmId", "in": "path", "required": true, "description": "ID of your realm.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b" }, { "name": "organizationId", "in": "path", "required": true, "description": "ID of the organization the passenger belongs to.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410" }, { "name": "passengerId", "in": "path", "required": true, "description": "ID of the passenger to update.", "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$" }, "example": "6710a3f2c9e77b0012a4d5e1" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "description": "Full name, as it appears on the passenger's travel documents. For a passenger linked to a user, send the current value unchanged.", "example": "Mariana Costa" }, "gender": { "type": "string", "enum": [ "MALE", "FEMALE" ], "description": "Gender.", "example": "FEMALE" }, "birthDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Date of birth (`YYYY-MM-DD`).", "example": "1990-04-17" }, "emails": { "minItems": 1, "type": "array", "items": { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$", "example": "mariana.costa@acme.com.br" }, "description": "Contact e-mails; the first one is the main contact. For a passenger linked to a user, send the current value unchanged.\n\n---\n\nExample: `[\"mariana.costa@acme.com.br\"]`" }, "phoneNumbers": { "minItems": 1, "type": "array", "items": { "anyOf": [ { "type": "string", "pattern": "^\\d{10,15}$" }, { "type": "string", "pattern": "^\\+[1-9]\\d{9,14}$" } ], "example": "+5511987654321" }, "description": "Contact phone numbers in international format (`+5511987654321`). Digits only with the country code (`5511987654321`) is also accepted.\n\n---\n\nExample: `[\"+5511987654321\"]`" }, "documents": { "type": "object", "properties": { "CPF": { "description": "Brazilian taxpayer ID. For a passenger linked to a user, send the current value unchanged.", "type": "object", "properties": { "code": { "type": "string", "minLength": 1, "description": "CPF number, 11 digits.", "example": "52998224725" }, "issueCountry": { "type": "string", "minLength": 2, "maxLength": 2, "description": "Issuing country. Always `BR`.", "example": "BR" } }, "required": [ "code", "issueCountry" ], "nullable": true }, "RG": { "description": "Brazilian national identity card.", "type": "object", "properties": { "code": { "type": "string", "minLength": 1, "description": "RG number, digits and letters only.", "example": "123456789" }, "issueCountry": { "type": "string", "minLength": 2, "maxLength": 2, "description": "Issuing country. Always `BR`.", "example": "BR" } }, "required": [ "code", "issueCountry" ], "nullable": true }, "PASSPORT": { "description": "Passport.", "type": "object", "properties": { "code": { "type": "string", "minLength": 1, "description": "Passport number.", "example": "FX123456" }, "issueCountry": { "type": "string", "minLength": 2, "maxLength": 2, "description": "Issuing country (ISO 3166-1 alpha-2).", "example": "BR" }, "expirationDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Expiration date (`YYYY-MM-DD`).", "example": "2031-04-17" } }, "required": [ "code", "issueCountry", "expirationDate" ], "nullable": true }, "CNH": { "description": "Brazilian driver's license.", "type": "object", "properties": { "code": { "type": "string", "minLength": 1, "description": "Driver's license number.", "example": "01234567890" }, "issueCountry": { "type": "string", "minLength": 2, "maxLength": 2, "description": "Issuing country. Always `BR`.", "example": "BR" } }, "required": [ "code", "issueCountry" ], "nullable": true } }, "description": "Identity documents, by type. At least one is required." }, "address": { "type": "object", "properties": { "shortAddress": { "type": "string", "minLength": 1, "description": "The address in a single line.", "example": "Av. Paulista, 1000 - Bela Vista, São Paulo - SP" }, "adressLines": { "minItems": 1, "type": "array", "items": { "type": "string", "minLength": 1, "example": "Av. Paulista, 1000" }, "description": "The address in postal lines. The field name is spelled `adressLines`.\n\n---\n\nExample: `[\"Av. Paulista, 1000\",\"Bela Vista\"]`" }, "locality": { "type": "string", "minLength": 1, "description": "City.", "example": "São Paulo" }, "administrativeArea": { "type": "string", "minLength": 1, "description": "State or province code.", "example": "SP" }, "administrativeAreaName": { "type": "string", "minLength": 1, "description": "State or province name.", "example": "São Paulo" }, "postalCode": { "type": "string", "minLength": 1, "description": "Postal code.", "example": "01310-100" }, "country": { "type": "string", "minLength": 2, "maxLength": 2, "description": "Country (ISO 3166-1 alpha-2).", "example": "BR" }, "timezone": { "type": "string", "minLength": 1, "description": "IANA time zone of the address.", "example": "America/Sao_Paulo" }, "coordinates": { "type": "object", "properties": { "lat": { "type": "number", "description": "Latitude.", "example": -23.5614 }, "lng": { "type": "number", "description": "Longitude.", "example": -46.6559 } }, "required": [ "lat", "lng" ], "description": "Location of the address." } }, "required": [ "shortAddress", "adressLines", "locality", "administrativeArea", "administrativeAreaName", "postalCode", "country", "timezone", "coordinates" ], "description": "Home address." }, "loyalty": { "description": "Loyalty program numbers, keyed by carrier code.\n\n---\n\nExample: `{\"LA\":\"123456789\"}`", "example": { "LA": "123456789" }, "type": "object", "additionalProperties": { "type": "string" } }, "customFields": { "description": "Values of the organization's passenger custom fields, keyed by the custom field's `slug`. Every required one must be present.\n\n---\n\nExample: `{\"cost-center\":\"CC-1020\"}`", "example": { "cost-center": "CC-1020" }, "type": "object", "additionalProperties": {} } }, "required": [ "name", "gender", "birthDate", "emails", "phoneNumbers", "documents", "address" ] } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the passenger.", "example": "6710a3f2c9e77b0012a4d5e1" }, "realmId": { "type": "string", "description": "ID of the realm the passenger belongs to.", "example": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b", "format": "uuid" }, "organizationId": { "type": "string", "description": "ID of the organization the passenger belongs to.", "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410", "format": "uuid" }, "source": { "type": "string", "enum": [ "PASSENGER" ], "description": "Always `PASSENGER` for a passenger. In the passenger list, it tells a passenger apart from a user who is not a passenger yet (`USER`).", "example": "PASSENGER" }, "profileComplete": { "type": "boolean", "enum": [ true ], "description": "Always `true`: a passenger has every field a booking needs.", "example": true }, "userId": { "type": "string", "description": "ID of the organization user this passenger is linked to. Omitted for a passenger who is not a user. A linked passenger's `name`, first e-mail and CPF come from the user and can't be changed.", "example": "e3553bc1-5e20-4e17-b22a-a796fda0aa99", "format": "uuid" }, "name": { "type": "string", "description": "Full name, as it appears on the passenger's travel documents.", "example": "Mariana Costa" }, "gender": { "type": "string", "enum": [ "MALE", "FEMALE" ], "description": "Gender.", "example": "FEMALE" }, "birthDate": { "type": "string", "description": "Date of birth (`YYYY-MM-DD`).", "example": "1990-04-17" }, "emails": { "type": "array", "items": { "type": "string", "example": "mariana.costa@acme.com.br" }, "description": "Contact e-mails. The first one is the main contact.\n\n---\n\nExample: `[\"mariana.costa@acme.com.br\"]`" }, "phoneNumbers": { "type": "array", "items": { "type": "string", "example": "+5511987654321" }, "description": "Contact phone numbers, in international format.\n\n---\n\nExample: `[\"+5511987654321\"]`" }, "documents": { "type": "object", "properties": { "CPF": { "description": "Brazilian taxpayer ID (CPF), 11 digits.", "type": "object", "properties": { "code": { "type": "string", "description": "Document number as printed, digits and letters only (no punctuation).", "example": "52998224725" }, "issueCountry": { "type": "string", "description": "Country that issued the document (ISO 3166-1 alpha-2). Always `BR` for `CPF`, `RG` and `CNH`.", "example": "BR" } }, "required": [ "code", "issueCountry" ], "nullable": true }, "RG": { "description": "Brazilian national identity card (RG).", "type": "object", "properties": { "code": { "type": "string", "description": "Document number as printed, digits and letters only (no punctuation).", "example": "52998224725" }, "issueCountry": { "type": "string", "description": "Country that issued the document (ISO 3166-1 alpha-2). Always `BR` for `CPF`, `RG` and `CNH`.", "example": "BR" } }, "required": [ "code", "issueCountry" ], "nullable": true }, "PASSPORT": { "description": "Passport.", "type": "object", "properties": { "code": { "type": "string", "description": "Document number as printed, digits and letters only (no punctuation).", "example": "52998224725" }, "issueCountry": { "type": "string", "description": "Country that issued the document (ISO 3166-1 alpha-2). Always `BR` for `CPF`, `RG` and `CNH`.", "example": "BR" }, "expirationDate": { "type": "string", "nullable": true, "description": "Expiration date (`YYYY-MM-DD`). `null` for a passport registered before the date was required.", "example": "2031-04-17" } }, "required": [ "code", "expirationDate", "issueCountry" ], "nullable": true }, "CNH": { "description": "Brazilian driver's license (CNH).", "type": "object", "properties": { "code": { "type": "string", "description": "Document number as printed, digits and letters only (no punctuation).", "example": "52998224725" }, "issueCountry": { "type": "string", "description": "Country that issued the document (ISO 3166-1 alpha-2). Always `BR` for `CPF`, `RG` and `CNH`.", "example": "BR" } }, "required": [ "code", "issueCountry" ], "nullable": true } }, "description": "Identity documents." }, "address": { "type": "object", "properties": { "shortAddress": { "type": "string", "description": "The address in a single line.", "example": "Av. Paulista, 1000 - Bela Vista, São Paulo - SP" }, "adressLines": { "type": "array", "items": { "type": "string", "example": "Av. Paulista, 1000" }, "description": "The address in postal lines. The field name is spelled `adressLines`.\n\n---\n\nExample: `[\"Av. Paulista, 1000\",\"Bela Vista\"]`" }, "locality": { "type": "string", "description": "City.", "example": "São Paulo" }, "administrativeArea": { "type": "string", "description": "State or province code.", "example": "SP" }, "administrativeAreaName": { "type": "string", "description": "State or province name.", "example": "São Paulo" }, "postalCode": { "type": "string", "description": "Postal code.", "example": "01310-100" }, "country": { "type": "string", "description": "Country (ISO 3166-1 alpha-2).", "example": "BR" }, "timezone": { "type": "string", "description": "IANA time zone of the address.", "example": "America/Sao_Paulo" }, "coordinates": { "type": "object", "properties": { "lat": { "type": "number", "description": "Latitude.", "example": -23.5614 }, "lng": { "type": "number", "description": "Longitude.", "example": -46.6559 } }, "required": [ "lat", "lng" ], "description": "Location of the address." } }, "required": [ "shortAddress", "adressLines", "locality", "administrativeArea", "administrativeAreaName", "postalCode", "country", "timezone", "coordinates" ], "description": "Home address." }, "loyalty": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Loyalty program numbers, keyed by carrier code. Omitted when there are none.\n\n---\n\nExample: `{\"LA\":\"123456789\"}`", "example": { "LA": "123456789" } }, "customFields": { "type": "object", "additionalProperties": {}, "description": "Values of the organization's passenger custom fields, keyed by the custom field's `slug`. Empty when none were set.\n\n---\n\nExample: `{\"cost-center\":\"CC-1020\"}`", "example": { "cost-center": "CC-1020" } }, "status": { "type": "string", "enum": [ "ACTIVE", "DELETED" ], "description": "Status of the passenger. Only `ACTIVE` passengers are returned.", "example": "ACTIVE" }, "createdAt": { "type": "string", "description": "When the passenger was created.", "example": "2026-10-01T13:45:12.000Z", "format": "date-time" }, "updatedAt": { "type": "string", "description": "When the passenger was last changed.", "example": "2026-10-01T13:45:12.000Z", "format": "date-time" } }, "required": [ "id", "realmId", "organizationId", "source", "profileComplete", "name", "gender", "birthDate", "emails", "phoneNumbers", "documents", "address", "customFields", "status" ], "description": "A passenger of the organization: a traveler who can be booked on trips." } } } }, "404": { "description": "`PASSENGER_NOT_FOUND` — No active passenger with this ID exists in the organization.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "PASSENGER_NOT_FOUND" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "TRAVEL" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b", "code": "PASSENGER_NOT_FOUND", "origin": "TRAVEL", "message": "Passenger not found" } } } }, "422": { "description": "`LINKED_FIELDS_READ_ONLY` — The passenger is linked to a user and the body changes `name`, `emails` or `documents.CPF`; `fields` lists each one.\n\n`INVALID_CUSTOM_FIELD` — A custom field value is invalid or a required one is missing.\n\n`BAD_REQUEST` — A path parameter is not a valid ID or the body failed validation; `fields` lists each offending field.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "LINKED_FIELDS_READ_ONLY", "INVALID_CUSTOM_FIELD", "BAD_REQUEST" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "TRAVEL" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." }, "fields": { "type": "array", "description": "One entry per invalid request field (validation errors only).", "items": { "type": "object", "properties": { "field": { "type": "string", "description": "Path of the invalid field, e.g. `label` or `values[0].value`.", "example": "label" }, "message": { "type": "string", "description": "Why the field was rejected.", "example": "label is required" }, "code": { "type": "string", "description": "`_` — e.g. `LABEL_REQUIRED`, `TYPE_ONE_OF`, `VALUES_VALUE_TYPE_ERROR`.", "example": "LABEL_REQUIRED" }, "values": { "type": "array", "items": { "type": "string" }, "description": "The accepted values, when the field is an enumeration." } }, "required": [ "field", "message", "code" ] } } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b", "code": "LINKED_FIELDS_READ_ONLY", "origin": "TRAVEL", "message": "The passenger is linked to a user and the body changes `name`, `emails` or `documents.CPF`; `fields` lists each one." } } } }, "503": { "description": "`PROVIDER_UNAVAILABLE` — The travel provider could not be reached; the passenger was not changed. Retry later.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "PROVIDER_UNAVAILABLE" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "TRAVEL" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b", "code": "PROVIDER_UNAVAILABLE", "origin": "TRAVEL", "message": "Travel provider temporarily unavailable, please retry." } } } } }, "x-p3-confidence": { "response": "generated:typed", "request": "generated:typed", "note": "`.refine(…)` constraint not represented (runtime-dependent value)" } } }, "/realms/{realmId}/trips": { "get": { "operationId": "getRealmsByRealmIdTrips", "summary": "List realm trips", "tags": [ "Trips" ], "x-p3-sidebar-order": 1, "description": "Lists every trip of the realm, across its organizations, newest first.", "x-mint": { "content": "Only an admin of the realm can list them (403 otherwise). Each trip carries the `organizationId` it belongs to. Filter by creation date, requester, passenger and the type, state or status of the trip. Paginated — see [Pagination](/api-reference/pagination)." }, "parameters": [ { "name": "realmId", "in": "path", "required": true, "description": "ID of the realm whose trips you want to list.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b" }, { "name": "from", "in": "query", "required": false, "description": "Only trips created on or after this day (`YYYY-MM-DD`, UTC).", "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "example": "2026-10-01" }, { "name": "to", "in": "query", "required": false, "description": "Only trips created on or before this day (`YYYY-MM-DD`, UTC), the whole day included.", "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "example": "2026-10-31" }, { "name": "vertical", "in": "query", "required": false, "description": "Only trips of this type.", "schema": { "type": "string", "enum": [ "AIR", "HOTEL", "BUS", "VEHICLE" ] }, "example": "AIR" }, { "name": "state", "in": "query", "required": false, "description": "Only trips in this state.", "schema": { "type": "string", "enum": [ "PENDING", "RESERVED", "ISSUED", "CANCELED" ] }, "example": "RESERVED" }, { "name": "status", "in": "query", "required": false, "description": "Only trips in this status.", "schema": { "type": "string", "enum": [ "PROCESSING_RESERVATION", "RESERVATION_FAILED", "RESERVED", "PROCESSING_ISSUE", "ISSUED", "PROCESSING_CANCELLATION", "CANCELED", "AWAITING_MANUAL_CANCELLATION", "CANCELLATION_FAILED", "FAILED", "FAILED_BY_INCONSISTENT_DATA", "FAILED_BY_UNAVAILABLE_RESOURCE", "FAILED_BY_BUDGET_EXCEEDED", "EXPIRED", "BLOCKED", "UNKNOWN", "ISSUANCE_FAILED" ] }, "example": "PROCESSING_RESERVATION" }, { "name": "createdBy", "in": "query", "required": false, "description": "Only trips created by this user (`createdBy`).", "schema": { "type": "string", "maxLength": 100 }, "example": "e3553bc1-5e20-4e17-b22a-a796fda0aa99" }, { "name": "passengerId", "in": "query", "required": false, "description": "Only trips the passenger travels on (24 hexadecimal characters).", "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$" }, "example": "6710a3f2c9e77b0012a4d5e1" }, { "name": "next", "in": "query", "required": false, "description": "Cursor returned as `next` by the previous page. Omit for the first page.", "schema": { "type": "string" }, "example": "eyJjIjoiMjAyNi0xMC0wMVQxMzo0NToxMi4wMDBaIiwiaSI6IjY3MTFiNGMwZDhlMWEzMDAxMmI3YzlmMiJ9" }, { "name": "limit", "in": "query", "required": false, "description": "Page size.", "schema": { "default": 15, "type": "integer", "minimum": 1, "maximum": 100 }, "example": 15 } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the trip.", "example": "6711b4c0d8e1a30012b7c9f2" }, "realmId": { "type": "string", "description": "ID of the realm the trip belongs to.", "example": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b", "format": "uuid" }, "organizationId": { "type": "string", "description": "ID of the organization the trip belongs to.", "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410", "format": "uuid" }, "createdBy": { "type": "string", "description": "ID of the user who created the trip. Omitted when a service did.", "example": "e3553bc1-5e20-4e17-b22a-a796fda0aa99", "format": "uuid" }, "customFields": { "type": "object", "additionalProperties": {}, "description": "Values of the organization's trip custom fields, keyed by the custom field's `slug`. Empty when none were set.\n\n---\n\nExample: `{\"cost-center\":\"CC-1020\"}`", "example": { "cost-center": "CC-1020" } }, "vertical": { "type": "string", "enum": [ "AIR", "HOTEL", "BUS", "VEHICLE" ], "description": "Type of product booked. It tells which shape `productSnapshot` has.", "example": "AIR" }, "state": { "type": "string", "enum": [ "PENDING", "RESERVED", "ISSUED", "CANCELED" ], "description": "Where the booking is in its life: `PENDING` while the reservation is being made, `RESERVED` once held (until `reservationExpiresAt`), `ISSUED` once ticketed and `CANCELED`. It only moves forward.", "example": "RESERVED" }, "status": { "type": "string", "enum": [ "PROCESSING_RESERVATION", "RESERVATION_FAILED", "RESERVED", "PROCESSING_ISSUE", "ISSUED", "PROCESSING_CANCELLATION", "CANCELED", "AWAITING_MANUAL_CANCELLATION", "CANCELLATION_FAILED", "FAILED", "FAILED_BY_INCONSISTENT_DATA", "FAILED_BY_UNAVAILABLE_RESOURCE", "FAILED_BY_BUDGET_EXCEEDED", "EXPIRED", "BLOCKED", "UNKNOWN", "ISSUANCE_FAILED" ], "description": "Finer-grained status: it also reports work in progress (`PROCESSING_*`) and failures, and can change back and forth. Use `state` to decide what the booking is; use `status` to tell what is happening to it.", "example": "RESERVED" }, "reservationExpiresAt": { "type": "string", "nullable": true, "description": "Until when the reservation is held. Past it, a trip that was not issued expires. `null` or omitted when there is no hold.", "example": "2026-10-02T13:45:12.000Z", "format": "date-time" }, "issuedAt": { "type": "string", "nullable": true, "description": "When the trip was issued. `null` or omitted until it is.", "format": "date-time" }, "originalAmount": { "type": "number", "description": "Price before discounts, in cents. Omitted until the price is known.", "example": 95000 }, "discountAmount": { "type": "number", "description": "Discount applied, in cents. Omitted until the price is known.", "example": 3010 }, "feeAmount": { "type": "number", "description": "Fees added, in cents. Omitted until the price is known.", "example": 0 }, "totalAmount": { "type": "number", "description": "Amount to pay, in cents: `originalAmount` - `discountAmount` + `feeAmount`. Omitted until the price is known.", "example": 91990 }, "currency": { "type": "string", "description": "Currency of the amounts, as the numeric ISO 4217 code (`986` is BRL).", "example": "986" }, "passengers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the passenger, as returned by the passenger endpoints.", "example": "6710a3f2c9e77b0012a4d5e1" }, "userId": { "type": "string", "description": "ID of the organization user the passenger is linked to. Omitted for a passenger who is not a user. A user sees the trips they travel on.", "example": "e3553bc1-5e20-4e17-b22a-a796fda0aa99", "format": "uuid" }, "lead": { "type": "boolean", "description": "Whether this passenger is the one responsible for the reservation.", "example": true }, "name": { "type": "string", "description": "Full name, as it appears on the passenger's travel documents.", "example": "Mariana Costa" }, "gender": { "type": "string", "enum": [ "MALE", "FEMALE" ], "description": "Gender.", "example": "FEMALE" }, "birthDate": { "type": "string", "description": "Date of birth (`YYYY-MM-DD`).", "example": "1990-04-17" } }, "required": [ "id", "lead", "name", "gender", "birthDate" ], "description": "A passenger of a trip: who travels, as recorded when the trip was booked. The passenger endpoints serve the full profile." }, "description": "The passengers booked on the trip." }, "productSnapshot": { "anyOf": [ { "type": "object", "properties": { "journeys": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the journey, referenced by `tickets[].fares[].journeyId`.", "example": "jour_V1StGXR8Z5jdHi6BmyT2k" }, "direction": { "type": "string", "enum": [ "DEPARTURE", "RETURN" ], "description": "Whether this is the outbound leg (`DEPARTURE`) or the return leg (`RETURN`).", "example": "DEPARTURE" }, "origin": { "type": "object", "properties": { "iata": { "type": "string", "description": "IATA code of the airport, 3 letters.", "example": "GRU" }, "name": { "type": "string", "nullable": true, "description": "Official name of the airport. `null` when unknown.", "example": "São Paulo/Guarulhos International Airport" }, "shortAddress": { "type": "string", "nullable": true, "description": "Readable single-line address of the airport. `null` when unknown.", "example": "Guarulhos, SP, Brazil" }, "locality": { "type": "string", "nullable": true, "description": "City the airport sits in. `null` when unknown.", "example": "Guarulhos" }, "administrativeArea": { "type": "string", "nullable": true, "description": "State, as its short code. `null` when unknown.", "example": "SP" }, "phoneNumbers": { "type": "array", "items": { "type": "string", "example": "551133334444" }, "description": "Contact phone numbers of the airport, digits only. Empty when none is registered.\n\n---\n\nExample: `[\"551133334444\"]`" } }, "required": [ "iata", "name", "shortAddress", "locality", "administrativeArea", "phoneNumbers" ], "description": "Airport the journey starts at." }, "destination": { "type": "object", "properties": { "iata": { "type": "string", "description": "IATA code of the airport, 3 letters.", "example": "GRU" }, "name": { "type": "string", "nullable": true, "description": "Official name of the airport. `null` when unknown.", "example": "São Paulo/Guarulhos International Airport" }, "shortAddress": { "type": "string", "nullable": true, "description": "Readable single-line address of the airport. `null` when unknown.", "example": "Guarulhos, SP, Brazil" }, "locality": { "type": "string", "nullable": true, "description": "City the airport sits in. `null` when unknown.", "example": "Guarulhos" }, "administrativeArea": { "type": "string", "nullable": true, "description": "State, as its short code. `null` when unknown.", "example": "SP" }, "phoneNumbers": { "type": "array", "items": { "type": "string", "example": "551133334444" }, "description": "Contact phone numbers of the airport, digits only. Empty when none is registered.\n\n---\n\nExample: `[\"551133334444\"]`" } }, "required": [ "iata", "name", "shortAddress", "locality", "administrativeArea", "phoneNumbers" ], "description": "Airport the journey ends at.", "example": { "iata": "SDU", "name": "Rio de Janeiro/Santos Dumont Airport", "shortAddress": "Rio de Janeiro, RJ, Brazil", "locality": "Rio de Janeiro", "administrativeArea": "RJ", "phoneNumbers": [ "552133339999" ] } }, "departureDate": { "type": "string", "description": "Departure date and time in the local time of the origin airport, as `YYYY-MM-DDTHH:mm:ss` with no time zone.", "example": "2026-11-02T08:30:00" }, "arrivalDate": { "type": "string", "description": "Arrival date and time in the local time of the destination airport, as `YYYY-MM-DDTHH:mm:ss` with no time zone.", "example": "2026-11-02T09:35:00" }, "duration": { "type": "string", "description": "Total travel time of the journey, connections included, as `HH:mm`.", "example": "01:05" }, "segments": { "type": "array", "items": { "type": "object", "properties": { "airline": { "type": "object", "properties": { "code": { "type": "string", "description": "IATA code of the airline.", "example": "LA" }, "name": { "type": "string", "nullable": true, "description": "Commercial name of the airline. `null` when unknown.", "example": "LATAM Airlines" }, "logo": { "type": "string", "nullable": true, "description": "URL of the airline's logo. `null` when there is none.", "example": "https://cdn.example.com/airlines/LA.png" } }, "required": [ "code", "name", "logo" ], "description": "Airline that sells the flight." }, "operation": { "type": "object", "properties": { "code": { "type": "string", "description": "IATA code of the airline.", "example": "LA" }, "name": { "type": "string", "nullable": true, "description": "Commercial name of the airline. `null` when unknown.", "example": "LATAM Airlines" }, "logo": { "type": "string", "nullable": true, "description": "URL of the airline's logo. `null` when there is none.", "example": "https://cdn.example.com/airlines/LA.png" } }, "required": [ "code", "name", "logo" ], "description": "Airline that operates the flight. It differs from `airline` on codeshare flights." }, "origin": { "type": "object", "properties": { "iata": { "type": "string", "description": "IATA code of the airport, 3 letters.", "example": "GRU" }, "name": { "type": "string", "nullable": true, "description": "Official name of the airport. `null` when unknown.", "example": "São Paulo/Guarulhos International Airport" }, "shortAddress": { "type": "string", "nullable": true, "description": "Readable single-line address of the airport. `null` when unknown.", "example": "Guarulhos, SP, Brazil" }, "locality": { "type": "string", "nullable": true, "description": "City the airport sits in. `null` when unknown.", "example": "Guarulhos" }, "administrativeArea": { "type": "string", "nullable": true, "description": "State, as its short code. `null` when unknown.", "example": "SP" }, "phoneNumbers": { "type": "array", "items": { "type": "string", "example": "551133334444" }, "description": "Contact phone numbers of the airport, digits only. Empty when none is registered.\n\n---\n\nExample: `[\"551133334444\"]`" } }, "required": [ "iata", "name", "shortAddress", "locality", "administrativeArea", "phoneNumbers" ], "description": "Airport the flight leaves from." }, "destination": { "type": "object", "properties": { "iata": { "type": "string", "description": "IATA code of the airport, 3 letters.", "example": "GRU" }, "name": { "type": "string", "nullable": true, "description": "Official name of the airport. `null` when unknown.", "example": "São Paulo/Guarulhos International Airport" }, "shortAddress": { "type": "string", "nullable": true, "description": "Readable single-line address of the airport. `null` when unknown.", "example": "Guarulhos, SP, Brazil" }, "locality": { "type": "string", "nullable": true, "description": "City the airport sits in. `null` when unknown.", "example": "Guarulhos" }, "administrativeArea": { "type": "string", "nullable": true, "description": "State, as its short code. `null` when unknown.", "example": "SP" }, "phoneNumbers": { "type": "array", "items": { "type": "string", "example": "551133334444" }, "description": "Contact phone numbers of the airport, digits only. Empty when none is registered.\n\n---\n\nExample: `[\"551133334444\"]`" } }, "required": [ "iata", "name", "shortAddress", "locality", "administrativeArea", "phoneNumbers" ], "description": "Airport the flight arrives at.", "example": { "iata": "SDU", "name": "Rio de Janeiro/Santos Dumont Airport", "shortAddress": "Rio de Janeiro, RJ, Brazil", "locality": "Rio de Janeiro", "administrativeArea": "RJ", "phoneNumbers": [ "552133339999" ] } }, "flightNumber": { "type": "string", "description": "Number of the flight, without the airline's code.", "example": "3101" }, "departureDate": { "type": "string", "description": "Departure date and time in the local time of the departure airport, as `YYYY-MM-DDTHH:mm:ss` with no time zone.", "example": "2026-11-02T08:30:00" }, "arrivalDate": { "type": "string", "description": "Arrival date and time in the local time of the arrival airport, as `YYYY-MM-DDTHH:mm:ss` with no time zone.", "example": "2026-11-02T09:35:00" }, "flightType": { "type": "string", "enum": [ "CHARTER", "ALLOTMENT", "REGULAR" ], "description": "Kind of flight: `REGULAR`, `CHARTER` or `ALLOTMENT`.", "example": "REGULAR" }, "duration": { "type": "string", "description": "Duration of the flight, as `HH:mm`.", "example": "01:05" }, "equipment": { "type": "string", "nullable": true, "description": "Aircraft scheduled for the flight, as the airline identifies it. `null` when not informed.", "example": "32Q" }, "cabin": { "type": "string", "enum": [ "ECONOMY", "PREMIUM_ECONOMY", "BUSINESS", "FIRST_CLASS", "UNDEFINED" ], "description": "Cabin booked for the flight.", "example": "ECONOMY" }, "class": { "type": "string", "nullable": true, "description": "Booking class (RBD) priced for the flight. Each airline defines its own codes. `null` when the airline does not expose it.", "example": "Y" }, "fareBasis": { "type": "string", "nullable": true, "description": "Fare basis code priced for the flight. Each airline defines its own codes. `null` when the airline does not expose it.", "example": "YOW" }, "flightInfo": { "description": "Live information about the flight. `null` until it is first collected, as the departure approaches.", "example": null, "type": "object", "properties": { "state": { "type": "string", "nullable": true, "enum": [ "SCHEDULED", "OUT_GATE", "IN_AIR", "LANDED", "IN_GATE", "CANCELED", "PROPOSED", "UNKNOWN", null ], "description": "Operational state of the flight. `null` when there is no live status yet.", "example": "SCHEDULED" }, "updatedAt": { "type": "string", "nullable": true, "description": "When the live status was captured. `null` when there is no live status yet.", "example": "2026-11-01T18:00:00.000Z" }, "aircraft": { "description": "Aircraft operating the flight. `null` when not known yet.", "type": "object", "properties": { "registration": { "type": "string", "nullable": true, "description": "Tail registration of the aircraft. `null` when not known yet.", "example": "PR-XBA" }, "type": { "type": "string", "nullable": true, "description": "ICAO code of the aircraft type. `null` when not known yet.", "example": "A21N" } }, "required": [ "registration", "type" ], "nullable": true }, "departure": { "type": "object", "properties": { "terminal": { "type": "string", "nullable": true, "description": "Terminal at the airport. `null` when not reported yet.", "example": "2" }, "gate": { "type": "string", "nullable": true, "description": "Gate at the airport. `null` when not reported yet.", "example": "B12" }, "baggage": { "type": "string", "nullable": true, "description": "Baggage belt, reported for arrivals only. `null` for departures and when not reported yet.", "example": "04" }, "estimatedTime": { "type": "string", "nullable": true, "description": "Estimated time at the gate, in UTC (ISO 8601). `null` when not known yet.", "example": "2026-11-02T11:30:00.000Z" }, "actualTime": { "type": "string", "nullable": true, "description": "Actual time at the gate, in UTC (ISO 8601), reported once the flight operates. `null` before that.", "example": "2026-11-02T11:34:00.000Z" }, "timeliness": { "type": "string", "nullable": true, "description": "Punctuality of the flight, such as `OnTime`, `Early` or `Delayed`. `null` when not known.", "example": "OnTime" }, "delayMinutes": { "type": "number", "nullable": true, "description": "Delay in minutes; negative when the flight is ahead of schedule. `null` when not known.", "example": 4 } }, "required": [ "terminal", "gate", "baggage", "estimatedTime", "actualTime", "timeliness", "delayMinutes" ], "description": "Live status at the departure airport." }, "arrival": { "type": "object", "properties": { "terminal": { "type": "string", "nullable": true, "description": "Terminal at the airport. `null` when not reported yet.", "example": "2" }, "gate": { "type": "string", "nullable": true, "description": "Gate at the airport. `null` when not reported yet.", "example": "B12" }, "baggage": { "type": "string", "nullable": true, "description": "Baggage belt, reported for arrivals only. `null` for departures and when not reported yet.", "example": "04" }, "estimatedTime": { "type": "string", "nullable": true, "description": "Estimated time at the gate, in UTC (ISO 8601). `null` when not known yet.", "example": "2026-11-02T11:30:00.000Z" }, "actualTime": { "type": "string", "nullable": true, "description": "Actual time at the gate, in UTC (ISO 8601), reported once the flight operates. `null` before that.", "example": "2026-11-02T11:34:00.000Z" }, "timeliness": { "type": "string", "nullable": true, "description": "Punctuality of the flight, such as `OnTime`, `Early` or `Delayed`. `null` when not known.", "example": "OnTime" }, "delayMinutes": { "type": "number", "nullable": true, "description": "Delay in minutes; negative when the flight is ahead of schedule. `null` when not known.", "example": 4 } }, "required": [ "terminal", "gate", "baggage", "estimatedTime", "actualTime", "timeliness", "delayMinutes" ], "description": "Live status at the arrival airport." } }, "required": [ "state", "updatedAt", "aircraft", "departure", "arrival" ], "nullable": true } }, "required": [ "airline", "operation", "origin", "destination", "flightNumber", "departureDate", "arrivalDate", "flightType", "duration", "equipment", "cabin", "class", "fareBasis", "flightInfo" ], "description": "One flight of a journey. A journey with connections has several." }, "description": "Flights of the journey, in chronological order, connections included." } }, "required": [ "id", "direction", "origin", "destination", "departureDate", "arrivalDate", "duration", "segments" ], "description": "One leg of the itinerary: the whole way from an origin to a destination, connections included." }, "description": "Legs of the itinerary, in travel order: one for a one-way trip, two (outbound and return) for a round trip." }, "tickets": { "type": "array", "items": { "type": "object", "properties": { "passengerId": { "type": "string", "description": "ID of the passenger holding this ticket — one of the trip's `passengers[]`. Omitted only if the passenger could not be matched to the trip's passengers.", "example": "6710a3f2c9e77b0012a4d5e1" }, "fareDescription": { "type": "string", "description": "Readable description of the fare of the ticket.", "example": "GRU to SDU, LATAM Airlines, Economy" }, "ticketNumber": { "type": "string", "nullable": true, "description": "Number of the ticket, as the airline issued it. `null` until the ticket is issued.", "example": null }, "fares": { "type": "array", "items": { "type": "object", "properties": { "journeyId": { "type": "string", "nullable": true, "description": "ID of the journey this fare covers — a `journeys[].id`. `null` when the fare covers the whole itinerary.", "example": "jour_V1StGXR8Z5jdHi6BmyT2k" }, "currency": { "type": "string", "description": "Currency, as the ISO 4217 alphabetic code.", "example": "BRL" }, "originalAmount": { "type": "number", "description": "Fare before discounts and fees, in cents.", "example": 95000 }, "discountAmount": { "type": "number", "description": "Discount applied to the fare, in cents.", "example": 3010 }, "feeAmount": { "type": "number", "description": "Fees added to the fare, in cents.", "example": 0 }, "amount": { "type": "number", "description": "Total charged for the fare, in cents: `originalAmount` - `discountAmount` + `feeAmount`.", "example": 91990 }, "cancellationPolicies": { "type": "object", "properties": { "refundable": { "type": "boolean", "description": "Whether cancelling gives any money back.", "example": true }, "immediateFine": { "type": "boolean", "description": "Whether a fine applies to a cancellation made right after the booking.", "example": false }, "penalties": { "type": "array", "items": { "type": "object", "properties": { "from": { "type": "string", "description": "First day (`YYYY-MM-DD`) on which this tier applies.", "example": "2026-10-25" }, "currency": { "type": "string", "description": "Currency, as the ISO 4217 alphabetic code.", "example": "BRL" }, "fineAmount": { "type": "number", "nullable": true, "description": "Fine charged for cancelling from `from` onward, in cents. `null` when the amount is not available.", "example": 15000 } }, "required": [ "from", "currency", "fineAmount" ], "description": "One tier of a cancellation penalty schedule." }, "description": "Penalty tiers, each in effect from its own date. Empty when no scheduled penalty applies." } }, "required": [ "refundable", "immediateFine", "penalties" ], "description": "Cancellation rules of the fare." }, "changePolicies": { "type": "object", "properties": { "canChange": { "type": "boolean", "description": "Whether the fare allows the booking to be changed.", "example": true }, "immediateFine": { "type": "boolean", "description": "Whether a fine applies to a change made right after the booking.", "example": false }, "penalties": { "type": "array", "items": { "type": "object", "properties": { "from": { "type": "string", "description": "First day (`YYYY-MM-DD`) on which this tier applies.", "example": "2026-10-25" }, "currency": { "type": "string", "description": "Currency, as the ISO 4217 alphabetic code.", "example": "BRL" }, "fineAmount": { "type": "number", "nullable": true, "description": "Fine charged for changing the booking from `from` onward, in cents. `null` when the amount is not available.", "example": 8000 } }, "required": [ "from", "currency", "fineAmount" ], "description": "One tier of a change penalty schedule." }, "description": "Penalty tiers, each in effect from its own date. Empty when no scheduled penalty applies." } }, "required": [ "canChange", "immediateFine", "penalties" ], "description": "Change rules of the fare." } }, "required": [ "journeyId", "currency", "originalAmount", "discountAmount", "feeAmount", "amount", "cancellationPolicies", "changePolicies" ], "description": "The fare of a ticket for one journey, or for the whole itinerary. Amounts are integers in cents." }, "description": "Fares of the ticket: one per journey, or a single one for the whole itinerary." }, "segments": { "type": "array", "items": { "type": "object", "properties": { "flightNumber": { "type": "string", "description": "Number of the flight this ticket covers, without the airline's code. It matches the `flightNumber` of one of the journeys' `segments`.", "example": "3101" }, "cabin": { "type": "string", "enum": [ "ECONOMY", "PREMIUM_ECONOMY", "BUSINESS", "FIRST_CLASS", "UNDEFINED" ], "description": "Cabin of the ticket on this flight.", "example": "ECONOMY" }, "class": { "type": "string", "nullable": true, "description": "Booking class (RBD) of the ticket on this flight. Each airline defines its own codes. `null` when the airline does not expose it.", "example": "Y" }, "fareBasis": { "type": "string", "nullable": true, "description": "Fare basis code of the ticket on this flight. Each airline defines its own codes. `null` when the airline does not expose it.", "example": "YOW" }, "baggages": { "type": "array", "items": { "type": "object", "properties": { "quantity": { "type": "number", "description": "Number of pieces included in the allowance.", "example": 1 }, "weight": { "type": "number", "nullable": true, "description": "Weight allowed per piece, in kg. `null` when the airline sets no weight limit per piece.", "example": 23 }, "type": { "type": "string", "enum": [ "CHECKED", "CARRY_ON", "PERSONAL_ITEM" ], "description": "Kind of baggage: `CHECKED`, `CARRY_ON` or `PERSONAL_ITEM`.", "example": "CHECKED" } }, "required": [ "quantity", "weight", "type" ], "description": "A baggage allowance of a ticket on one flight." }, "description": "Baggage allowance of the ticket on this flight. Empty for an infant on an adult's lap." } }, "required": [ "flightNumber", "cabin", "class", "fareBasis", "baggages" ], "description": "What a ticket covers on one flight of the itinerary: the cabin, the fare codes and the baggage allowance." }, "description": "What the ticket covers on each flight of the itinerary." } }, "required": [ "fareDescription", "ticketNumber", "fares", "segments" ], "description": "The ticket of one passenger. It covers the whole itinerary, with a fare per journey or a single fare for all of it." }, "description": "Tickets of the booking, one per passenger, each covering the whole itinerary." }, "locators": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "Kind of reference, such as `PNR` for an airline's booking code.", "example": "PNR" }, "code": { "type": "string", "description": "The reference itself, as the supplier issued it.", "example": "ABC123" } }, "required": [ "type", "code" ], "description": "A reference that identifies the booking with the supplier, such as an airline's booking code." }, "description": "Booking references issued by the airlines. Empty until the reservation is confirmed." }, "flightInfoUpdatedAt": { "type": "string", "nullable": true, "description": "When the live flight information was last collected. `null` until it is first collected.", "example": null, "format": "date-time" } }, "required": [ "journeys", "tickets", "locators", "flightInfoUpdatedAt" ], "description": "The booked flight: itinerary, the ticket of each passenger (by ID) with its fares and baggage, and reservation locators. This is the shape of `productSnapshot` when the trip's `vertical` is `AIR`. Amounts are integers in cents.", "title": "Air trip" }, { "type": "object", "properties": { "hotel": { "type": "object", "properties": { "name": { "type": "string", "description": "Official name of the hotel.", "example": "Hotel Paulista Plaza" }, "chain": { "type": "object", "properties": { "brandName": { "type": "string", "nullable": true, "description": "Brand within the chain. `null` when not informed.", "example": "Ibis" }, "chainName": { "type": "string", "nullable": true, "description": "Name of the chain. `null` for an independent hotel.", "example": "Accor" }, "logo": { "type": "string", "nullable": true, "description": "URL of the chain's logo. `null` when the hotel has no chain with a registered logo.", "example": "https://cdn.example.com/hotels/ibis.svg" } }, "required": [ "brandName", "chainName", "logo" ], "description": "Chain and brand of the hotel." }, "shortAddress": { "type": "string", "nullable": true, "description": "Readable single-line address of the hotel. `null` when unknown.", "example": "Av. Paulista, 1500, São Paulo, SP, Brazil" }, "phoneNumbers": { "type": "array", "items": { "type": "string", "example": "551133335555" }, "description": "Contact phone numbers of the hotel, digits only. Empty when none is registered.\n\n---\n\nExample: `[\"551133335555\"]`" }, "locality": { "type": "string", "nullable": true, "description": "City the hotel sits in. `null` when unknown.", "example": "São Paulo" }, "administrativeArea": { "type": "string", "nullable": true, "description": "State, as its short code. `null` when unknown.", "example": "SP" }, "checkInTime": { "type": "string", "nullable": true, "description": "Time of day, in the hotel's local time (`HH:mm`), from which guests can check in. `null` when unknown.", "example": "14:00" }, "checkOutTime": { "type": "string", "nullable": true, "description": "Time of day, in the hotel's local time (`HH:mm`), by which guests must check out. `null` when unknown.", "example": "12:00" } }, "required": [ "name", "chain", "shortAddress", "phoneNumbers", "locality", "administrativeArea", "checkInTime", "checkOutTime" ], "description": "Hotel where the stay is booked." }, "checkIn": { "type": "string", "description": "Check-in date (`YYYY-MM-DD`).", "example": "2026-11-02" }, "checkOut": { "type": "string", "description": "Check-out date (`YYYY-MM-DD`).", "example": "2026-11-04" }, "rooms": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the room, as the hotel offers it.", "example": "Standard Room, 1 Queen Bed" }, "fare": { "type": "object", "properties": { "currency": { "type": "string", "description": "Currency, as the ISO 4217 alphabetic code.", "example": "BRL" }, "originalAmount": { "type": "number", "description": "Fare before discounts and fees, in cents.", "example": 120000 }, "discountAmount": { "type": "number", "description": "Discount applied to the fare, in cents.", "example": 8000 }, "feeAmount": { "type": "number", "description": "Fees added to the fare, in cents.", "example": 0 }, "amount": { "type": "number", "description": "Total charged for the fare, in cents: `originalAmount` - `discountAmount` + `feeAmount`.", "example": 112000 }, "boardType": { "type": "string", "enum": [ "ONLY_ROOM", "BREAKFAST", "HALF_BOARD", "FULL_BOARD", "ALL_INCLUSIVE" ], "description": "Meals included in the fare.", "example": "BREAKFAST" }, "cancellationPolicies": { "type": "object", "properties": { "refundable": { "type": "boolean", "description": "Whether cancelling gives any money back.", "example": true }, "immediateFine": { "type": "boolean", "description": "Whether a fine applies to a cancellation made right after the booking.", "example": false }, "penalties": { "type": "array", "items": { "type": "object", "properties": { "from": { "type": "string", "description": "First day (`YYYY-MM-DD`) on which this tier applies.", "example": "2026-10-25" }, "currency": { "type": "string", "description": "Currency, as the ISO 4217 alphabetic code.", "example": "BRL" }, "fineAmount": { "type": "number", "nullable": true, "description": "Fine charged for cancelling from `from` onward, in cents. `null` when the amount is not available.", "example": 15000 } }, "required": [ "from", "currency", "fineAmount" ], "description": "One tier of a cancellation penalty schedule." }, "description": "Penalty tiers, each in effect from its own date. Empty when no scheduled penalty applies." } }, "required": [ "refundable", "immediateFine", "penalties" ], "description": "Cancellation rules of the fare." } }, "required": [ "currency", "originalAmount", "discountAmount", "feeAmount", "amount", "boardType", "cancellationPolicies" ], "description": "Fare of the room." }, "passengersId": { "type": "array", "items": { "type": "string", "example": "6710a3f2c9e77b0012a4d5e1" }, "description": "IDs of the passengers staying in this room — the trip's `passengers[]`.\n\n---\n\nExample: `[\"6710a3f2c9e77b0012a4d5e1\"]`" } }, "required": [ "name", "fare", "passengersId" ], "description": "A booked room." }, "description": "Rooms booked for the stay." }, "locators": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "Kind of reference, such as `PNR` for an airline's booking code.", "example": "PNR" }, "code": { "type": "string", "description": "The reference itself, as the supplier issued it.", "example": "ABC123" } }, "required": [ "type", "code" ], "description": "A reference that identifies the booking with the supplier, such as an airline's booking code." }, "description": "Booking references issued by the hotel. Empty until the reservation is confirmed." } }, "required": [ "hotel", "checkIn", "checkOut", "rooms", "locators" ], "description": "The booked hotel stay: the hotel, the dates, the rooms with their fares and guests (by ID), and the reservation locators. This is the shape of `productSnapshot` when the trip's `vertical` is `HOTEL`. Amounts are integers in cents.", "title": "Hotel trip" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "DIRECT", "CONNECTION", "ONE_STOP" ], "description": "Kind of trip: `DIRECT`, `CONNECTION` or `ONE_STOP`.", "example": "DIRECT" }, "origin": { "type": "object", "properties": { "locality": { "type": "string", "description": "City the station sits in.", "example": "São Paulo" }, "administrativeArea": { "type": "string", "description": "State, as its short code.", "example": "SP" }, "name": { "type": "string", "nullable": true, "description": "Official name of the station. `null` when unknown.", "example": "Terminal Rodoviário Tietê" }, "shortAddress": { "type": "string", "nullable": true, "description": "Readable single-line address of the station. `null` when unknown.", "example": "Av. Cruzeiro do Sul, 1800, São Paulo, SP, Brazil" }, "phoneNumbers": { "type": "array", "items": { "type": "string", "example": "551133336666" }, "description": "Contact phone numbers of the station, digits only. Empty when none is registered.\n\n---\n\nExample: `[\"551133336666\"]`" } }, "required": [ "locality", "administrativeArea", "name", "shortAddress", "phoneNumbers" ], "description": "Station the trip starts at." }, "destination": { "type": "object", "properties": { "locality": { "type": "string", "description": "City the station sits in.", "example": "São Paulo" }, "administrativeArea": { "type": "string", "description": "State, as its short code.", "example": "SP" }, "name": { "type": "string", "nullable": true, "description": "Official name of the station. `null` when unknown.", "example": "Terminal Rodoviário Tietê" }, "shortAddress": { "type": "string", "nullable": true, "description": "Readable single-line address of the station. `null` when unknown.", "example": "Av. Cruzeiro do Sul, 1800, São Paulo, SP, Brazil" }, "phoneNumbers": { "type": "array", "items": { "type": "string", "example": "551133336666" }, "description": "Contact phone numbers of the station, digits only. Empty when none is registered.\n\n---\n\nExample: `[\"551133336666\"]`" } }, "required": [ "locality", "administrativeArea", "name", "shortAddress", "phoneNumbers" ], "description": "Station the trip ends at.", "example": { "locality": "Rio de Janeiro", "administrativeArea": "RJ", "name": "Rodoviária Novo Rio", "shortAddress": "Av. Francisco Bicalho, 1, Rio de Janeiro, RJ, Brazil", "phoneNumbers": [ "552133338888" ] } }, "departureDate": { "type": "string", "description": "Departure date and time in the local time of the origin station, as `YYYY-MM-DDTHH:mm:ss` with no time zone.", "example": "2026-11-02T08:30:00" }, "arrivalDate": { "type": "string", "description": "Arrival date and time in the local time of the destination station, as `YYYY-MM-DDTHH:mm:ss` with no time zone.", "example": "2026-11-02T14:45:00" }, "company": { "type": "object", "properties": { "name": { "type": "string", "description": "Commercial name of the company.", "example": "Expresso Brasileiro" }, "logo": { "type": "string", "nullable": true, "description": "URL of the company's logo. `null` when there is none.", "example": "https://cdn.example.com/bus/expresso-brasileiro.png" } }, "required": [ "name", "logo" ], "description": "Company that operates the trip." }, "passengerId": { "type": "string", "description": "ID of the passenger travelling on this ticket — one of the trip's `passengers[]`. Omitted only if the passenger could not be matched to the trip's passengers.", "example": "6710a3f2c9e77b0012a4d5e1" }, "segments": { "type": "array", "items": { "type": "object", "properties": { "seatNumber": { "type": "number", "description": "Seat reserved on the segment.", "example": 12 }, "serviceClass": { "type": "string", "enum": [ "SLEEPER_BED", "BED", "SEMI_BED", "EXECUTIVE", "CONVENTIONAL", "UNDEFINED" ], "description": "Class of service booked for the segment.", "example": "EXECUTIVE" }, "origin": { "type": "object", "properties": { "locality": { "type": "string", "description": "City the station sits in.", "example": "São Paulo" }, "administrativeArea": { "type": "string", "description": "State, as its short code.", "example": "SP" }, "name": { "type": "string", "nullable": true, "description": "Official name of the station. `null` when unknown.", "example": "Terminal Rodoviário Tietê" }, "shortAddress": { "type": "string", "nullable": true, "description": "Readable single-line address of the station. `null` when unknown.", "example": "Av. Cruzeiro do Sul, 1800, São Paulo, SP, Brazil" }, "phoneNumbers": { "type": "array", "items": { "type": "string", "example": "551133336666" }, "description": "Contact phone numbers of the station, digits only. Empty when none is registered.\n\n---\n\nExample: `[\"551133336666\"]`" } }, "required": [ "locality", "administrativeArea", "name", "shortAddress", "phoneNumbers" ], "description": "Station the segment leaves from." }, "destination": { "type": "object", "properties": { "locality": { "type": "string", "description": "City the station sits in.", "example": "São Paulo" }, "administrativeArea": { "type": "string", "description": "State, as its short code.", "example": "SP" }, "name": { "type": "string", "nullable": true, "description": "Official name of the station. `null` when unknown.", "example": "Terminal Rodoviário Tietê" }, "shortAddress": { "type": "string", "nullable": true, "description": "Readable single-line address of the station. `null` when unknown.", "example": "Av. Cruzeiro do Sul, 1800, São Paulo, SP, Brazil" }, "phoneNumbers": { "type": "array", "items": { "type": "string", "example": "551133336666" }, "description": "Contact phone numbers of the station, digits only. Empty when none is registered.\n\n---\n\nExample: `[\"551133336666\"]`" } }, "required": [ "locality", "administrativeArea", "name", "shortAddress", "phoneNumbers" ], "description": "Station the segment arrives at.", "example": { "locality": "Rio de Janeiro", "administrativeArea": "RJ", "name": "Rodoviária Novo Rio", "shortAddress": "Av. Francisco Bicalho, 1, Rio de Janeiro, RJ, Brazil", "phoneNumbers": [ "552133338888" ] } }, "departureDate": { "type": "string", "description": "Departure date and time in the local time of the origin station, as `YYYY-MM-DDTHH:mm:ss` with no time zone.", "example": "2026-11-02T08:30:00" }, "arrivalDate": { "type": "string", "description": "Arrival date and time in the local time of the destination station, as `YYYY-MM-DDTHH:mm:ss` with no time zone.", "example": "2026-11-02T14:45:00" }, "duration": { "type": "string", "nullable": true, "description": "Duration of the leg, as `HH:mm`. `null` when not available.", "example": "06:15" }, "fare": { "type": "object", "properties": { "originalAmount": { "type": "number", "description": "Fare before discounts and fees, in cents.", "example": 18000 }, "discountAmount": { "type": "number", "description": "Discount applied to the fare, in cents.", "example": 1000 }, "feeAmount": { "type": "number", "description": "Fees added to the fare, in cents.", "example": 500 }, "amount": { "type": "number", "description": "Total charged for the fare, in cents: `originalAmount` - `discountAmount` + `feeAmount`.", "example": 17500 }, "currency": { "type": "string", "description": "Currency, as the ISO 4217 alphabetic code.", "example": "BRL" }, "cancellationPolicies": { "type": "object", "properties": { "refundable": { "type": "boolean", "description": "Whether cancelling gives any money back.", "example": true }, "immediateFine": { "type": "boolean", "description": "Whether a fine applies to a cancellation made right after the booking.", "example": false }, "penalties": { "type": "array", "items": { "type": "object", "properties": { "from": { "type": "string", "description": "First day (`YYYY-MM-DD`) on which this tier applies.", "example": "2026-10-25" }, "currency": { "type": "string", "description": "Currency, as the ISO 4217 alphabetic code.", "example": "BRL" }, "fineAmount": { "type": "number", "nullable": true, "description": "Fine charged for cancelling from `from` onward, in cents. `null` when the amount is not available.", "example": 15000 } }, "required": [ "from", "currency", "fineAmount" ], "description": "One tier of a cancellation penalty schedule." }, "description": "Penalty tiers, each in effect from its own date. Empty when no scheduled penalty applies." } }, "required": [ "refundable", "immediateFine", "penalties" ], "description": "Cancellation rules of the fare." } }, "required": [ "originalAmount", "discountAmount", "feeAmount", "amount", "currency", "cancellationPolicies" ], "description": "Fare of the segment." }, "company": { "type": "object", "properties": { "name": { "type": "string", "description": "Commercial name of the company.", "example": "Expresso Brasileiro" }, "logo": { "type": "string", "nullable": true, "description": "URL of the company's logo. `null` when there is none.", "example": "https://cdn.example.com/bus/expresso-brasileiro.png" } }, "required": [ "name", "logo" ], "description": "Operator running this leg." } }, "required": [ "seatNumber", "serviceClass", "origin", "destination", "departureDate", "arrivalDate", "duration", "fare", "company" ], "description": "One leg of the bus trip, with the seat booked on it." }, "description": "Segments of the trip, one per leg, each with its seat, fare and operator." }, "routeDirection": { "type": "string", "enum": [ "DEPARTURE", "RETURN" ], "description": "Whether this booking is the outbound trip (`DEPARTURE`) or the return trip (`RETURN`).", "example": "DEPARTURE" }, "boardingInfo": { "description": "Boarding pass and, per leg, platform and ticket codes. `null` until it is first collected, as the departure approaches.", "example": null, "type": "object", "properties": { "boardingPass": { "type": "string", "nullable": true, "description": "The boarding pass PDF, base64-encoded. `null` when not available yet.", "example": "JVBERi0xLjcK" }, "routes": { "type": "array", "items": { "type": "object", "properties": { "origin": { "type": "string", "description": "City the leg starts in.", "example": "São Paulo" }, "destination": { "type": "string", "description": "City the leg ends in.", "example": "Rio de Janeiro" }, "platform": { "type": "string", "nullable": true, "description": "Boarding platform at the origin station. `null` when not assigned or not applicable.", "example": "14" }, "departureDate": { "type": "string", "description": "Departure date and time in local time, as `YYYY-MM-DDTHH:mm:ss` with no time zone.", "example": "2026-11-02T08:30:00" }, "arrivalDate": { "type": "string", "description": "Arrival date and time in local time, as `YYYY-MM-DDTHH:mm:ss` with no time zone.", "example": "2026-11-02T14:45:00" }, "tickets": { "type": "array", "items": { "type": "object", "properties": { "passengerId": { "type": "string", "description": "ID of the passenger the ticket belongs to — one of the trip's `passengers[]`. Omitted only if the passenger could not be matched to the trip's passengers.", "example": "6710a3f2c9e77b0012a4d5e1" }, "locators": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "Kind of reference, such as `PNR` for an airline's booking code.", "example": "PNR" }, "code": { "type": "string", "description": "The reference itself, as the supplier issued it.", "example": "ABC123" } }, "required": [ "type", "code" ], "description": "A reference that identifies the booking with the supplier, such as an airline's booking code." }, "description": "Booking references of the ticket. Empty when none is available." }, "ticketCode": { "type": "string", "nullable": true, "description": "Code of the ticket. `null` when not available.", "example": "EB123456" }, "qrCode": { "type": "string", "nullable": true, "description": "The boarding QR code image, base64-encoded. `null` when not available.", "example": "iVBORw0KGgo=" }, "bpeNumber": { "type": "string", "nullable": true, "description": "Number of the electronic bus ticket (BP-e). `null` when not available.", "example": "35261112345678000190630010000123451000123456" } }, "required": [ "locators", "ticketCode", "qrCode", "bpeNumber" ], "description": "The boarding ticket of one passenger on one leg." }, "description": "Tickets of the leg, one per passenger." } }, "required": [ "origin", "destination", "platform", "departureDate", "arrivalDate", "tickets" ], "description": "The boarding details of one leg of the trip." }, "description": "Boarding details per leg. A connection has two legs; direct and one-stop trips have one." } }, "required": [ "boardingPass", "routes" ], "nullable": true } }, "required": [ "type", "origin", "destination", "departureDate", "arrivalDate", "company", "segments", "routeDirection", "boardingInfo" ], "description": "The booked bus trip of one passenger (by ID): stations, operator, the legs with their seats and fares, and boarding information. This is the shape of `productSnapshot` when the trip's `vertical` is `BUS`. Amounts are integers in cents.", "title": "Bus trip" }, { "type": "object", "properties": { "groupName": { "type": "string", "description": "Commercial group the vehicle belongs to, such as `ECONOMY` or `SUV`.", "example": "ECONOMY" }, "class": { "type": "string", "description": "Class of the vehicle within its group.", "example": "INTERMEDIATE" }, "name": { "type": "string", "description": "Name of the vehicle, as the rental company displays it.", "example": "Fiat Mobi" }, "sipp": { "type": "string", "description": "SIPP code that classifies the vehicle by size, doors, transmission and fuel.", "example": "ECMR" }, "rentalCompany": { "type": "object", "properties": { "code": { "type": "string", "description": "Code of the rental company.", "example": "LOC" }, "name": { "type": "string", "description": "Commercial name of the rental company.", "example": "Localiza" }, "logo": { "type": "string", "nullable": true, "description": "URL of the rental company's logo. `null` when the company has no registered logo.", "example": "https://cdn.example.com/rentals/localiza.svg" } }, "required": [ "code", "name", "logo" ], "description": "Rental company that holds the booking." }, "pickUpLocation": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the rental location.", "example": "Localiza Aeroporto Guarulhos (GRU)" }, "phoneNumbers": { "type": "array", "items": { "type": "string", "example": "551133337777" }, "description": "Contact phone numbers of the location, digits only. Empty when none is registered.\n\n---\n\nExample: `[\"551133337777\"]`" }, "shortAddress": { "type": "string", "nullable": true, "description": "Readable single-line address of the location. `null` when unknown.", "example": "Rod. Hélio Smidt, s/n, Guarulhos, SP, Brazil" }, "locality": { "type": "string", "nullable": true, "description": "City the location sits in. `null` when unknown.", "example": "Guarulhos" }, "administrativeArea": { "type": "string", "nullable": true, "description": "State, as its short code. `null` when unknown.", "example": "SP" } }, "required": [ "name", "phoneNumbers", "shortAddress", "locality", "administrativeArea" ], "description": "Where the vehicle is picked up." }, "dropOffLocation": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the rental location.", "example": "Localiza Aeroporto Guarulhos (GRU)" }, "phoneNumbers": { "type": "array", "items": { "type": "string", "example": "551133337777" }, "description": "Contact phone numbers of the location, digits only. Empty when none is registered.\n\n---\n\nExample: `[\"551133337777\"]`" }, "shortAddress": { "type": "string", "nullable": true, "description": "Readable single-line address of the location. `null` when unknown.", "example": "Rod. Hélio Smidt, s/n, Guarulhos, SP, Brazil" }, "locality": { "type": "string", "nullable": true, "description": "City the location sits in. `null` when unknown.", "example": "Guarulhos" }, "administrativeArea": { "type": "string", "nullable": true, "description": "State, as its short code. `null` when unknown.", "example": "SP" } }, "required": [ "name", "phoneNumbers", "shortAddress", "locality", "administrativeArea" ], "description": "Where the vehicle is dropped off." }, "pickUpDate": { "type": "string", "description": "Pick-up date and time in the local time of the pick-up location, as `YYYY-MM-DDTHH:mm:ss` with no time zone.", "example": "2026-11-02T10:00:00" }, "dropOffDate": { "type": "string", "description": "Drop-off date and time in the local time of the drop-off location, as `YYYY-MM-DDTHH:mm:ss` with no time zone.", "example": "2026-11-04T10:00:00" }, "rentals": { "type": "array", "items": { "type": "object", "properties": { "description": { "type": "string", "nullable": true, "description": "Readable description of the rental option. `null` when not provided.", "example": "Compact car, air conditioning, unlimited mileage" }, "fare": { "type": "object", "properties": { "originalAmount": { "type": "number", "description": "Fare before discounts and fees, in cents.", "example": 36000 }, "discountAmount": { "type": "number", "description": "Discount applied to the fare, in cents.", "example": 2000 }, "feeAmount": { "type": "number", "description": "Fees added to the fare, in cents.", "example": 0 }, "amount": { "type": "number", "description": "Total charged for the fare, in cents: `originalAmount` - `discountAmount` + `feeAmount`.", "example": 34000 }, "currency": { "type": "string", "description": "Currency, as the ISO 4217 alphabetic code.", "example": "BRL" }, "cancellationPolicies": { "type": "object", "properties": { "refundable": { "type": "boolean", "description": "Whether cancelling gives any money back.", "example": true }, "immediateFine": { "type": "boolean", "description": "Whether a fine applies to a cancellation made right after the booking.", "example": false }, "penalties": { "type": "array", "items": { "type": "object", "properties": { "from": { "type": "string", "nullable": true, "description": "First day (`YYYY-MM-DD`) on which this tier applies. `null` when the supplier gave no date.", "example": "2026-10-31" }, "currency": { "type": "string", "description": "Currency, as the ISO 4217 alphabetic code.", "example": "BRL" }, "fineAmount": { "type": "number", "nullable": true, "description": "Fine charged for cancelling from `from` onward, in cents. `null` when the amount is not available.", "example": 12000 } }, "required": [ "from", "currency", "fineAmount" ], "description": "One tier of the cancellation penalty schedule of a rental." }, "description": "Penalty tiers, each in effect from its own date. Empty when no scheduled penalty applies." } }, "required": [ "refundable", "immediateFine", "penalties" ], "description": "Cancellation rules of the fare." } }, "required": [ "originalAmount", "discountAmount", "feeAmount", "amount", "currency", "cancellationPolicies" ], "description": "Fare of the rental." }, "passengersId": { "type": "array", "items": { "type": "string", "example": "6710a3f2c9e77b0012a4d5e1" }, "description": "IDs of the passengers travelling on this rental — the trip's `passengers[]`. Empty when none was assigned.\n\n---\n\nExample: `[\"6710a3f2c9e77b0012a4d5e1\"]`" }, "locators": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "Kind of reference, such as `PNR` for an airline's booking code.", "example": "PNR" }, "code": { "type": "string", "description": "The reference itself, as the supplier issued it.", "example": "ABC123" } }, "required": [ "type", "code" ], "description": "A reference that identifies the booking with the supplier, such as an airline's booking code." }, "description": "Booking references of the rental with the rental company. Empty until the reservation is confirmed." } }, "required": [ "description", "fare", "passengersId", "locators" ], "description": "A booked rental." }, "description": "Rentals booked under this record." }, "locators": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "Kind of reference, such as `PNR` for an airline's booking code.", "example": "PNR" }, "code": { "type": "string", "description": "The reference itself, as the supplier issued it.", "example": "ABC123" } }, "required": [ "type", "code" ], "description": "A reference that identifies the booking with the supplier, such as an airline's booking code." }, "description": "Booking references of the reservation as a whole. Empty until the reservation is confirmed." } }, "required": [ "groupName", "class", "name", "sipp", "rentalCompany", "pickUpLocation", "dropOffLocation", "pickUpDate", "dropOffDate", "rentals", "locators" ], "description": "The booked vehicle rental: the vehicle, the rental company, the pick-up and drop-off places and dates, fares, passengers (by ID) and reservation locators. This is the shape of `productSnapshot` when the trip's `vertical` is `VEHICLE`. Amounts are integers in cents.", "title": "Vehicle trip" } ], "description": "The booked product: the itinerary, stay, ticket or rental as recorded by the travel provider — journeys and flights, the hotel and its rooms, the route and boarding information, the rental — with its fares, policies and booking locators. It does not repeat the trip's own fields (`state`, `status`, the amounts, the dates) and carries no identifier of the travel provider; passengers are referenced by their `id` in `passengers[]`. Its shape depends on `vertical`: a flight (`AIR`), a hotel stay (`HOTEL`), a bus ticket (`BUS`) or a vehicle rental (`VEHICLE`) — see the four schemas below. Omitted until the record is first fetched." }, "cancellation": { "type": "object", "properties": { "quoteId": { "type": "string", "description": "ID of the confirmed cancellation quote." }, "cancelType": { "type": "string", "enum": [ "CREDIT", "REFUND", "MANUAL_CANCEL", "VOID" ], "description": "Kind of cancellation: `VOID` for a trip not issued yet, `REFUND` or `CREDIT` for an issued one, `MANUAL_CANCEL` when the amounts are settled outside the system." }, "originalAmount": { "type": "number", "nullable": true, "description": "What the trip cost, in cents. Omitted when it couldn't be recorded; `null` for `MANUAL_CANCEL`." }, "remainingAmount": { "type": "number", "nullable": true, "description": "What is given back after the fine, in cents. Omitted when it couldn't be recorded; `null` for `MANUAL_CANCEL`." }, "fineAmount": { "type": "number", "nullable": true, "description": "Cancellation fine, in cents. Omitted when it couldn't be recorded; `null` for `MANUAL_CANCEL`." }, "currency": { "type": "string", "description": "Currency of the amounts, as the numeric ISO 4217 code (`986` is BRL)." }, "status": { "type": "string", "description": "Status of the quote when it was confirmed." }, "expiresAt": { "type": "string", "description": "When the quote would have expired.", "format": "date-time" }, "confirmedAt": { "type": "string", "description": "When the cancellation was confirmed.", "format": "date-time" }, "confirmedBy": { "type": "string", "description": "ID of the user who confirmed the cancellation. Omitted when a service did." } }, "required": [ "quoteId", "cancelType" ], "description": "The confirmed cancellation. Omitted until one is confirmed." }, "createdAt": { "type": "string", "description": "When the trip was created.", "example": "2026-10-01T13:45:12.000Z", "format": "date-time" }, "updatedAt": { "type": "string", "description": "When the trip last changed.", "example": "2026-10-01T13:46:03.000Z", "format": "date-time" } }, "required": [ "id", "realmId", "organizationId", "customFields", "vertical", "state", "status", "passengers" ], "description": "A trip: ONE booked product — a flight, a hotel stay, a bus ticket or a vehicle rental — for the organization's passengers, with its lifecycle. Booking several products means creating several trips." }, "description": "Trips, newest first." }, "next": { "type": "string", "nullable": true, "description": "Cursor for the next page. `null` on the last page.", "example": "eyJjIjoiMjAyNi0xMC0wMVQxMzo0NToxMi4wMDBaIiwiaSI6IjY3MTFiNGMwZDhlMWEzMDAxMmI3YzlmMiJ9" } }, "required": [ "items", "next" ], "description": "One page of the trip list." } } } }, "403": { "description": "`TRAVEL_REALM_ADMIN_REQUIRED` — Only admins of the realm can list its trips.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "TRAVEL_REALM_ADMIN_REQUIRED" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "TRAVEL" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b", "code": "TRAVEL_REALM_ADMIN_REQUIRED", "origin": "TRAVEL", "message": "Realm admin required" } } } }, "422": { "description": "`BAD_REQUEST` — The realm ID or a query parameter is invalid; `fields` lists each one.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "BAD_REQUEST" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "TRAVEL" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." }, "fields": { "type": "array", "description": "One entry per invalid request field (validation errors only).", "items": { "type": "object", "properties": { "field": { "type": "string", "description": "Path of the invalid field, e.g. `label` or `values[0].value`.", "example": "label" }, "message": { "type": "string", "description": "Why the field was rejected.", "example": "label is required" }, "code": { "type": "string", "description": "`_` — e.g. `LABEL_REQUIRED`, `TYPE_ONE_OF`, `VALUES_VALUE_TYPE_ERROR`.", "example": "LABEL_REQUIRED" }, "values": { "type": "array", "items": { "type": "string" }, "description": "The accepted values, when the field is an enumeration." } }, "required": [ "field", "message", "code" ] } } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "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": "vertical", "message": "Invalid option: expected one of \"AIR\"|\"HOTEL\"|\"BUS\"|\"VEHICLE\"", "code": "VERTICAL_ONE_OF" } ] } } } } }, "x-p3-confidence": { "response": "generated:typed", "parameters": "generated:typed", "note": "`.refine(…)` constraint not represented (runtime-dependent value)" } } }, "/realms/{realmId}/organizations/{organizationId}/trips": { "get": { "operationId": "getRealmsByRealmIdOrganizationsByOrganizationIdTrips", "summary": "List organization trips", "tags": [ "Trips" ], "x-p3-sidebar-order": 2, "description": "Lists every trip of the organization, newest first.", "x-mint": { "content": "Only an organization admin can list them: any other user gets a 403, not a page of their own trips (a passenger's trips are listed under that passenger). Filter by creation date, requester, passenger and the type, state or status of the trip. Paginated — see [Pagination](/api-reference/pagination)." }, "parameters": [ { "name": "realmId", "in": "path", "required": true, "description": "ID of your realm.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b" }, { "name": "organizationId", "in": "path", "required": true, "description": "ID of the organization whose trips you want to list.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410" }, { "name": "from", "in": "query", "required": false, "description": "Only trips created on or after this day (`YYYY-MM-DD`, UTC).", "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "example": "2026-10-01" }, { "name": "to", "in": "query", "required": false, "description": "Only trips created on or before this day (`YYYY-MM-DD`, UTC), the whole day included.", "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "example": "2026-10-31" }, { "name": "vertical", "in": "query", "required": false, "description": "Only trips of this type.", "schema": { "type": "string", "enum": [ "AIR", "HOTEL", "BUS", "VEHICLE" ] }, "example": "AIR" }, { "name": "state", "in": "query", "required": false, "description": "Only trips in this state.", "schema": { "type": "string", "enum": [ "PENDING", "RESERVED", "ISSUED", "CANCELED" ] }, "example": "RESERVED" }, { "name": "status", "in": "query", "required": false, "description": "Only trips in this status.", "schema": { "type": "string", "enum": [ "PROCESSING_RESERVATION", "RESERVATION_FAILED", "RESERVED", "PROCESSING_ISSUE", "ISSUED", "PROCESSING_CANCELLATION", "CANCELED", "AWAITING_MANUAL_CANCELLATION", "CANCELLATION_FAILED", "FAILED", "FAILED_BY_INCONSISTENT_DATA", "FAILED_BY_UNAVAILABLE_RESOURCE", "FAILED_BY_BUDGET_EXCEEDED", "EXPIRED", "BLOCKED", "UNKNOWN", "ISSUANCE_FAILED" ] }, "example": "PROCESSING_RESERVATION" }, { "name": "createdBy", "in": "query", "required": false, "description": "Only trips created by this user (`createdBy`).", "schema": { "type": "string", "maxLength": 100 }, "example": "e3553bc1-5e20-4e17-b22a-a796fda0aa99" }, { "name": "passengerId", "in": "query", "required": false, "description": "Only trips the passenger travels on (24 hexadecimal characters).", "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$" }, "example": "6710a3f2c9e77b0012a4d5e1" }, { "name": "next", "in": "query", "required": false, "description": "Cursor returned as `next` by the previous page. Omit for the first page.", "schema": { "type": "string" }, "example": "eyJjIjoiMjAyNi0xMC0wMVQxMzo0NToxMi4wMDBaIiwiaSI6IjY3MTFiNGMwZDhlMWEzMDAxMmI3YzlmMiJ9" }, { "name": "limit", "in": "query", "required": false, "description": "Page size.", "schema": { "default": 15, "type": "integer", "minimum": 1, "maximum": 100 }, "example": 15 } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the trip.", "example": "6711b4c0d8e1a30012b7c9f2" }, "realmId": { "type": "string", "description": "ID of the realm the trip belongs to.", "example": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b", "format": "uuid" }, "organizationId": { "type": "string", "description": "ID of the organization the trip belongs to.", "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410", "format": "uuid" }, "createdBy": { "type": "string", "description": "ID of the user who created the trip. Omitted when a service did.", "example": "e3553bc1-5e20-4e17-b22a-a796fda0aa99", "format": "uuid" }, "customFields": { "type": "object", "additionalProperties": {}, "description": "Values of the organization's trip custom fields, keyed by the custom field's `slug`. Empty when none were set.\n\n---\n\nExample: `{\"cost-center\":\"CC-1020\"}`", "example": { "cost-center": "CC-1020" } }, "vertical": { "type": "string", "enum": [ "AIR", "HOTEL", "BUS", "VEHICLE" ], "description": "Type of product booked. It tells which shape `productSnapshot` has.", "example": "AIR" }, "state": { "type": "string", "enum": [ "PENDING", "RESERVED", "ISSUED", "CANCELED" ], "description": "Where the booking is in its life: `PENDING` while the reservation is being made, `RESERVED` once held (until `reservationExpiresAt`), `ISSUED` once ticketed and `CANCELED`. It only moves forward.", "example": "RESERVED" }, "status": { "type": "string", "enum": [ "PROCESSING_RESERVATION", "RESERVATION_FAILED", "RESERVED", "PROCESSING_ISSUE", "ISSUED", "PROCESSING_CANCELLATION", "CANCELED", "AWAITING_MANUAL_CANCELLATION", "CANCELLATION_FAILED", "FAILED", "FAILED_BY_INCONSISTENT_DATA", "FAILED_BY_UNAVAILABLE_RESOURCE", "FAILED_BY_BUDGET_EXCEEDED", "EXPIRED", "BLOCKED", "UNKNOWN", "ISSUANCE_FAILED" ], "description": "Finer-grained status: it also reports work in progress (`PROCESSING_*`) and failures, and can change back and forth. Use `state` to decide what the booking is; use `status` to tell what is happening to it.", "example": "RESERVED" }, "reservationExpiresAt": { "type": "string", "nullable": true, "description": "Until when the reservation is held. Past it, a trip that was not issued expires. `null` or omitted when there is no hold.", "example": "2026-10-02T13:45:12.000Z", "format": "date-time" }, "issuedAt": { "type": "string", "nullable": true, "description": "When the trip was issued. `null` or omitted until it is.", "format": "date-time" }, "originalAmount": { "type": "number", "description": "Price before discounts, in cents. Omitted until the price is known.", "example": 95000 }, "discountAmount": { "type": "number", "description": "Discount applied, in cents. Omitted until the price is known.", "example": 3010 }, "feeAmount": { "type": "number", "description": "Fees added, in cents. Omitted until the price is known.", "example": 0 }, "totalAmount": { "type": "number", "description": "Amount to pay, in cents: `originalAmount` - `discountAmount` + `feeAmount`. Omitted until the price is known.", "example": 91990 }, "currency": { "type": "string", "description": "Currency of the amounts, as the numeric ISO 4217 code (`986` is BRL).", "example": "986" }, "passengers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the passenger, as returned by the passenger endpoints.", "example": "6710a3f2c9e77b0012a4d5e1" }, "userId": { "type": "string", "description": "ID of the organization user the passenger is linked to. Omitted for a passenger who is not a user. A user sees the trips they travel on.", "example": "e3553bc1-5e20-4e17-b22a-a796fda0aa99", "format": "uuid" }, "lead": { "type": "boolean", "description": "Whether this passenger is the one responsible for the reservation.", "example": true }, "name": { "type": "string", "description": "Full name, as it appears on the passenger's travel documents.", "example": "Mariana Costa" }, "gender": { "type": "string", "enum": [ "MALE", "FEMALE" ], "description": "Gender.", "example": "FEMALE" }, "birthDate": { "type": "string", "description": "Date of birth (`YYYY-MM-DD`).", "example": "1990-04-17" } }, "required": [ "id", "lead", "name", "gender", "birthDate" ], "description": "A passenger of a trip: who travels, as recorded when the trip was booked. The passenger endpoints serve the full profile." }, "description": "The passengers booked on the trip." }, "productSnapshot": { "anyOf": [ { "type": "object", "properties": { "journeys": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the journey, referenced by `tickets[].fares[].journeyId`.", "example": "jour_V1StGXR8Z5jdHi6BmyT2k" }, "direction": { "type": "string", "enum": [ "DEPARTURE", "RETURN" ], "description": "Whether this is the outbound leg (`DEPARTURE`) or the return leg (`RETURN`).", "example": "DEPARTURE" }, "origin": { "type": "object", "properties": { "iata": { "type": "string", "description": "IATA code of the airport, 3 letters.", "example": "GRU" }, "name": { "type": "string", "nullable": true, "description": "Official name of the airport. `null` when unknown.", "example": "São Paulo/Guarulhos International Airport" }, "shortAddress": { "type": "string", "nullable": true, "description": "Readable single-line address of the airport. `null` when unknown.", "example": "Guarulhos, SP, Brazil" }, "locality": { "type": "string", "nullable": true, "description": "City the airport sits in. `null` when unknown.", "example": "Guarulhos" }, "administrativeArea": { "type": "string", "nullable": true, "description": "State, as its short code. `null` when unknown.", "example": "SP" }, "phoneNumbers": { "type": "array", "items": { "type": "string", "example": "551133334444" }, "description": "Contact phone numbers of the airport, digits only. Empty when none is registered.\n\n---\n\nExample: `[\"551133334444\"]`" } }, "required": [ "iata", "name", "shortAddress", "locality", "administrativeArea", "phoneNumbers" ], "description": "Airport the journey starts at." }, "destination": { "type": "object", "properties": { "iata": { "type": "string", "description": "IATA code of the airport, 3 letters.", "example": "GRU" }, "name": { "type": "string", "nullable": true, "description": "Official name of the airport. `null` when unknown.", "example": "São Paulo/Guarulhos International Airport" }, "shortAddress": { "type": "string", "nullable": true, "description": "Readable single-line address of the airport. `null` when unknown.", "example": "Guarulhos, SP, Brazil" }, "locality": { "type": "string", "nullable": true, "description": "City the airport sits in. `null` when unknown.", "example": "Guarulhos" }, "administrativeArea": { "type": "string", "nullable": true, "description": "State, as its short code. `null` when unknown.", "example": "SP" }, "phoneNumbers": { "type": "array", "items": { "type": "string", "example": "551133334444" }, "description": "Contact phone numbers of the airport, digits only. Empty when none is registered.\n\n---\n\nExample: `[\"551133334444\"]`" } }, "required": [ "iata", "name", "shortAddress", "locality", "administrativeArea", "phoneNumbers" ], "description": "Airport the journey ends at.", "example": { "iata": "SDU", "name": "Rio de Janeiro/Santos Dumont Airport", "shortAddress": "Rio de Janeiro, RJ, Brazil", "locality": "Rio de Janeiro", "administrativeArea": "RJ", "phoneNumbers": [ "552133339999" ] } }, "departureDate": { "type": "string", "description": "Departure date and time in the local time of the origin airport, as `YYYY-MM-DDTHH:mm:ss` with no time zone.", "example": "2026-11-02T08:30:00" }, "arrivalDate": { "type": "string", "description": "Arrival date and time in the local time of the destination airport, as `YYYY-MM-DDTHH:mm:ss` with no time zone.", "example": "2026-11-02T09:35:00" }, "duration": { "type": "string", "description": "Total travel time of the journey, connections included, as `HH:mm`.", "example": "01:05" }, "segments": { "type": "array", "items": { "type": "object", "properties": { "airline": { "type": "object", "properties": { "code": { "type": "string", "description": "IATA code of the airline.", "example": "LA" }, "name": { "type": "string", "nullable": true, "description": "Commercial name of the airline. `null` when unknown.", "example": "LATAM Airlines" }, "logo": { "type": "string", "nullable": true, "description": "URL of the airline's logo. `null` when there is none.", "example": "https://cdn.example.com/airlines/LA.png" } }, "required": [ "code", "name", "logo" ], "description": "Airline that sells the flight." }, "operation": { "type": "object", "properties": { "code": { "type": "string", "description": "IATA code of the airline.", "example": "LA" }, "name": { "type": "string", "nullable": true, "description": "Commercial name of the airline. `null` when unknown.", "example": "LATAM Airlines" }, "logo": { "type": "string", "nullable": true, "description": "URL of the airline's logo. `null` when there is none.", "example": "https://cdn.example.com/airlines/LA.png" } }, "required": [ "code", "name", "logo" ], "description": "Airline that operates the flight. It differs from `airline` on codeshare flights." }, "origin": { "type": "object", "properties": { "iata": { "type": "string", "description": "IATA code of the airport, 3 letters.", "example": "GRU" }, "name": { "type": "string", "nullable": true, "description": "Official name of the airport. `null` when unknown.", "example": "São Paulo/Guarulhos International Airport" }, "shortAddress": { "type": "string", "nullable": true, "description": "Readable single-line address of the airport. `null` when unknown.", "example": "Guarulhos, SP, Brazil" }, "locality": { "type": "string", "nullable": true, "description": "City the airport sits in. `null` when unknown.", "example": "Guarulhos" }, "administrativeArea": { "type": "string", "nullable": true, "description": "State, as its short code. `null` when unknown.", "example": "SP" }, "phoneNumbers": { "type": "array", "items": { "type": "string", "example": "551133334444" }, "description": "Contact phone numbers of the airport, digits only. Empty when none is registered.\n\n---\n\nExample: `[\"551133334444\"]`" } }, "required": [ "iata", "name", "shortAddress", "locality", "administrativeArea", "phoneNumbers" ], "description": "Airport the flight leaves from." }, "destination": { "type": "object", "properties": { "iata": { "type": "string", "description": "IATA code of the airport, 3 letters.", "example": "GRU" }, "name": { "type": "string", "nullable": true, "description": "Official name of the airport. `null` when unknown.", "example": "São Paulo/Guarulhos International Airport" }, "shortAddress": { "type": "string", "nullable": true, "description": "Readable single-line address of the airport. `null` when unknown.", "example": "Guarulhos, SP, Brazil" }, "locality": { "type": "string", "nullable": true, "description": "City the airport sits in. `null` when unknown.", "example": "Guarulhos" }, "administrativeArea": { "type": "string", "nullable": true, "description": "State, as its short code. `null` when unknown.", "example": "SP" }, "phoneNumbers": { "type": "array", "items": { "type": "string", "example": "551133334444" }, "description": "Contact phone numbers of the airport, digits only. Empty when none is registered.\n\n---\n\nExample: `[\"551133334444\"]`" } }, "required": [ "iata", "name", "shortAddress", "locality", "administrativeArea", "phoneNumbers" ], "description": "Airport the flight arrives at.", "example": { "iata": "SDU", "name": "Rio de Janeiro/Santos Dumont Airport", "shortAddress": "Rio de Janeiro, RJ, Brazil", "locality": "Rio de Janeiro", "administrativeArea": "RJ", "phoneNumbers": [ "552133339999" ] } }, "flightNumber": { "type": "string", "description": "Number of the flight, without the airline's code.", "example": "3101" }, "departureDate": { "type": "string", "description": "Departure date and time in the local time of the departure airport, as `YYYY-MM-DDTHH:mm:ss` with no time zone.", "example": "2026-11-02T08:30:00" }, "arrivalDate": { "type": "string", "description": "Arrival date and time in the local time of the arrival airport, as `YYYY-MM-DDTHH:mm:ss` with no time zone.", "example": "2026-11-02T09:35:00" }, "flightType": { "type": "string", "enum": [ "CHARTER", "ALLOTMENT", "REGULAR" ], "description": "Kind of flight: `REGULAR`, `CHARTER` or `ALLOTMENT`.", "example": "REGULAR" }, "duration": { "type": "string", "description": "Duration of the flight, as `HH:mm`.", "example": "01:05" }, "equipment": { "type": "string", "nullable": true, "description": "Aircraft scheduled for the flight, as the airline identifies it. `null` when not informed.", "example": "32Q" }, "cabin": { "type": "string", "enum": [ "ECONOMY", "PREMIUM_ECONOMY", "BUSINESS", "FIRST_CLASS", "UNDEFINED" ], "description": "Cabin booked for the flight.", "example": "ECONOMY" }, "class": { "type": "string", "nullable": true, "description": "Booking class (RBD) priced for the flight. Each airline defines its own codes. `null` when the airline does not expose it.", "example": "Y" }, "fareBasis": { "type": "string", "nullable": true, "description": "Fare basis code priced for the flight. Each airline defines its own codes. `null` when the airline does not expose it.", "example": "YOW" }, "flightInfo": { "description": "Live information about the flight. `null` until it is first collected, as the departure approaches.", "example": null, "type": "object", "properties": { "state": { "type": "string", "nullable": true, "enum": [ "SCHEDULED", "OUT_GATE", "IN_AIR", "LANDED", "IN_GATE", "CANCELED", "PROPOSED", "UNKNOWN", null ], "description": "Operational state of the flight. `null` when there is no live status yet.", "example": "SCHEDULED" }, "updatedAt": { "type": "string", "nullable": true, "description": "When the live status was captured. `null` when there is no live status yet.", "example": "2026-11-01T18:00:00.000Z" }, "aircraft": { "description": "Aircraft operating the flight. `null` when not known yet.", "type": "object", "properties": { "registration": { "type": "string", "nullable": true, "description": "Tail registration of the aircraft. `null` when not known yet.", "example": "PR-XBA" }, "type": { "type": "string", "nullable": true, "description": "ICAO code of the aircraft type. `null` when not known yet.", "example": "A21N" } }, "required": [ "registration", "type" ], "nullable": true }, "departure": { "type": "object", "properties": { "terminal": { "type": "string", "nullable": true, "description": "Terminal at the airport. `null` when not reported yet.", "example": "2" }, "gate": { "type": "string", "nullable": true, "description": "Gate at the airport. `null` when not reported yet.", "example": "B12" }, "baggage": { "type": "string", "nullable": true, "description": "Baggage belt, reported for arrivals only. `null` for departures and when not reported yet.", "example": "04" }, "estimatedTime": { "type": "string", "nullable": true, "description": "Estimated time at the gate, in UTC (ISO 8601). `null` when not known yet.", "example": "2026-11-02T11:30:00.000Z" }, "actualTime": { "type": "string", "nullable": true, "description": "Actual time at the gate, in UTC (ISO 8601), reported once the flight operates. `null` before that.", "example": "2026-11-02T11:34:00.000Z" }, "timeliness": { "type": "string", "nullable": true, "description": "Punctuality of the flight, such as `OnTime`, `Early` or `Delayed`. `null` when not known.", "example": "OnTime" }, "delayMinutes": { "type": "number", "nullable": true, "description": "Delay in minutes; negative when the flight is ahead of schedule. `null` when not known.", "example": 4 } }, "required": [ "terminal", "gate", "baggage", "estimatedTime", "actualTime", "timeliness", "delayMinutes" ], "description": "Live status at the departure airport." }, "arrival": { "type": "object", "properties": { "terminal": { "type": "string", "nullable": true, "description": "Terminal at the airport. `null` when not reported yet.", "example": "2" }, "gate": { "type": "string", "nullable": true, "description": "Gate at the airport. `null` when not reported yet.", "example": "B12" }, "baggage": { "type": "string", "nullable": true, "description": "Baggage belt, reported for arrivals only. `null` for departures and when not reported yet.", "example": "04" }, "estimatedTime": { "type": "string", "nullable": true, "description": "Estimated time at the gate, in UTC (ISO 8601). `null` when not known yet.", "example": "2026-11-02T11:30:00.000Z" }, "actualTime": { "type": "string", "nullable": true, "description": "Actual time at the gate, in UTC (ISO 8601), reported once the flight operates. `null` before that.", "example": "2026-11-02T11:34:00.000Z" }, "timeliness": { "type": "string", "nullable": true, "description": "Punctuality of the flight, such as `OnTime`, `Early` or `Delayed`. `null` when not known.", "example": "OnTime" }, "delayMinutes": { "type": "number", "nullable": true, "description": "Delay in minutes; negative when the flight is ahead of schedule. `null` when not known.", "example": 4 } }, "required": [ "terminal", "gate", "baggage", "estimatedTime", "actualTime", "timeliness", "delayMinutes" ], "description": "Live status at the arrival airport." } }, "required": [ "state", "updatedAt", "aircraft", "departure", "arrival" ], "nullable": true } }, "required": [ "airline", "operation", "origin", "destination", "flightNumber", "departureDate", "arrivalDate", "flightType", "duration", "equipment", "cabin", "class", "fareBasis", "flightInfo" ], "description": "One flight of a journey. A journey with connections has several." }, "description": "Flights of the journey, in chronological order, connections included." } }, "required": [ "id", "direction", "origin", "destination", "departureDate", "arrivalDate", "duration", "segments" ], "description": "One leg of the itinerary: the whole way from an origin to a destination, connections included." }, "description": "Legs of the itinerary, in travel order: one for a one-way trip, two (outbound and return) for a round trip." }, "tickets": { "type": "array", "items": { "type": "object", "properties": { "passengerId": { "type": "string", "description": "ID of the passenger holding this ticket — one of the trip's `passengers[]`. Omitted only if the passenger could not be matched to the trip's passengers.", "example": "6710a3f2c9e77b0012a4d5e1" }, "fareDescription": { "type": "string", "description": "Readable description of the fare of the ticket.", "example": "GRU to SDU, LATAM Airlines, Economy" }, "ticketNumber": { "type": "string", "nullable": true, "description": "Number of the ticket, as the airline issued it. `null` until the ticket is issued.", "example": null }, "fares": { "type": "array", "items": { "type": "object", "properties": { "journeyId": { "type": "string", "nullable": true, "description": "ID of the journey this fare covers — a `journeys[].id`. `null` when the fare covers the whole itinerary.", "example": "jour_V1StGXR8Z5jdHi6BmyT2k" }, "currency": { "type": "string", "description": "Currency, as the ISO 4217 alphabetic code.", "example": "BRL" }, "originalAmount": { "type": "number", "description": "Fare before discounts and fees, in cents.", "example": 95000 }, "discountAmount": { "type": "number", "description": "Discount applied to the fare, in cents.", "example": 3010 }, "feeAmount": { "type": "number", "description": "Fees added to the fare, in cents.", "example": 0 }, "amount": { "type": "number", "description": "Total charged for the fare, in cents: `originalAmount` - `discountAmount` + `feeAmount`.", "example": 91990 }, "cancellationPolicies": { "type": "object", "properties": { "refundable": { "type": "boolean", "description": "Whether cancelling gives any money back.", "example": true }, "immediateFine": { "type": "boolean", "description": "Whether a fine applies to a cancellation made right after the booking.", "example": false }, "penalties": { "type": "array", "items": { "type": "object", "properties": { "from": { "type": "string", "description": "First day (`YYYY-MM-DD`) on which this tier applies.", "example": "2026-10-25" }, "currency": { "type": "string", "description": "Currency, as the ISO 4217 alphabetic code.", "example": "BRL" }, "fineAmount": { "type": "number", "nullable": true, "description": "Fine charged for cancelling from `from` onward, in cents. `null` when the amount is not available.", "example": 15000 } }, "required": [ "from", "currency", "fineAmount" ], "description": "One tier of a cancellation penalty schedule." }, "description": "Penalty tiers, each in effect from its own date. Empty when no scheduled penalty applies." } }, "required": [ "refundable", "immediateFine", "penalties" ], "description": "Cancellation rules of the fare." }, "changePolicies": { "type": "object", "properties": { "canChange": { "type": "boolean", "description": "Whether the fare allows the booking to be changed.", "example": true }, "immediateFine": { "type": "boolean", "description": "Whether a fine applies to a change made right after the booking.", "example": false }, "penalties": { "type": "array", "items": { "type": "object", "properties": { "from": { "type": "string", "description": "First day (`YYYY-MM-DD`) on which this tier applies.", "example": "2026-10-25" }, "currency": { "type": "string", "description": "Currency, as the ISO 4217 alphabetic code.", "example": "BRL" }, "fineAmount": { "type": "number", "nullable": true, "description": "Fine charged for changing the booking from `from` onward, in cents. `null` when the amount is not available.", "example": 8000 } }, "required": [ "from", "currency", "fineAmount" ], "description": "One tier of a change penalty schedule." }, "description": "Penalty tiers, each in effect from its own date. Empty when no scheduled penalty applies." } }, "required": [ "canChange", "immediateFine", "penalties" ], "description": "Change rules of the fare." } }, "required": [ "journeyId", "currency", "originalAmount", "discountAmount", "feeAmount", "amount", "cancellationPolicies", "changePolicies" ], "description": "The fare of a ticket for one journey, or for the whole itinerary. Amounts are integers in cents." }, "description": "Fares of the ticket: one per journey, or a single one for the whole itinerary." }, "segments": { "type": "array", "items": { "type": "object", "properties": { "flightNumber": { "type": "string", "description": "Number of the flight this ticket covers, without the airline's code. It matches the `flightNumber` of one of the journeys' `segments`.", "example": "3101" }, "cabin": { "type": "string", "enum": [ "ECONOMY", "PREMIUM_ECONOMY", "BUSINESS", "FIRST_CLASS", "UNDEFINED" ], "description": "Cabin of the ticket on this flight.", "example": "ECONOMY" }, "class": { "type": "string", "nullable": true, "description": "Booking class (RBD) of the ticket on this flight. Each airline defines its own codes. `null` when the airline does not expose it.", "example": "Y" }, "fareBasis": { "type": "string", "nullable": true, "description": "Fare basis code of the ticket on this flight. Each airline defines its own codes. `null` when the airline does not expose it.", "example": "YOW" }, "baggages": { "type": "array", "items": { "type": "object", "properties": { "quantity": { "type": "number", "description": "Number of pieces included in the allowance.", "example": 1 }, "weight": { "type": "number", "nullable": true, "description": "Weight allowed per piece, in kg. `null` when the airline sets no weight limit per piece.", "example": 23 }, "type": { "type": "string", "enum": [ "CHECKED", "CARRY_ON", "PERSONAL_ITEM" ], "description": "Kind of baggage: `CHECKED`, `CARRY_ON` or `PERSONAL_ITEM`.", "example": "CHECKED" } }, "required": [ "quantity", "weight", "type" ], "description": "A baggage allowance of a ticket on one flight." }, "description": "Baggage allowance of the ticket on this flight. Empty for an infant on an adult's lap." } }, "required": [ "flightNumber", "cabin", "class", "fareBasis", "baggages" ], "description": "What a ticket covers on one flight of the itinerary: the cabin, the fare codes and the baggage allowance." }, "description": "What the ticket covers on each flight of the itinerary." } }, "required": [ "fareDescription", "ticketNumber", "fares", "segments" ], "description": "The ticket of one passenger. It covers the whole itinerary, with a fare per journey or a single fare for all of it." }, "description": "Tickets of the booking, one per passenger, each covering the whole itinerary." }, "locators": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "Kind of reference, such as `PNR` for an airline's booking code.", "example": "PNR" }, "code": { "type": "string", "description": "The reference itself, as the supplier issued it.", "example": "ABC123" } }, "required": [ "type", "code" ], "description": "A reference that identifies the booking with the supplier, such as an airline's booking code." }, "description": "Booking references issued by the airlines. Empty until the reservation is confirmed." }, "flightInfoUpdatedAt": { "type": "string", "nullable": true, "description": "When the live flight information was last collected. `null` until it is first collected.", "example": null, "format": "date-time" } }, "required": [ "journeys", "tickets", "locators", "flightInfoUpdatedAt" ], "description": "The booked flight: itinerary, the ticket of each passenger (by ID) with its fares and baggage, and reservation locators. This is the shape of `productSnapshot` when the trip's `vertical` is `AIR`. Amounts are integers in cents.", "title": "Air trip" }, { "type": "object", "properties": { "hotel": { "type": "object", "properties": { "name": { "type": "string", "description": "Official name of the hotel.", "example": "Hotel Paulista Plaza" }, "chain": { "type": "object", "properties": { "brandName": { "type": "string", "nullable": true, "description": "Brand within the chain. `null` when not informed.", "example": "Ibis" }, "chainName": { "type": "string", "nullable": true, "description": "Name of the chain. `null` for an independent hotel.", "example": "Accor" }, "logo": { "type": "string", "nullable": true, "description": "URL of the chain's logo. `null` when the hotel has no chain with a registered logo.", "example": "https://cdn.example.com/hotels/ibis.svg" } }, "required": [ "brandName", "chainName", "logo" ], "description": "Chain and brand of the hotel." }, "shortAddress": { "type": "string", "nullable": true, "description": "Readable single-line address of the hotel. `null` when unknown.", "example": "Av. Paulista, 1500, São Paulo, SP, Brazil" }, "phoneNumbers": { "type": "array", "items": { "type": "string", "example": "551133335555" }, "description": "Contact phone numbers of the hotel, digits only. Empty when none is registered.\n\n---\n\nExample: `[\"551133335555\"]`" }, "locality": { "type": "string", "nullable": true, "description": "City the hotel sits in. `null` when unknown.", "example": "São Paulo" }, "administrativeArea": { "type": "string", "nullable": true, "description": "State, as its short code. `null` when unknown.", "example": "SP" }, "checkInTime": { "type": "string", "nullable": true, "description": "Time of day, in the hotel's local time (`HH:mm`), from which guests can check in. `null` when unknown.", "example": "14:00" }, "checkOutTime": { "type": "string", "nullable": true, "description": "Time of day, in the hotel's local time (`HH:mm`), by which guests must check out. `null` when unknown.", "example": "12:00" } }, "required": [ "name", "chain", "shortAddress", "phoneNumbers", "locality", "administrativeArea", "checkInTime", "checkOutTime" ], "description": "Hotel where the stay is booked." }, "checkIn": { "type": "string", "description": "Check-in date (`YYYY-MM-DD`).", "example": "2026-11-02" }, "checkOut": { "type": "string", "description": "Check-out date (`YYYY-MM-DD`).", "example": "2026-11-04" }, "rooms": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the room, as the hotel offers it.", "example": "Standard Room, 1 Queen Bed" }, "fare": { "type": "object", "properties": { "currency": { "type": "string", "description": "Currency, as the ISO 4217 alphabetic code.", "example": "BRL" }, "originalAmount": { "type": "number", "description": "Fare before discounts and fees, in cents.", "example": 120000 }, "discountAmount": { "type": "number", "description": "Discount applied to the fare, in cents.", "example": 8000 }, "feeAmount": { "type": "number", "description": "Fees added to the fare, in cents.", "example": 0 }, "amount": { "type": "number", "description": "Total charged for the fare, in cents: `originalAmount` - `discountAmount` + `feeAmount`.", "example": 112000 }, "boardType": { "type": "string", "enum": [ "ONLY_ROOM", "BREAKFAST", "HALF_BOARD", "FULL_BOARD", "ALL_INCLUSIVE" ], "description": "Meals included in the fare.", "example": "BREAKFAST" }, "cancellationPolicies": { "type": "object", "properties": { "refundable": { "type": "boolean", "description": "Whether cancelling gives any money back.", "example": true }, "immediateFine": { "type": "boolean", "description": "Whether a fine applies to a cancellation made right after the booking.", "example": false }, "penalties": { "type": "array", "items": { "type": "object", "properties": { "from": { "type": "string", "description": "First day (`YYYY-MM-DD`) on which this tier applies.", "example": "2026-10-25" }, "currency": { "type": "string", "description": "Currency, as the ISO 4217 alphabetic code.", "example": "BRL" }, "fineAmount": { "type": "number", "nullable": true, "description": "Fine charged for cancelling from `from` onward, in cents. `null` when the amount is not available.", "example": 15000 } }, "required": [ "from", "currency", "fineAmount" ], "description": "One tier of a cancellation penalty schedule." }, "description": "Penalty tiers, each in effect from its own date. Empty when no scheduled penalty applies." } }, "required": [ "refundable", "immediateFine", "penalties" ], "description": "Cancellation rules of the fare." } }, "required": [ "currency", "originalAmount", "discountAmount", "feeAmount", "amount", "boardType", "cancellationPolicies" ], "description": "Fare of the room." }, "passengersId": { "type": "array", "items": { "type": "string", "example": "6710a3f2c9e77b0012a4d5e1" }, "description": "IDs of the passengers staying in this room — the trip's `passengers[]`.\n\n---\n\nExample: `[\"6710a3f2c9e77b0012a4d5e1\"]`" } }, "required": [ "name", "fare", "passengersId" ], "description": "A booked room." }, "description": "Rooms booked for the stay." }, "locators": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "Kind of reference, such as `PNR` for an airline's booking code.", "example": "PNR" }, "code": { "type": "string", "description": "The reference itself, as the supplier issued it.", "example": "ABC123" } }, "required": [ "type", "code" ], "description": "A reference that identifies the booking with the supplier, such as an airline's booking code." }, "description": "Booking references issued by the hotel. Empty until the reservation is confirmed." } }, "required": [ "hotel", "checkIn", "checkOut", "rooms", "locators" ], "description": "The booked hotel stay: the hotel, the dates, the rooms with their fares and guests (by ID), and the reservation locators. This is the shape of `productSnapshot` when the trip's `vertical` is `HOTEL`. Amounts are integers in cents.", "title": "Hotel trip" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "DIRECT", "CONNECTION", "ONE_STOP" ], "description": "Kind of trip: `DIRECT`, `CONNECTION` or `ONE_STOP`.", "example": "DIRECT" }, "origin": { "type": "object", "properties": { "locality": { "type": "string", "description": "City the station sits in.", "example": "São Paulo" }, "administrativeArea": { "type": "string", "description": "State, as its short code.", "example": "SP" }, "name": { "type": "string", "nullable": true, "description": "Official name of the station. `null` when unknown.", "example": "Terminal Rodoviário Tietê" }, "shortAddress": { "type": "string", "nullable": true, "description": "Readable single-line address of the station. `null` when unknown.", "example": "Av. Cruzeiro do Sul, 1800, São Paulo, SP, Brazil" }, "phoneNumbers": { "type": "array", "items": { "type": "string", "example": "551133336666" }, "description": "Contact phone numbers of the station, digits only. Empty when none is registered.\n\n---\n\nExample: `[\"551133336666\"]`" } }, "required": [ "locality", "administrativeArea", "name", "shortAddress", "phoneNumbers" ], "description": "Station the trip starts at." }, "destination": { "type": "object", "properties": { "locality": { "type": "string", "description": "City the station sits in.", "example": "São Paulo" }, "administrativeArea": { "type": "string", "description": "State, as its short code.", "example": "SP" }, "name": { "type": "string", "nullable": true, "description": "Official name of the station. `null` when unknown.", "example": "Terminal Rodoviário Tietê" }, "shortAddress": { "type": "string", "nullable": true, "description": "Readable single-line address of the station. `null` when unknown.", "example": "Av. Cruzeiro do Sul, 1800, São Paulo, SP, Brazil" }, "phoneNumbers": { "type": "array", "items": { "type": "string", "example": "551133336666" }, "description": "Contact phone numbers of the station, digits only. Empty when none is registered.\n\n---\n\nExample: `[\"551133336666\"]`" } }, "required": [ "locality", "administrativeArea", "name", "shortAddress", "phoneNumbers" ], "description": "Station the trip ends at.", "example": { "locality": "Rio de Janeiro", "administrativeArea": "RJ", "name": "Rodoviária Novo Rio", "shortAddress": "Av. Francisco Bicalho, 1, Rio de Janeiro, RJ, Brazil", "phoneNumbers": [ "552133338888" ] } }, "departureDate": { "type": "string", "description": "Departure date and time in the local time of the origin station, as `YYYY-MM-DDTHH:mm:ss` with no time zone.", "example": "2026-11-02T08:30:00" }, "arrivalDate": { "type": "string", "description": "Arrival date and time in the local time of the destination station, as `YYYY-MM-DDTHH:mm:ss` with no time zone.", "example": "2026-11-02T14:45:00" }, "company": { "type": "object", "properties": { "name": { "type": "string", "description": "Commercial name of the company.", "example": "Expresso Brasileiro" }, "logo": { "type": "string", "nullable": true, "description": "URL of the company's logo. `null` when there is none.", "example": "https://cdn.example.com/bus/expresso-brasileiro.png" } }, "required": [ "name", "logo" ], "description": "Company that operates the trip." }, "passengerId": { "type": "string", "description": "ID of the passenger travelling on this ticket — one of the trip's `passengers[]`. Omitted only if the passenger could not be matched to the trip's passengers.", "example": "6710a3f2c9e77b0012a4d5e1" }, "segments": { "type": "array", "items": { "type": "object", "properties": { "seatNumber": { "type": "number", "description": "Seat reserved on the segment.", "example": 12 }, "serviceClass": { "type": "string", "enum": [ "SLEEPER_BED", "BED", "SEMI_BED", "EXECUTIVE", "CONVENTIONAL", "UNDEFINED" ], "description": "Class of service booked for the segment.", "example": "EXECUTIVE" }, "origin": { "type": "object", "properties": { "locality": { "type": "string", "description": "City the station sits in.", "example": "São Paulo" }, "administrativeArea": { "type": "string", "description": "State, as its short code.", "example": "SP" }, "name": { "type": "string", "nullable": true, "description": "Official name of the station. `null` when unknown.", "example": "Terminal Rodoviário Tietê" }, "shortAddress": { "type": "string", "nullable": true, "description": "Readable single-line address of the station. `null` when unknown.", "example": "Av. Cruzeiro do Sul, 1800, São Paulo, SP, Brazil" }, "phoneNumbers": { "type": "array", "items": { "type": "string", "example": "551133336666" }, "description": "Contact phone numbers of the station, digits only. Empty when none is registered.\n\n---\n\nExample: `[\"551133336666\"]`" } }, "required": [ "locality", "administrativeArea", "name", "shortAddress", "phoneNumbers" ], "description": "Station the segment leaves from." }, "destination": { "type": "object", "properties": { "locality": { "type": "string", "description": "City the station sits in.", "example": "São Paulo" }, "administrativeArea": { "type": "string", "description": "State, as its short code.", "example": "SP" }, "name": { "type": "string", "nullable": true, "description": "Official name of the station. `null` when unknown.", "example": "Terminal Rodoviário Tietê" }, "shortAddress": { "type": "string", "nullable": true, "description": "Readable single-line address of the station. `null` when unknown.", "example": "Av. Cruzeiro do Sul, 1800, São Paulo, SP, Brazil" }, "phoneNumbers": { "type": "array", "items": { "type": "string", "example": "551133336666" }, "description": "Contact phone numbers of the station, digits only. Empty when none is registered.\n\n---\n\nExample: `[\"551133336666\"]`" } }, "required": [ "locality", "administrativeArea", "name", "shortAddress", "phoneNumbers" ], "description": "Station the segment arrives at.", "example": { "locality": "Rio de Janeiro", "administrativeArea": "RJ", "name": "Rodoviária Novo Rio", "shortAddress": "Av. Francisco Bicalho, 1, Rio de Janeiro, RJ, Brazil", "phoneNumbers": [ "552133338888" ] } }, "departureDate": { "type": "string", "description": "Departure date and time in the local time of the origin station, as `YYYY-MM-DDTHH:mm:ss` with no time zone.", "example": "2026-11-02T08:30:00" }, "arrivalDate": { "type": "string", "description": "Arrival date and time in the local time of the destination station, as `YYYY-MM-DDTHH:mm:ss` with no time zone.", "example": "2026-11-02T14:45:00" }, "duration": { "type": "string", "nullable": true, "description": "Duration of the leg, as `HH:mm`. `null` when not available.", "example": "06:15" }, "fare": { "type": "object", "properties": { "originalAmount": { "type": "number", "description": "Fare before discounts and fees, in cents.", "example": 18000 }, "discountAmount": { "type": "number", "description": "Discount applied to the fare, in cents.", "example": 1000 }, "feeAmount": { "type": "number", "description": "Fees added to the fare, in cents.", "example": 500 }, "amount": { "type": "number", "description": "Total charged for the fare, in cents: `originalAmount` - `discountAmount` + `feeAmount`.", "example": 17500 }, "currency": { "type": "string", "description": "Currency, as the ISO 4217 alphabetic code.", "example": "BRL" }, "cancellationPolicies": { "type": "object", "properties": { "refundable": { "type": "boolean", "description": "Whether cancelling gives any money back.", "example": true }, "immediateFine": { "type": "boolean", "description": "Whether a fine applies to a cancellation made right after the booking.", "example": false }, "penalties": { "type": "array", "items": { "type": "object", "properties": { "from": { "type": "string", "description": "First day (`YYYY-MM-DD`) on which this tier applies.", "example": "2026-10-25" }, "currency": { "type": "string", "description": "Currency, as the ISO 4217 alphabetic code.", "example": "BRL" }, "fineAmount": { "type": "number", "nullable": true, "description": "Fine charged for cancelling from `from` onward, in cents. `null` when the amount is not available.", "example": 15000 } }, "required": [ "from", "currency", "fineAmount" ], "description": "One tier of a cancellation penalty schedule." }, "description": "Penalty tiers, each in effect from its own date. Empty when no scheduled penalty applies." } }, "required": [ "refundable", "immediateFine", "penalties" ], "description": "Cancellation rules of the fare." } }, "required": [ "originalAmount", "discountAmount", "feeAmount", "amount", "currency", "cancellationPolicies" ], "description": "Fare of the segment." }, "company": { "type": "object", "properties": { "name": { "type": "string", "description": "Commercial name of the company.", "example": "Expresso Brasileiro" }, "logo": { "type": "string", "nullable": true, "description": "URL of the company's logo. `null` when there is none.", "example": "https://cdn.example.com/bus/expresso-brasileiro.png" } }, "required": [ "name", "logo" ], "description": "Operator running this leg." } }, "required": [ "seatNumber", "serviceClass", "origin", "destination", "departureDate", "arrivalDate", "duration", "fare", "company" ], "description": "One leg of the bus trip, with the seat booked on it." }, "description": "Segments of the trip, one per leg, each with its seat, fare and operator." }, "routeDirection": { "type": "string", "enum": [ "DEPARTURE", "RETURN" ], "description": "Whether this booking is the outbound trip (`DEPARTURE`) or the return trip (`RETURN`).", "example": "DEPARTURE" }, "boardingInfo": { "description": "Boarding pass and, per leg, platform and ticket codes. `null` until it is first collected, as the departure approaches.", "example": null, "type": "object", "properties": { "boardingPass": { "type": "string", "nullable": true, "description": "The boarding pass PDF, base64-encoded. `null` when not available yet.", "example": "JVBERi0xLjcK" }, "routes": { "type": "array", "items": { "type": "object", "properties": { "origin": { "type": "string", "description": "City the leg starts in.", "example": "São Paulo" }, "destination": { "type": "string", "description": "City the leg ends in.", "example": "Rio de Janeiro" }, "platform": { "type": "string", "nullable": true, "description": "Boarding platform at the origin station. `null` when not assigned or not applicable.", "example": "14" }, "departureDate": { "type": "string", "description": "Departure date and time in local time, as `YYYY-MM-DDTHH:mm:ss` with no time zone.", "example": "2026-11-02T08:30:00" }, "arrivalDate": { "type": "string", "description": "Arrival date and time in local time, as `YYYY-MM-DDTHH:mm:ss` with no time zone.", "example": "2026-11-02T14:45:00" }, "tickets": { "type": "array", "items": { "type": "object", "properties": { "passengerId": { "type": "string", "description": "ID of the passenger the ticket belongs to — one of the trip's `passengers[]`. Omitted only if the passenger could not be matched to the trip's passengers.", "example": "6710a3f2c9e77b0012a4d5e1" }, "locators": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "Kind of reference, such as `PNR` for an airline's booking code.", "example": "PNR" }, "code": { "type": "string", "description": "The reference itself, as the supplier issued it.", "example": "ABC123" } }, "required": [ "type", "code" ], "description": "A reference that identifies the booking with the supplier, such as an airline's booking code." }, "description": "Booking references of the ticket. Empty when none is available." }, "ticketCode": { "type": "string", "nullable": true, "description": "Code of the ticket. `null` when not available.", "example": "EB123456" }, "qrCode": { "type": "string", "nullable": true, "description": "The boarding QR code image, base64-encoded. `null` when not available.", "example": "iVBORw0KGgo=" }, "bpeNumber": { "type": "string", "nullable": true, "description": "Number of the electronic bus ticket (BP-e). `null` when not available.", "example": "35261112345678000190630010000123451000123456" } }, "required": [ "locators", "ticketCode", "qrCode", "bpeNumber" ], "description": "The boarding ticket of one passenger on one leg." }, "description": "Tickets of the leg, one per passenger." } }, "required": [ "origin", "destination", "platform", "departureDate", "arrivalDate", "tickets" ], "description": "The boarding details of one leg of the trip." }, "description": "Boarding details per leg. A connection has two legs; direct and one-stop trips have one." } }, "required": [ "boardingPass", "routes" ], "nullable": true } }, "required": [ "type", "origin", "destination", "departureDate", "arrivalDate", "company", "segments", "routeDirection", "boardingInfo" ], "description": "The booked bus trip of one passenger (by ID): stations, operator, the legs with their seats and fares, and boarding information. This is the shape of `productSnapshot` when the trip's `vertical` is `BUS`. Amounts are integers in cents.", "title": "Bus trip" }, { "type": "object", "properties": { "groupName": { "type": "string", "description": "Commercial group the vehicle belongs to, such as `ECONOMY` or `SUV`.", "example": "ECONOMY" }, "class": { "type": "string", "description": "Class of the vehicle within its group.", "example": "INTERMEDIATE" }, "name": { "type": "string", "description": "Name of the vehicle, as the rental company displays it.", "example": "Fiat Mobi" }, "sipp": { "type": "string", "description": "SIPP code that classifies the vehicle by size, doors, transmission and fuel.", "example": "ECMR" }, "rentalCompany": { "type": "object", "properties": { "code": { "type": "string", "description": "Code of the rental company.", "example": "LOC" }, "name": { "type": "string", "description": "Commercial name of the rental company.", "example": "Localiza" }, "logo": { "type": "string", "nullable": true, "description": "URL of the rental company's logo. `null` when the company has no registered logo.", "example": "https://cdn.example.com/rentals/localiza.svg" } }, "required": [ "code", "name", "logo" ], "description": "Rental company that holds the booking." }, "pickUpLocation": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the rental location.", "example": "Localiza Aeroporto Guarulhos (GRU)" }, "phoneNumbers": { "type": "array", "items": { "type": "string", "example": "551133337777" }, "description": "Contact phone numbers of the location, digits only. Empty when none is registered.\n\n---\n\nExample: `[\"551133337777\"]`" }, "shortAddress": { "type": "string", "nullable": true, "description": "Readable single-line address of the location. `null` when unknown.", "example": "Rod. Hélio Smidt, s/n, Guarulhos, SP, Brazil" }, "locality": { "type": "string", "nullable": true, "description": "City the location sits in. `null` when unknown.", "example": "Guarulhos" }, "administrativeArea": { "type": "string", "nullable": true, "description": "State, as its short code. `null` when unknown.", "example": "SP" } }, "required": [ "name", "phoneNumbers", "shortAddress", "locality", "administrativeArea" ], "description": "Where the vehicle is picked up." }, "dropOffLocation": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the rental location.", "example": "Localiza Aeroporto Guarulhos (GRU)" }, "phoneNumbers": { "type": "array", "items": { "type": "string", "example": "551133337777" }, "description": "Contact phone numbers of the location, digits only. Empty when none is registered.\n\n---\n\nExample: `[\"551133337777\"]`" }, "shortAddress": { "type": "string", "nullable": true, "description": "Readable single-line address of the location. `null` when unknown.", "example": "Rod. Hélio Smidt, s/n, Guarulhos, SP, Brazil" }, "locality": { "type": "string", "nullable": true, "description": "City the location sits in. `null` when unknown.", "example": "Guarulhos" }, "administrativeArea": { "type": "string", "nullable": true, "description": "State, as its short code. `null` when unknown.", "example": "SP" } }, "required": [ "name", "phoneNumbers", "shortAddress", "locality", "administrativeArea" ], "description": "Where the vehicle is dropped off." }, "pickUpDate": { "type": "string", "description": "Pick-up date and time in the local time of the pick-up location, as `YYYY-MM-DDTHH:mm:ss` with no time zone.", "example": "2026-11-02T10:00:00" }, "dropOffDate": { "type": "string", "description": "Drop-off date and time in the local time of the drop-off location, as `YYYY-MM-DDTHH:mm:ss` with no time zone.", "example": "2026-11-04T10:00:00" }, "rentals": { "type": "array", "items": { "type": "object", "properties": { "description": { "type": "string", "nullable": true, "description": "Readable description of the rental option. `null` when not provided.", "example": "Compact car, air conditioning, unlimited mileage" }, "fare": { "type": "object", "properties": { "originalAmount": { "type": "number", "description": "Fare before discounts and fees, in cents.", "example": 36000 }, "discountAmount": { "type": "number", "description": "Discount applied to the fare, in cents.", "example": 2000 }, "feeAmount": { "type": "number", "description": "Fees added to the fare, in cents.", "example": 0 }, "amount": { "type": "number", "description": "Total charged for the fare, in cents: `originalAmount` - `discountAmount` + `feeAmount`.", "example": 34000 }, "currency": { "type": "string", "description": "Currency, as the ISO 4217 alphabetic code.", "example": "BRL" }, "cancellationPolicies": { "type": "object", "properties": { "refundable": { "type": "boolean", "description": "Whether cancelling gives any money back.", "example": true }, "immediateFine": { "type": "boolean", "description": "Whether a fine applies to a cancellation made right after the booking.", "example": false }, "penalties": { "type": "array", "items": { "type": "object", "properties": { "from": { "type": "string", "nullable": true, "description": "First day (`YYYY-MM-DD`) on which this tier applies. `null` when the supplier gave no date.", "example": "2026-10-31" }, "currency": { "type": "string", "description": "Currency, as the ISO 4217 alphabetic code.", "example": "BRL" }, "fineAmount": { "type": "number", "nullable": true, "description": "Fine charged for cancelling from `from` onward, in cents. `null` when the amount is not available.", "example": 12000 } }, "required": [ "from", "currency", "fineAmount" ], "description": "One tier of the cancellation penalty schedule of a rental." }, "description": "Penalty tiers, each in effect from its own date. Empty when no scheduled penalty applies." } }, "required": [ "refundable", "immediateFine", "penalties" ], "description": "Cancellation rules of the fare." } }, "required": [ "originalAmount", "discountAmount", "feeAmount", "amount", "currency", "cancellationPolicies" ], "description": "Fare of the rental." }, "passengersId": { "type": "array", "items": { "type": "string", "example": "6710a3f2c9e77b0012a4d5e1" }, "description": "IDs of the passengers travelling on this rental — the trip's `passengers[]`. Empty when none was assigned.\n\n---\n\nExample: `[\"6710a3f2c9e77b0012a4d5e1\"]`" }, "locators": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "Kind of reference, such as `PNR` for an airline's booking code.", "example": "PNR" }, "code": { "type": "string", "description": "The reference itself, as the supplier issued it.", "example": "ABC123" } }, "required": [ "type", "code" ], "description": "A reference that identifies the booking with the supplier, such as an airline's booking code." }, "description": "Booking references of the rental with the rental company. Empty until the reservation is confirmed." } }, "required": [ "description", "fare", "passengersId", "locators" ], "description": "A booked rental." }, "description": "Rentals booked under this record." }, "locators": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "Kind of reference, such as `PNR` for an airline's booking code.", "example": "PNR" }, "code": { "type": "string", "description": "The reference itself, as the supplier issued it.", "example": "ABC123" } }, "required": [ "type", "code" ], "description": "A reference that identifies the booking with the supplier, such as an airline's booking code." }, "description": "Booking references of the reservation as a whole. Empty until the reservation is confirmed." } }, "required": [ "groupName", "class", "name", "sipp", "rentalCompany", "pickUpLocation", "dropOffLocation", "pickUpDate", "dropOffDate", "rentals", "locators" ], "description": "The booked vehicle rental: the vehicle, the rental company, the pick-up and drop-off places and dates, fares, passengers (by ID) and reservation locators. This is the shape of `productSnapshot` when the trip's `vertical` is `VEHICLE`. Amounts are integers in cents.", "title": "Vehicle trip" } ], "description": "The booked product: the itinerary, stay, ticket or rental as recorded by the travel provider — journeys and flights, the hotel and its rooms, the route and boarding information, the rental — with its fares, policies and booking locators. It does not repeat the trip's own fields (`state`, `status`, the amounts, the dates) and carries no identifier of the travel provider; passengers are referenced by their `id` in `passengers[]`. Its shape depends on `vertical`: a flight (`AIR`), a hotel stay (`HOTEL`), a bus ticket (`BUS`) or a vehicle rental (`VEHICLE`) — see the four schemas below. Omitted until the record is first fetched." }, "cancellation": { "type": "object", "properties": { "quoteId": { "type": "string", "description": "ID of the confirmed cancellation quote." }, "cancelType": { "type": "string", "enum": [ "CREDIT", "REFUND", "MANUAL_CANCEL", "VOID" ], "description": "Kind of cancellation: `VOID` for a trip not issued yet, `REFUND` or `CREDIT` for an issued one, `MANUAL_CANCEL` when the amounts are settled outside the system." }, "originalAmount": { "type": "number", "nullable": true, "description": "What the trip cost, in cents. Omitted when it couldn't be recorded; `null` for `MANUAL_CANCEL`." }, "remainingAmount": { "type": "number", "nullable": true, "description": "What is given back after the fine, in cents. Omitted when it couldn't be recorded; `null` for `MANUAL_CANCEL`." }, "fineAmount": { "type": "number", "nullable": true, "description": "Cancellation fine, in cents. Omitted when it couldn't be recorded; `null` for `MANUAL_CANCEL`." }, "currency": { "type": "string", "description": "Currency of the amounts, as the numeric ISO 4217 code (`986` is BRL)." }, "status": { "type": "string", "description": "Status of the quote when it was confirmed." }, "expiresAt": { "type": "string", "description": "When the quote would have expired.", "format": "date-time" }, "confirmedAt": { "type": "string", "description": "When the cancellation was confirmed.", "format": "date-time" }, "confirmedBy": { "type": "string", "description": "ID of the user who confirmed the cancellation. Omitted when a service did." } }, "required": [ "quoteId", "cancelType" ], "description": "The confirmed cancellation. Omitted until one is confirmed." }, "createdAt": { "type": "string", "description": "When the trip was created.", "example": "2026-10-01T13:45:12.000Z", "format": "date-time" }, "updatedAt": { "type": "string", "description": "When the trip last changed.", "example": "2026-10-01T13:46:03.000Z", "format": "date-time" } }, "required": [ "id", "realmId", "organizationId", "customFields", "vertical", "state", "status", "passengers" ], "description": "A trip: ONE booked product — a flight, a hotel stay, a bus ticket or a vehicle rental — for the organization's passengers, with its lifecycle. Booking several products means creating several trips." }, "description": "Trips, newest first." }, "next": { "type": "string", "nullable": true, "description": "Cursor for the next page. `null` on the last page.", "example": "eyJjIjoiMjAyNi0xMC0wMVQxMzo0NToxMi4wMDBaIiwiaSI6IjY3MTFiNGMwZDhlMWEzMDAxMmI3YzlmMiJ9" } }, "required": [ "items", "next" ], "description": "One page of the trip list." } } } }, "403": { "description": "`TRAVEL_ADMIN_REQUIRED` — Only organization admins can list the trips of the organization.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "TRAVEL_ADMIN_REQUIRED" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "TRAVEL" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b", "code": "TRAVEL_ADMIN_REQUIRED", "origin": "TRAVEL", "message": "Organization admin required" } } } }, "422": { "description": "`BAD_REQUEST` — A path or query parameter is invalid; `fields` lists each one.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "BAD_REQUEST" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "TRAVEL" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." }, "fields": { "type": "array", "description": "One entry per invalid request field (validation errors only).", "items": { "type": "object", "properties": { "field": { "type": "string", "description": "Path of the invalid field, e.g. `label` or `values[0].value`.", "example": "label" }, "message": { "type": "string", "description": "Why the field was rejected.", "example": "label is required" }, "code": { "type": "string", "description": "`_` — e.g. `LABEL_REQUIRED`, `TYPE_ONE_OF`, `VALUES_VALUE_TYPE_ERROR`.", "example": "LABEL_REQUIRED" }, "values": { "type": "array", "items": { "type": "string" }, "description": "The accepted values, when the field is an enumeration." } }, "required": [ "field", "message", "code" ] } } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "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": "vertical", "message": "Invalid option: expected one of \"AIR\"|\"HOTEL\"|\"BUS\"|\"VEHICLE\"", "code": "VERTICAL_ONE_OF" } ] } } } } }, "x-p3-confidence": { "response": "generated:typed", "parameters": "generated:typed", "note": "`.refine(…)` constraint not represented (runtime-dependent value)" } }, "post": { "operationId": "postRealmsByRealmIdOrganizationsByOrganizationIdTrips", "summary": "Create a trip", "tags": [ "Trips" ], "x-p3-sidebar-order": 3, "description": "Books a trip: one flight, hotel stay, bus ticket or vehicle rental for the organization's passengers. To book several products, create one trip for each.", "x-mint": { "content": "The reservation is asynchronous, so the answer is `202 Accepted` with the trip; a trip still `PENDING` is being reserved. Read the trip to follow it to `RESERVED`, then issue it before its `reservationExpiresAt`.\n\nSend exactly one of `air`, `hotel`, `bus` or `vehicle`, using the ids from the search responses and your passengers' IDs. Every required trip custom field of the organization must be in `customFields`; they can't be changed afterwards.\n\nThe booking is placed with the travel provider before the trip is recorded, so a request that fails with a 4xx booked nothing and can be corrected and sent again. An error the provider reports about the booking — a seat or fare no longer available, say — is returned with its own status, `code` and `message`. Each request books once: repeating a request that succeeded books a second trip, and so may repeating one that failed with a 503, whose outcome at the provider is unknown." }, "parameters": [ { "name": "realmId", "in": "path", "required": true, "description": "ID of your realm.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b" }, { "name": "organizationId", "in": "path", "required": true, "description": "ID of the organization to book the trip for.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "air": { "description": "The flight to book: one air search item. Send exactly one of `air`, `hotel`, `bus` or `vehicle` — a trip is one booked product.", "type": "object", "properties": { "searchItemId": { "type": "string", "pattern": "^srch_item_[0-9A-Za-z]{21}$", "description": "An `id` from the `items` array of the matching air search response (prefix `srch_item_`).", "example": "srch_item_V1StGXR8Z5jdHi6BmyT2k" }, "leadPassengerId": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$", "description": "ID of the passenger responsible for the reservation (24 hexadecimal characters). Must be one of `passengers`.", "example": "6710a3f2c9e77b0012a4d5e1" }, "fareId": { "type": "string", "pattern": "^fare_[0-9A-Za-z]{21}$", "description": "The chosen fare option within the air search item (`fareOptions[].id`, prefix `fare_`).", "example": "fare_V1StGXR8Z5jdHi6BmyT2k" }, "passengers": { "minItems": 1, "type": "array", "items": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$", "example": "6710a3f2c9e77b0012a4d5e1" }, "description": "IDs of the passengers travelling on this fare (24 hexadecimal characters each).\n\n---\n\nExample: `[\"6710a3f2c9e77b0012a4d5e1\"]`" } }, "required": [ "searchItemId", "leadPassengerId", "fareId", "passengers" ] }, "hotel": { "description": "The hotel stay to book: one hotel search item. Send exactly one of `air`, `hotel`, `bus` or `vehicle` — a trip is one booked product.", "type": "object", "properties": { "searchItemId": { "type": "string", "pattern": "^srch_item_[0-9A-Za-z]{21}$", "description": "An `id` from the `items` array of the matching hotel search response (prefix `srch_item_`).", "example": "srch_item_V1StGXR8Z5jdHi6BmyT2k" }, "leadPassengerId": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$", "description": "ID of the passenger responsible for the reservation (24 hexadecimal characters). Must stay in one of the `rooms`.", "example": "6710a3f2c9e77b0012a4d5e1" }, "rooms": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "roomId": { "type": "string", "pattern": "^room_[0-9A-Za-z]{21}$", "description": "The chosen room within the hotel search item (`roomGroups[].rooms[].id`, prefix `room_`).", "example": "room_V1StGXR8Z5jdHi6BmyT2k" }, "passengers": { "minItems": 1, "type": "array", "items": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$", "example": "6710a3f2c9e77b0012a4d5e1" }, "description": "IDs of the passengers staying in this room (24 hexadecimal characters each).\n\n---\n\nExample: `[\"6710a3f2c9e77b0012a4d5e1\"]`" } }, "required": [ "roomId", "passengers" ] }, "description": "The rooms to book, with who stays in each." } }, "required": [ "searchItemId", "leadPassengerId", "rooms" ] }, "bus": { "description": "The bus ticket to book: one passenger on one bus search item — book each passenger as a separate trip. Send exactly one of `air`, `hotel`, `bus` or `vehicle` — a trip is one booked product.", "type": "object", "properties": { "searchItemId": { "type": "string", "pattern": "^srch_item_[0-9A-Za-z]{21}$", "description": "An `id` from the `items` array of the matching bus search response (prefix `srch_item_`).", "example": "srch_item_V1StGXR8Z5jdHi6BmyT2k" }, "leadPassengerId": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$", "description": "ID of the passenger travelling on this ticket (24 hexadecimal characters).", "example": "6710a3f2c9e77b0012a4d5e1" }, "segments": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "segmentId": { "type": "string", "pattern": "^seg_[0-9A-Za-z]{21}$", "description": "A `segments[].id` from the bus search item detail (prefix `seg_`).", "example": "seg_V1StGXR8Z5jdHi6BmyT2k" }, "seatNumber": { "type": "integer", "minimum": 0, "exclusiveMinimum": true, "description": "Seat number to reserve on this segment.", "example": 14 } }, "required": [ "segmentId", "seatNumber" ] }, "description": "The seats to reserve for the passenger, one per leg." } }, "required": [ "searchItemId", "leadPassengerId", "segments" ] }, "vehicle": { "description": "The vehicle rental to book: one vehicle search item. Send exactly one of `air`, `hotel`, `bus` or `vehicle` — a trip is one booked product.", "type": "object", "properties": { "searchItemId": { "type": "string", "pattern": "^srch_item_[0-9A-Za-z]{21}$", "description": "An `id` from the `items` array of the matching vehicle search response (prefix `srch_item_`).", "example": "srch_item_V1StGXR8Z5jdHi6BmyT2k" }, "leadPassengerId": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$", "description": "ID of the passenger responsible for the rental — the driver (24 hexadecimal characters).", "example": "6710a3f2c9e77b0012a4d5e1" }, "fareId": { "type": "string", "pattern": "^fare_[0-9A-Za-z]{21}$", "description": "The chosen fare option within the vehicle search item (`fareOptions[].id`, prefix `fare_`).", "example": "fare_V1StGXR8Z5jdHi6BmyT2k" } }, "required": [ "searchItemId", "leadPassengerId", "fareId" ] }, "customFields": { "description": "Values of the organization's trip custom fields, keyed by the custom field's `slug`. Every required one must be present. They can't be changed after the trip is created.\n\n---\n\nExample: `{\"cost-center\":\"CC-1020\"}`", "example": { "cost-center": "CC-1020" }, "type": "object", "additionalProperties": {} } } } } } }, "responses": { "202": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the trip.", "example": "6711b4c0d8e1a30012b7c9f2" }, "realmId": { "type": "string", "description": "ID of the realm the trip belongs to.", "example": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b", "format": "uuid" }, "organizationId": { "type": "string", "description": "ID of the organization the trip belongs to.", "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410", "format": "uuid" }, "createdBy": { "type": "string", "description": "ID of the user who created the trip. Omitted when a service did.", "example": "e3553bc1-5e20-4e17-b22a-a796fda0aa99", "format": "uuid" }, "customFields": { "type": "object", "additionalProperties": {}, "description": "Values of the organization's trip custom fields, keyed by the custom field's `slug`. Empty when none were set.\n\n---\n\nExample: `{\"cost-center\":\"CC-1020\"}`", "example": { "cost-center": "CC-1020" } }, "vertical": { "type": "string", "enum": [ "AIR", "HOTEL", "BUS", "VEHICLE" ], "description": "Type of product booked. It tells which shape `productSnapshot` has.", "example": "AIR" }, "state": { "type": "string", "enum": [ "PENDING", "RESERVED", "ISSUED", "CANCELED" ], "description": "Where the booking is in its life: `PENDING` while the reservation is being made, `RESERVED` once held (until `reservationExpiresAt`), `ISSUED` once ticketed and `CANCELED`. It only moves forward.", "example": "RESERVED" }, "status": { "type": "string", "enum": [ "PROCESSING_RESERVATION", "RESERVATION_FAILED", "RESERVED", "PROCESSING_ISSUE", "ISSUED", "PROCESSING_CANCELLATION", "CANCELED", "AWAITING_MANUAL_CANCELLATION", "CANCELLATION_FAILED", "FAILED", "FAILED_BY_INCONSISTENT_DATA", "FAILED_BY_UNAVAILABLE_RESOURCE", "FAILED_BY_BUDGET_EXCEEDED", "EXPIRED", "BLOCKED", "UNKNOWN", "ISSUANCE_FAILED" ], "description": "Finer-grained status: it also reports work in progress (`PROCESSING_*`) and failures, and can change back and forth. Use `state` to decide what the booking is; use `status` to tell what is happening to it.", "example": "RESERVED" }, "reservationExpiresAt": { "type": "string", "nullable": true, "description": "Until when the reservation is held. Past it, a trip that was not issued expires. `null` or omitted when there is no hold.", "example": "2026-10-02T13:45:12.000Z", "format": "date-time" }, "issuedAt": { "type": "string", "nullable": true, "description": "When the trip was issued. `null` or omitted until it is.", "format": "date-time" }, "originalAmount": { "type": "number", "description": "Price before discounts, in cents. Omitted until the price is known.", "example": 95000 }, "discountAmount": { "type": "number", "description": "Discount applied, in cents. Omitted until the price is known.", "example": 3010 }, "feeAmount": { "type": "number", "description": "Fees added, in cents. Omitted until the price is known.", "example": 0 }, "totalAmount": { "type": "number", "description": "Amount to pay, in cents: `originalAmount` - `discountAmount` + `feeAmount`. Omitted until the price is known.", "example": 91990 }, "currency": { "type": "string", "description": "Currency of the amounts, as the numeric ISO 4217 code (`986` is BRL).", "example": "986" }, "passengers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the passenger, as returned by the passenger endpoints.", "example": "6710a3f2c9e77b0012a4d5e1" }, "userId": { "type": "string", "description": "ID of the organization user the passenger is linked to. Omitted for a passenger who is not a user. A user sees the trips they travel on.", "example": "e3553bc1-5e20-4e17-b22a-a796fda0aa99", "format": "uuid" }, "lead": { "type": "boolean", "description": "Whether this passenger is the one responsible for the reservation.", "example": true }, "name": { "type": "string", "description": "Full name, as it appears on the passenger's travel documents.", "example": "Mariana Costa" }, "gender": { "type": "string", "enum": [ "MALE", "FEMALE" ], "description": "Gender.", "example": "FEMALE" }, "birthDate": { "type": "string", "description": "Date of birth (`YYYY-MM-DD`).", "example": "1990-04-17" } }, "required": [ "id", "lead", "name", "gender", "birthDate" ], "description": "A passenger of a trip: who travels, as recorded when the trip was booked. The passenger endpoints serve the full profile." }, "description": "The passengers booked on the trip." }, "productSnapshot": { "anyOf": [ { "type": "object", "properties": { "journeys": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the journey, referenced by `tickets[].fares[].journeyId`.", "example": "jour_V1StGXR8Z5jdHi6BmyT2k" }, "direction": { "type": "string", "enum": [ "DEPARTURE", "RETURN" ], "description": "Whether this is the outbound leg (`DEPARTURE`) or the return leg (`RETURN`).", "example": "DEPARTURE" }, "origin": { "type": "object", "properties": { "iata": { "type": "string", "description": "IATA code of the airport, 3 letters.", "example": "GRU" }, "name": { "type": "string", "nullable": true, "description": "Official name of the airport. `null` when unknown.", "example": "São Paulo/Guarulhos International Airport" }, "shortAddress": { "type": "string", "nullable": true, "description": "Readable single-line address of the airport. `null` when unknown.", "example": "Guarulhos, SP, Brazil" }, "locality": { "type": "string", "nullable": true, "description": "City the airport sits in. `null` when unknown.", "example": "Guarulhos" }, "administrativeArea": { "type": "string", "nullable": true, "description": "State, as its short code. `null` when unknown.", "example": "SP" }, "phoneNumbers": { "type": "array", "items": { "type": "string", "example": "551133334444" }, "description": "Contact phone numbers of the airport, digits only. Empty when none is registered.\n\n---\n\nExample: `[\"551133334444\"]`" } }, "required": [ "iata", "name", "shortAddress", "locality", "administrativeArea", "phoneNumbers" ], "description": "Airport the journey starts at." }, "destination": { "type": "object", "properties": { "iata": { "type": "string", "description": "IATA code of the airport, 3 letters.", "example": "GRU" }, "name": { "type": "string", "nullable": true, "description": "Official name of the airport. `null` when unknown.", "example": "São Paulo/Guarulhos International Airport" }, "shortAddress": { "type": "string", "nullable": true, "description": "Readable single-line address of the airport. `null` when unknown.", "example": "Guarulhos, SP, Brazil" }, "locality": { "type": "string", "nullable": true, "description": "City the airport sits in. `null` when unknown.", "example": "Guarulhos" }, "administrativeArea": { "type": "string", "nullable": true, "description": "State, as its short code. `null` when unknown.", "example": "SP" }, "phoneNumbers": { "type": "array", "items": { "type": "string", "example": "551133334444" }, "description": "Contact phone numbers of the airport, digits only. Empty when none is registered.\n\n---\n\nExample: `[\"551133334444\"]`" } }, "required": [ "iata", "name", "shortAddress", "locality", "administrativeArea", "phoneNumbers" ], "description": "Airport the journey ends at.", "example": { "iata": "SDU", "name": "Rio de Janeiro/Santos Dumont Airport", "shortAddress": "Rio de Janeiro, RJ, Brazil", "locality": "Rio de Janeiro", "administrativeArea": "RJ", "phoneNumbers": [ "552133339999" ] } }, "departureDate": { "type": "string", "description": "Departure date and time in the local time of the origin airport, as `YYYY-MM-DDTHH:mm:ss` with no time zone.", "example": "2026-11-02T08:30:00" }, "arrivalDate": { "type": "string", "description": "Arrival date and time in the local time of the destination airport, as `YYYY-MM-DDTHH:mm:ss` with no time zone.", "example": "2026-11-02T09:35:00" }, "duration": { "type": "string", "description": "Total travel time of the journey, connections included, as `HH:mm`.", "example": "01:05" }, "segments": { "type": "array", "items": { "type": "object", "properties": { "airline": { "type": "object", "properties": { "code": { "type": "string", "description": "IATA code of the airline.", "example": "LA" }, "name": { "type": "string", "nullable": true, "description": "Commercial name of the airline. `null` when unknown.", "example": "LATAM Airlines" }, "logo": { "type": "string", "nullable": true, "description": "URL of the airline's logo. `null` when there is none.", "example": "https://cdn.example.com/airlines/LA.png" } }, "required": [ "code", "name", "logo" ], "description": "Airline that sells the flight." }, "operation": { "type": "object", "properties": { "code": { "type": "string", "description": "IATA code of the airline.", "example": "LA" }, "name": { "type": "string", "nullable": true, "description": "Commercial name of the airline. `null` when unknown.", "example": "LATAM Airlines" }, "logo": { "type": "string", "nullable": true, "description": "URL of the airline's logo. `null` when there is none.", "example": "https://cdn.example.com/airlines/LA.png" } }, "required": [ "code", "name", "logo" ], "description": "Airline that operates the flight. It differs from `airline` on codeshare flights." }, "origin": { "type": "object", "properties": { "iata": { "type": "string", "description": "IATA code of the airport, 3 letters.", "example": "GRU" }, "name": { "type": "string", "nullable": true, "description": "Official name of the airport. `null` when unknown.", "example": "São Paulo/Guarulhos International Airport" }, "shortAddress": { "type": "string", "nullable": true, "description": "Readable single-line address of the airport. `null` when unknown.", "example": "Guarulhos, SP, Brazil" }, "locality": { "type": "string", "nullable": true, "description": "City the airport sits in. `null` when unknown.", "example": "Guarulhos" }, "administrativeArea": { "type": "string", "nullable": true, "description": "State, as its short code. `null` when unknown.", "example": "SP" }, "phoneNumbers": { "type": "array", "items": { "type": "string", "example": "551133334444" }, "description": "Contact phone numbers of the airport, digits only. Empty when none is registered.\n\n---\n\nExample: `[\"551133334444\"]`" } }, "required": [ "iata", "name", "shortAddress", "locality", "administrativeArea", "phoneNumbers" ], "description": "Airport the flight leaves from." }, "destination": { "type": "object", "properties": { "iata": { "type": "string", "description": "IATA code of the airport, 3 letters.", "example": "GRU" }, "name": { "type": "string", "nullable": true, "description": "Official name of the airport. `null` when unknown.", "example": "São Paulo/Guarulhos International Airport" }, "shortAddress": { "type": "string", "nullable": true, "description": "Readable single-line address of the airport. `null` when unknown.", "example": "Guarulhos, SP, Brazil" }, "locality": { "type": "string", "nullable": true, "description": "City the airport sits in. `null` when unknown.", "example": "Guarulhos" }, "administrativeArea": { "type": "string", "nullable": true, "description": "State, as its short code. `null` when unknown.", "example": "SP" }, "phoneNumbers": { "type": "array", "items": { "type": "string", "example": "551133334444" }, "description": "Contact phone numbers of the airport, digits only. Empty when none is registered.\n\n---\n\nExample: `[\"551133334444\"]`" } }, "required": [ "iata", "name", "shortAddress", "locality", "administrativeArea", "phoneNumbers" ], "description": "Airport the flight arrives at.", "example": { "iata": "SDU", "name": "Rio de Janeiro/Santos Dumont Airport", "shortAddress": "Rio de Janeiro, RJ, Brazil", "locality": "Rio de Janeiro", "administrativeArea": "RJ", "phoneNumbers": [ "552133339999" ] } }, "flightNumber": { "type": "string", "description": "Number of the flight, without the airline's code.", "example": "3101" }, "departureDate": { "type": "string", "description": "Departure date and time in the local time of the departure airport, as `YYYY-MM-DDTHH:mm:ss` with no time zone.", "example": "2026-11-02T08:30:00" }, "arrivalDate": { "type": "string", "description": "Arrival date and time in the local time of the arrival airport, as `YYYY-MM-DDTHH:mm:ss` with no time zone.", "example": "2026-11-02T09:35:00" }, "flightType": { "type": "string", "enum": [ "CHARTER", "ALLOTMENT", "REGULAR" ], "description": "Kind of flight: `REGULAR`, `CHARTER` or `ALLOTMENT`.", "example": "REGULAR" }, "duration": { "type": "string", "description": "Duration of the flight, as `HH:mm`.", "example": "01:05" }, "equipment": { "type": "string", "nullable": true, "description": "Aircraft scheduled for the flight, as the airline identifies it. `null` when not informed.", "example": "32Q" }, "cabin": { "type": "string", "enum": [ "ECONOMY", "PREMIUM_ECONOMY", "BUSINESS", "FIRST_CLASS", "UNDEFINED" ], "description": "Cabin booked for the flight.", "example": "ECONOMY" }, "class": { "type": "string", "nullable": true, "description": "Booking class (RBD) priced for the flight. Each airline defines its own codes. `null` when the airline does not expose it.", "example": "Y" }, "fareBasis": { "type": "string", "nullable": true, "description": "Fare basis code priced for the flight. Each airline defines its own codes. `null` when the airline does not expose it.", "example": "YOW" }, "flightInfo": { "description": "Live information about the flight. `null` until it is first collected, as the departure approaches.", "example": null, "type": "object", "properties": { "state": { "type": "string", "nullable": true, "enum": [ "SCHEDULED", "OUT_GATE", "IN_AIR", "LANDED", "IN_GATE", "CANCELED", "PROPOSED", "UNKNOWN", null ], "description": "Operational state of the flight. `null` when there is no live status yet.", "example": "SCHEDULED" }, "updatedAt": { "type": "string", "nullable": true, "description": "When the live status was captured. `null` when there is no live status yet.", "example": "2026-11-01T18:00:00.000Z" }, "aircraft": { "description": "Aircraft operating the flight. `null` when not known yet.", "type": "object", "properties": { "registration": { "type": "string", "nullable": true, "description": "Tail registration of the aircraft. `null` when not known yet.", "example": "PR-XBA" }, "type": { "type": "string", "nullable": true, "description": "ICAO code of the aircraft type. `null` when not known yet.", "example": "A21N" } }, "required": [ "registration", "type" ], "nullable": true }, "departure": { "type": "object", "properties": { "terminal": { "type": "string", "nullable": true, "description": "Terminal at the airport. `null` when not reported yet.", "example": "2" }, "gate": { "type": "string", "nullable": true, "description": "Gate at the airport. `null` when not reported yet.", "example": "B12" }, "baggage": { "type": "string", "nullable": true, "description": "Baggage belt, reported for arrivals only. `null` for departures and when not reported yet.", "example": "04" }, "estimatedTime": { "type": "string", "nullable": true, "description": "Estimated time at the gate, in UTC (ISO 8601). `null` when not known yet.", "example": "2026-11-02T11:30:00.000Z" }, "actualTime": { "type": "string", "nullable": true, "description": "Actual time at the gate, in UTC (ISO 8601), reported once the flight operates. `null` before that.", "example": "2026-11-02T11:34:00.000Z" }, "timeliness": { "type": "string", "nullable": true, "description": "Punctuality of the flight, such as `OnTime`, `Early` or `Delayed`. `null` when not known.", "example": "OnTime" }, "delayMinutes": { "type": "number", "nullable": true, "description": "Delay in minutes; negative when the flight is ahead of schedule. `null` when not known.", "example": 4 } }, "required": [ "terminal", "gate", "baggage", "estimatedTime", "actualTime", "timeliness", "delayMinutes" ], "description": "Live status at the departure airport." }, "arrival": { "type": "object", "properties": { "terminal": { "type": "string", "nullable": true, "description": "Terminal at the airport. `null` when not reported yet.", "example": "2" }, "gate": { "type": "string", "nullable": true, "description": "Gate at the airport. `null` when not reported yet.", "example": "B12" }, "baggage": { "type": "string", "nullable": true, "description": "Baggage belt, reported for arrivals only. `null` for departures and when not reported yet.", "example": "04" }, "estimatedTime": { "type": "string", "nullable": true, "description": "Estimated time at the gate, in UTC (ISO 8601). `null` when not known yet.", "example": "2026-11-02T11:30:00.000Z" }, "actualTime": { "type": "string", "nullable": true, "description": "Actual time at the gate, in UTC (ISO 8601), reported once the flight operates. `null` before that.", "example": "2026-11-02T11:34:00.000Z" }, "timeliness": { "type": "string", "nullable": true, "description": "Punctuality of the flight, such as `OnTime`, `Early` or `Delayed`. `null` when not known.", "example": "OnTime" }, "delayMinutes": { "type": "number", "nullable": true, "description": "Delay in minutes; negative when the flight is ahead of schedule. `null` when not known.", "example": 4 } }, "required": [ "terminal", "gate", "baggage", "estimatedTime", "actualTime", "timeliness", "delayMinutes" ], "description": "Live status at the arrival airport." } }, "required": [ "state", "updatedAt", "aircraft", "departure", "arrival" ], "nullable": true } }, "required": [ "airline", "operation", "origin", "destination", "flightNumber", "departureDate", "arrivalDate", "flightType", "duration", "equipment", "cabin", "class", "fareBasis", "flightInfo" ], "description": "One flight of a journey. A journey with connections has several." }, "description": "Flights of the journey, in chronological order, connections included." } }, "required": [ "id", "direction", "origin", "destination", "departureDate", "arrivalDate", "duration", "segments" ], "description": "One leg of the itinerary: the whole way from an origin to a destination, connections included." }, "description": "Legs of the itinerary, in travel order: one for a one-way trip, two (outbound and return) for a round trip." }, "tickets": { "type": "array", "items": { "type": "object", "properties": { "passengerId": { "type": "string", "description": "ID of the passenger holding this ticket — one of the trip's `passengers[]`. Omitted only if the passenger could not be matched to the trip's passengers.", "example": "6710a3f2c9e77b0012a4d5e1" }, "fareDescription": { "type": "string", "description": "Readable description of the fare of the ticket.", "example": "GRU to SDU, LATAM Airlines, Economy" }, "ticketNumber": { "type": "string", "nullable": true, "description": "Number of the ticket, as the airline issued it. `null` until the ticket is issued.", "example": null }, "fares": { "type": "array", "items": { "type": "object", "properties": { "journeyId": { "type": "string", "nullable": true, "description": "ID of the journey this fare covers — a `journeys[].id`. `null` when the fare covers the whole itinerary.", "example": "jour_V1StGXR8Z5jdHi6BmyT2k" }, "currency": { "type": "string", "description": "Currency, as the ISO 4217 alphabetic code.", "example": "BRL" }, "originalAmount": { "type": "number", "description": "Fare before discounts and fees, in cents.", "example": 95000 }, "discountAmount": { "type": "number", "description": "Discount applied to the fare, in cents.", "example": 3010 }, "feeAmount": { "type": "number", "description": "Fees added to the fare, in cents.", "example": 0 }, "amount": { "type": "number", "description": "Total charged for the fare, in cents: `originalAmount` - `discountAmount` + `feeAmount`.", "example": 91990 }, "cancellationPolicies": { "type": "object", "properties": { "refundable": { "type": "boolean", "description": "Whether cancelling gives any money back.", "example": true }, "immediateFine": { "type": "boolean", "description": "Whether a fine applies to a cancellation made right after the booking.", "example": false }, "penalties": { "type": "array", "items": { "type": "object", "properties": { "from": { "type": "string", "description": "First day (`YYYY-MM-DD`) on which this tier applies.", "example": "2026-10-25" }, "currency": { "type": "string", "description": "Currency, as the ISO 4217 alphabetic code.", "example": "BRL" }, "fineAmount": { "type": "number", "nullable": true, "description": "Fine charged for cancelling from `from` onward, in cents. `null` when the amount is not available.", "example": 15000 } }, "required": [ "from", "currency", "fineAmount" ], "description": "One tier of a cancellation penalty schedule." }, "description": "Penalty tiers, each in effect from its own date. Empty when no scheduled penalty applies." } }, "required": [ "refundable", "immediateFine", "penalties" ], "description": "Cancellation rules of the fare." }, "changePolicies": { "type": "object", "properties": { "canChange": { "type": "boolean", "description": "Whether the fare allows the booking to be changed.", "example": true }, "immediateFine": { "type": "boolean", "description": "Whether a fine applies to a change made right after the booking.", "example": false }, "penalties": { "type": "array", "items": { "type": "object", "properties": { "from": { "type": "string", "description": "First day (`YYYY-MM-DD`) on which this tier applies.", "example": "2026-10-25" }, "currency": { "type": "string", "description": "Currency, as the ISO 4217 alphabetic code.", "example": "BRL" }, "fineAmount": { "type": "number", "nullable": true, "description": "Fine charged for changing the booking from `from` onward, in cents. `null` when the amount is not available.", "example": 8000 } }, "required": [ "from", "currency", "fineAmount" ], "description": "One tier of a change penalty schedule." }, "description": "Penalty tiers, each in effect from its own date. Empty when no scheduled penalty applies." } }, "required": [ "canChange", "immediateFine", "penalties" ], "description": "Change rules of the fare." } }, "required": [ "journeyId", "currency", "originalAmount", "discountAmount", "feeAmount", "amount", "cancellationPolicies", "changePolicies" ], "description": "The fare of a ticket for one journey, or for the whole itinerary. Amounts are integers in cents." }, "description": "Fares of the ticket: one per journey, or a single one for the whole itinerary." }, "segments": { "type": "array", "items": { "type": "object", "properties": { "flightNumber": { "type": "string", "description": "Number of the flight this ticket covers, without the airline's code. It matches the `flightNumber` of one of the journeys' `segments`.", "example": "3101" }, "cabin": { "type": "string", "enum": [ "ECONOMY", "PREMIUM_ECONOMY", "BUSINESS", "FIRST_CLASS", "UNDEFINED" ], "description": "Cabin of the ticket on this flight.", "example": "ECONOMY" }, "class": { "type": "string", "nullable": true, "description": "Booking class (RBD) of the ticket on this flight. Each airline defines its own codes. `null` when the airline does not expose it.", "example": "Y" }, "fareBasis": { "type": "string", "nullable": true, "description": "Fare basis code of the ticket on this flight. Each airline defines its own codes. `null` when the airline does not expose it.", "example": "YOW" }, "baggages": { "type": "array", "items": { "type": "object", "properties": { "quantity": { "type": "number", "description": "Number of pieces included in the allowance.", "example": 1 }, "weight": { "type": "number", "nullable": true, "description": "Weight allowed per piece, in kg. `null` when the airline sets no weight limit per piece.", "example": 23 }, "type": { "type": "string", "enum": [ "CHECKED", "CARRY_ON", "PERSONAL_ITEM" ], "description": "Kind of baggage: `CHECKED`, `CARRY_ON` or `PERSONAL_ITEM`.", "example": "CHECKED" } }, "required": [ "quantity", "weight", "type" ], "description": "A baggage allowance of a ticket on one flight." }, "description": "Baggage allowance of the ticket on this flight. Empty for an infant on an adult's lap." } }, "required": [ "flightNumber", "cabin", "class", "fareBasis", "baggages" ], "description": "What a ticket covers on one flight of the itinerary: the cabin, the fare codes and the baggage allowance." }, "description": "What the ticket covers on each flight of the itinerary." } }, "required": [ "fareDescription", "ticketNumber", "fares", "segments" ], "description": "The ticket of one passenger. It covers the whole itinerary, with a fare per journey or a single fare for all of it." }, "description": "Tickets of the booking, one per passenger, each covering the whole itinerary." }, "locators": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "Kind of reference, such as `PNR` for an airline's booking code.", "example": "PNR" }, "code": { "type": "string", "description": "The reference itself, as the supplier issued it.", "example": "ABC123" } }, "required": [ "type", "code" ], "description": "A reference that identifies the booking with the supplier, such as an airline's booking code." }, "description": "Booking references issued by the airlines. Empty until the reservation is confirmed." }, "flightInfoUpdatedAt": { "type": "string", "nullable": true, "description": "When the live flight information was last collected. `null` until it is first collected.", "example": null, "format": "date-time" } }, "required": [ "journeys", "tickets", "locators", "flightInfoUpdatedAt" ], "description": "The booked flight: itinerary, the ticket of each passenger (by ID) with its fares and baggage, and reservation locators. This is the shape of `productSnapshot` when the trip's `vertical` is `AIR`. Amounts are integers in cents.", "title": "Air trip" }, { "type": "object", "properties": { "hotel": { "type": "object", "properties": { "name": { "type": "string", "description": "Official name of the hotel.", "example": "Hotel Paulista Plaza" }, "chain": { "type": "object", "properties": { "brandName": { "type": "string", "nullable": true, "description": "Brand within the chain. `null` when not informed.", "example": "Ibis" }, "chainName": { "type": "string", "nullable": true, "description": "Name of the chain. `null` for an independent hotel.", "example": "Accor" }, "logo": { "type": "string", "nullable": true, "description": "URL of the chain's logo. `null` when the hotel has no chain with a registered logo.", "example": "https://cdn.example.com/hotels/ibis.svg" } }, "required": [ "brandName", "chainName", "logo" ], "description": "Chain and brand of the hotel." }, "shortAddress": { "type": "string", "nullable": true, "description": "Readable single-line address of the hotel. `null` when unknown.", "example": "Av. Paulista, 1500, São Paulo, SP, Brazil" }, "phoneNumbers": { "type": "array", "items": { "type": "string", "example": "551133335555" }, "description": "Contact phone numbers of the hotel, digits only. Empty when none is registered.\n\n---\n\nExample: `[\"551133335555\"]`" }, "locality": { "type": "string", "nullable": true, "description": "City the hotel sits in. `null` when unknown.", "example": "São Paulo" }, "administrativeArea": { "type": "string", "nullable": true, "description": "State, as its short code. `null` when unknown.", "example": "SP" }, "checkInTime": { "type": "string", "nullable": true, "description": "Time of day, in the hotel's local time (`HH:mm`), from which guests can check in. `null` when unknown.", "example": "14:00" }, "checkOutTime": { "type": "string", "nullable": true, "description": "Time of day, in the hotel's local time (`HH:mm`), by which guests must check out. `null` when unknown.", "example": "12:00" } }, "required": [ "name", "chain", "shortAddress", "phoneNumbers", "locality", "administrativeArea", "checkInTime", "checkOutTime" ], "description": "Hotel where the stay is booked." }, "checkIn": { "type": "string", "description": "Check-in date (`YYYY-MM-DD`).", "example": "2026-11-02" }, "checkOut": { "type": "string", "description": "Check-out date (`YYYY-MM-DD`).", "example": "2026-11-04" }, "rooms": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the room, as the hotel offers it.", "example": "Standard Room, 1 Queen Bed" }, "fare": { "type": "object", "properties": { "currency": { "type": "string", "description": "Currency, as the ISO 4217 alphabetic code.", "example": "BRL" }, "originalAmount": { "type": "number", "description": "Fare before discounts and fees, in cents.", "example": 120000 }, "discountAmount": { "type": "number", "description": "Discount applied to the fare, in cents.", "example": 8000 }, "feeAmount": { "type": "number", "description": "Fees added to the fare, in cents.", "example": 0 }, "amount": { "type": "number", "description": "Total charged for the fare, in cents: `originalAmount` - `discountAmount` + `feeAmount`.", "example": 112000 }, "boardType": { "type": "string", "enum": [ "ONLY_ROOM", "BREAKFAST", "HALF_BOARD", "FULL_BOARD", "ALL_INCLUSIVE" ], "description": "Meals included in the fare.", "example": "BREAKFAST" }, "cancellationPolicies": { "type": "object", "properties": { "refundable": { "type": "boolean", "description": "Whether cancelling gives any money back.", "example": true }, "immediateFine": { "type": "boolean", "description": "Whether a fine applies to a cancellation made right after the booking.", "example": false }, "penalties": { "type": "array", "items": { "type": "object", "properties": { "from": { "type": "string", "description": "First day (`YYYY-MM-DD`) on which this tier applies.", "example": "2026-10-25" }, "currency": { "type": "string", "description": "Currency, as the ISO 4217 alphabetic code.", "example": "BRL" }, "fineAmount": { "type": "number", "nullable": true, "description": "Fine charged for cancelling from `from` onward, in cents. `null` when the amount is not available.", "example": 15000 } }, "required": [ "from", "currency", "fineAmount" ], "description": "One tier of a cancellation penalty schedule." }, "description": "Penalty tiers, each in effect from its own date. Empty when no scheduled penalty applies." } }, "required": [ "refundable", "immediateFine", "penalties" ], "description": "Cancellation rules of the fare." } }, "required": [ "currency", "originalAmount", "discountAmount", "feeAmount", "amount", "boardType", "cancellationPolicies" ], "description": "Fare of the room." }, "passengersId": { "type": "array", "items": { "type": "string", "example": "6710a3f2c9e77b0012a4d5e1" }, "description": "IDs of the passengers staying in this room — the trip's `passengers[]`.\n\n---\n\nExample: `[\"6710a3f2c9e77b0012a4d5e1\"]`" } }, "required": [ "name", "fare", "passengersId" ], "description": "A booked room." }, "description": "Rooms booked for the stay." }, "locators": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "Kind of reference, such as `PNR` for an airline's booking code.", "example": "PNR" }, "code": { "type": "string", "description": "The reference itself, as the supplier issued it.", "example": "ABC123" } }, "required": [ "type", "code" ], "description": "A reference that identifies the booking with the supplier, such as an airline's booking code." }, "description": "Booking references issued by the hotel. Empty until the reservation is confirmed." } }, "required": [ "hotel", "checkIn", "checkOut", "rooms", "locators" ], "description": "The booked hotel stay: the hotel, the dates, the rooms with their fares and guests (by ID), and the reservation locators. This is the shape of `productSnapshot` when the trip's `vertical` is `HOTEL`. Amounts are integers in cents.", "title": "Hotel trip" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "DIRECT", "CONNECTION", "ONE_STOP" ], "description": "Kind of trip: `DIRECT`, `CONNECTION` or `ONE_STOP`.", "example": "DIRECT" }, "origin": { "type": "object", "properties": { "locality": { "type": "string", "description": "City the station sits in.", "example": "São Paulo" }, "administrativeArea": { "type": "string", "description": "State, as its short code.", "example": "SP" }, "name": { "type": "string", "nullable": true, "description": "Official name of the station. `null` when unknown.", "example": "Terminal Rodoviário Tietê" }, "shortAddress": { "type": "string", "nullable": true, "description": "Readable single-line address of the station. `null` when unknown.", "example": "Av. Cruzeiro do Sul, 1800, São Paulo, SP, Brazil" }, "phoneNumbers": { "type": "array", "items": { "type": "string", "example": "551133336666" }, "description": "Contact phone numbers of the station, digits only. Empty when none is registered.\n\n---\n\nExample: `[\"551133336666\"]`" } }, "required": [ "locality", "administrativeArea", "name", "shortAddress", "phoneNumbers" ], "description": "Station the trip starts at." }, "destination": { "type": "object", "properties": { "locality": { "type": "string", "description": "City the station sits in.", "example": "São Paulo" }, "administrativeArea": { "type": "string", "description": "State, as its short code.", "example": "SP" }, "name": { "type": "string", "nullable": true, "description": "Official name of the station. `null` when unknown.", "example": "Terminal Rodoviário Tietê" }, "shortAddress": { "type": "string", "nullable": true, "description": "Readable single-line address of the station. `null` when unknown.", "example": "Av. Cruzeiro do Sul, 1800, São Paulo, SP, Brazil" }, "phoneNumbers": { "type": "array", "items": { "type": "string", "example": "551133336666" }, "description": "Contact phone numbers of the station, digits only. Empty when none is registered.\n\n---\n\nExample: `[\"551133336666\"]`" } }, "required": [ "locality", "administrativeArea", "name", "shortAddress", "phoneNumbers" ], "description": "Station the trip ends at.", "example": { "locality": "Rio de Janeiro", "administrativeArea": "RJ", "name": "Rodoviária Novo Rio", "shortAddress": "Av. Francisco Bicalho, 1, Rio de Janeiro, RJ, Brazil", "phoneNumbers": [ "552133338888" ] } }, "departureDate": { "type": "string", "description": "Departure date and time in the local time of the origin station, as `YYYY-MM-DDTHH:mm:ss` with no time zone.", "example": "2026-11-02T08:30:00" }, "arrivalDate": { "type": "string", "description": "Arrival date and time in the local time of the destination station, as `YYYY-MM-DDTHH:mm:ss` with no time zone.", "example": "2026-11-02T14:45:00" }, "company": { "type": "object", "properties": { "name": { "type": "string", "description": "Commercial name of the company.", "example": "Expresso Brasileiro" }, "logo": { "type": "string", "nullable": true, "description": "URL of the company's logo. `null` when there is none.", "example": "https://cdn.example.com/bus/expresso-brasileiro.png" } }, "required": [ "name", "logo" ], "description": "Company that operates the trip." }, "passengerId": { "type": "string", "description": "ID of the passenger travelling on this ticket — one of the trip's `passengers[]`. Omitted only if the passenger could not be matched to the trip's passengers.", "example": "6710a3f2c9e77b0012a4d5e1" }, "segments": { "type": "array", "items": { "type": "object", "properties": { "seatNumber": { "type": "number", "description": "Seat reserved on the segment.", "example": 12 }, "serviceClass": { "type": "string", "enum": [ "SLEEPER_BED", "BED", "SEMI_BED", "EXECUTIVE", "CONVENTIONAL", "UNDEFINED" ], "description": "Class of service booked for the segment.", "example": "EXECUTIVE" }, "origin": { "type": "object", "properties": { "locality": { "type": "string", "description": "City the station sits in.", "example": "São Paulo" }, "administrativeArea": { "type": "string", "description": "State, as its short code.", "example": "SP" }, "name": { "type": "string", "nullable": true, "description": "Official name of the station. `null` when unknown.", "example": "Terminal Rodoviário Tietê" }, "shortAddress": { "type": "string", "nullable": true, "description": "Readable single-line address of the station. `null` when unknown.", "example": "Av. Cruzeiro do Sul, 1800, São Paulo, SP, Brazil" }, "phoneNumbers": { "type": "array", "items": { "type": "string", "example": "551133336666" }, "description": "Contact phone numbers of the station, digits only. Empty when none is registered.\n\n---\n\nExample: `[\"551133336666\"]`" } }, "required": [ "locality", "administrativeArea", "name", "shortAddress", "phoneNumbers" ], "description": "Station the segment leaves from." }, "destination": { "type": "object", "properties": { "locality": { "type": "string", "description": "City the station sits in.", "example": "São Paulo" }, "administrativeArea": { "type": "string", "description": "State, as its short code.", "example": "SP" }, "name": { "type": "string", "nullable": true, "description": "Official name of the station. `null` when unknown.", "example": "Terminal Rodoviário Tietê" }, "shortAddress": { "type": "string", "nullable": true, "description": "Readable single-line address of the station. `null` when unknown.", "example": "Av. Cruzeiro do Sul, 1800, São Paulo, SP, Brazil" }, "phoneNumbers": { "type": "array", "items": { "type": "string", "example": "551133336666" }, "description": "Contact phone numbers of the station, digits only. Empty when none is registered.\n\n---\n\nExample: `[\"551133336666\"]`" } }, "required": [ "locality", "administrativeArea", "name", "shortAddress", "phoneNumbers" ], "description": "Station the segment arrives at.", "example": { "locality": "Rio de Janeiro", "administrativeArea": "RJ", "name": "Rodoviária Novo Rio", "shortAddress": "Av. Francisco Bicalho, 1, Rio de Janeiro, RJ, Brazil", "phoneNumbers": [ "552133338888" ] } }, "departureDate": { "type": "string", "description": "Departure date and time in the local time of the origin station, as `YYYY-MM-DDTHH:mm:ss` with no time zone.", "example": "2026-11-02T08:30:00" }, "arrivalDate": { "type": "string", "description": "Arrival date and time in the local time of the destination station, as `YYYY-MM-DDTHH:mm:ss` with no time zone.", "example": "2026-11-02T14:45:00" }, "duration": { "type": "string", "nullable": true, "description": "Duration of the leg, as `HH:mm`. `null` when not available.", "example": "06:15" }, "fare": { "type": "object", "properties": { "originalAmount": { "type": "number", "description": "Fare before discounts and fees, in cents.", "example": 18000 }, "discountAmount": { "type": "number", "description": "Discount applied to the fare, in cents.", "example": 1000 }, "feeAmount": { "type": "number", "description": "Fees added to the fare, in cents.", "example": 500 }, "amount": { "type": "number", "description": "Total charged for the fare, in cents: `originalAmount` - `discountAmount` + `feeAmount`.", "example": 17500 }, "currency": { "type": "string", "description": "Currency, as the ISO 4217 alphabetic code.", "example": "BRL" }, "cancellationPolicies": { "type": "object", "properties": { "refundable": { "type": "boolean", "description": "Whether cancelling gives any money back.", "example": true }, "immediateFine": { "type": "boolean", "description": "Whether a fine applies to a cancellation made right after the booking.", "example": false }, "penalties": { "type": "array", "items": { "type": "object", "properties": { "from": { "type": "string", "description": "First day (`YYYY-MM-DD`) on which this tier applies.", "example": "2026-10-25" }, "currency": { "type": "string", "description": "Currency, as the ISO 4217 alphabetic code.", "example": "BRL" }, "fineAmount": { "type": "number", "nullable": true, "description": "Fine charged for cancelling from `from` onward, in cents. `null` when the amount is not available.", "example": 15000 } }, "required": [ "from", "currency", "fineAmount" ], "description": "One tier of a cancellation penalty schedule." }, "description": "Penalty tiers, each in effect from its own date. Empty when no scheduled penalty applies." } }, "required": [ "refundable", "immediateFine", "penalties" ], "description": "Cancellation rules of the fare." } }, "required": [ "originalAmount", "discountAmount", "feeAmount", "amount", "currency", "cancellationPolicies" ], "description": "Fare of the segment." }, "company": { "type": "object", "properties": { "name": { "type": "string", "description": "Commercial name of the company.", "example": "Expresso Brasileiro" }, "logo": { "type": "string", "nullable": true, "description": "URL of the company's logo. `null` when there is none.", "example": "https://cdn.example.com/bus/expresso-brasileiro.png" } }, "required": [ "name", "logo" ], "description": "Operator running this leg." } }, "required": [ "seatNumber", "serviceClass", "origin", "destination", "departureDate", "arrivalDate", "duration", "fare", "company" ], "description": "One leg of the bus trip, with the seat booked on it." }, "description": "Segments of the trip, one per leg, each with its seat, fare and operator." }, "routeDirection": { "type": "string", "enum": [ "DEPARTURE", "RETURN" ], "description": "Whether this booking is the outbound trip (`DEPARTURE`) or the return trip (`RETURN`).", "example": "DEPARTURE" }, "boardingInfo": { "description": "Boarding pass and, per leg, platform and ticket codes. `null` until it is first collected, as the departure approaches.", "example": null, "type": "object", "properties": { "boardingPass": { "type": "string", "nullable": true, "description": "The boarding pass PDF, base64-encoded. `null` when not available yet.", "example": "JVBERi0xLjcK" }, "routes": { "type": "array", "items": { "type": "object", "properties": { "origin": { "type": "string", "description": "City the leg starts in.", "example": "São Paulo" }, "destination": { "type": "string", "description": "City the leg ends in.", "example": "Rio de Janeiro" }, "platform": { "type": "string", "nullable": true, "description": "Boarding platform at the origin station. `null` when not assigned or not applicable.", "example": "14" }, "departureDate": { "type": "string", "description": "Departure date and time in local time, as `YYYY-MM-DDTHH:mm:ss` with no time zone.", "example": "2026-11-02T08:30:00" }, "arrivalDate": { "type": "string", "description": "Arrival date and time in local time, as `YYYY-MM-DDTHH:mm:ss` with no time zone.", "example": "2026-11-02T14:45:00" }, "tickets": { "type": "array", "items": { "type": "object", "properties": { "passengerId": { "type": "string", "description": "ID of the passenger the ticket belongs to — one of the trip's `passengers[]`. Omitted only if the passenger could not be matched to the trip's passengers.", "example": "6710a3f2c9e77b0012a4d5e1" }, "locators": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "Kind of reference, such as `PNR` for an airline's booking code.", "example": "PNR" }, "code": { "type": "string", "description": "The reference itself, as the supplier issued it.", "example": "ABC123" } }, "required": [ "type", "code" ], "description": "A reference that identifies the booking with the supplier, such as an airline's booking code." }, "description": "Booking references of the ticket. Empty when none is available." }, "ticketCode": { "type": "string", "nullable": true, "description": "Code of the ticket. `null` when not available.", "example": "EB123456" }, "qrCode": { "type": "string", "nullable": true, "description": "The boarding QR code image, base64-encoded. `null` when not available.", "example": "iVBORw0KGgo=" }, "bpeNumber": { "type": "string", "nullable": true, "description": "Number of the electronic bus ticket (BP-e). `null` when not available.", "example": "35261112345678000190630010000123451000123456" } }, "required": [ "locators", "ticketCode", "qrCode", "bpeNumber" ], "description": "The boarding ticket of one passenger on one leg." }, "description": "Tickets of the leg, one per passenger." } }, "required": [ "origin", "destination", "platform", "departureDate", "arrivalDate", "tickets" ], "description": "The boarding details of one leg of the trip." }, "description": "Boarding details per leg. A connection has two legs; direct and one-stop trips have one." } }, "required": [ "boardingPass", "routes" ], "nullable": true } }, "required": [ "type", "origin", "destination", "departureDate", "arrivalDate", "company", "segments", "routeDirection", "boardingInfo" ], "description": "The booked bus trip of one passenger (by ID): stations, operator, the legs with their seats and fares, and boarding information. This is the shape of `productSnapshot` when the trip's `vertical` is `BUS`. Amounts are integers in cents.", "title": "Bus trip" }, { "type": "object", "properties": { "groupName": { "type": "string", "description": "Commercial group the vehicle belongs to, such as `ECONOMY` or `SUV`.", "example": "ECONOMY" }, "class": { "type": "string", "description": "Class of the vehicle within its group.", "example": "INTERMEDIATE" }, "name": { "type": "string", "description": "Name of the vehicle, as the rental company displays it.", "example": "Fiat Mobi" }, "sipp": { "type": "string", "description": "SIPP code that classifies the vehicle by size, doors, transmission and fuel.", "example": "ECMR" }, "rentalCompany": { "type": "object", "properties": { "code": { "type": "string", "description": "Code of the rental company.", "example": "LOC" }, "name": { "type": "string", "description": "Commercial name of the rental company.", "example": "Localiza" }, "logo": { "type": "string", "nullable": true, "description": "URL of the rental company's logo. `null` when the company has no registered logo.", "example": "https://cdn.example.com/rentals/localiza.svg" } }, "required": [ "code", "name", "logo" ], "description": "Rental company that holds the booking." }, "pickUpLocation": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the rental location.", "example": "Localiza Aeroporto Guarulhos (GRU)" }, "phoneNumbers": { "type": "array", "items": { "type": "string", "example": "551133337777" }, "description": "Contact phone numbers of the location, digits only. Empty when none is registered.\n\n---\n\nExample: `[\"551133337777\"]`" }, "shortAddress": { "type": "string", "nullable": true, "description": "Readable single-line address of the location. `null` when unknown.", "example": "Rod. Hélio Smidt, s/n, Guarulhos, SP, Brazil" }, "locality": { "type": "string", "nullable": true, "description": "City the location sits in. `null` when unknown.", "example": "Guarulhos" }, "administrativeArea": { "type": "string", "nullable": true, "description": "State, as its short code. `null` when unknown.", "example": "SP" } }, "required": [ "name", "phoneNumbers", "shortAddress", "locality", "administrativeArea" ], "description": "Where the vehicle is picked up." }, "dropOffLocation": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the rental location.", "example": "Localiza Aeroporto Guarulhos (GRU)" }, "phoneNumbers": { "type": "array", "items": { "type": "string", "example": "551133337777" }, "description": "Contact phone numbers of the location, digits only. Empty when none is registered.\n\n---\n\nExample: `[\"551133337777\"]`" }, "shortAddress": { "type": "string", "nullable": true, "description": "Readable single-line address of the location. `null` when unknown.", "example": "Rod. Hélio Smidt, s/n, Guarulhos, SP, Brazil" }, "locality": { "type": "string", "nullable": true, "description": "City the location sits in. `null` when unknown.", "example": "Guarulhos" }, "administrativeArea": { "type": "string", "nullable": true, "description": "State, as its short code. `null` when unknown.", "example": "SP" } }, "required": [ "name", "phoneNumbers", "shortAddress", "locality", "administrativeArea" ], "description": "Where the vehicle is dropped off." }, "pickUpDate": { "type": "string", "description": "Pick-up date and time in the local time of the pick-up location, as `YYYY-MM-DDTHH:mm:ss` with no time zone.", "example": "2026-11-02T10:00:00" }, "dropOffDate": { "type": "string", "description": "Drop-off date and time in the local time of the drop-off location, as `YYYY-MM-DDTHH:mm:ss` with no time zone.", "example": "2026-11-04T10:00:00" }, "rentals": { "type": "array", "items": { "type": "object", "properties": { "description": { "type": "string", "nullable": true, "description": "Readable description of the rental option. `null` when not provided.", "example": "Compact car, air conditioning, unlimited mileage" }, "fare": { "type": "object", "properties": { "originalAmount": { "type": "number", "description": "Fare before discounts and fees, in cents.", "example": 36000 }, "discountAmount": { "type": "number", "description": "Discount applied to the fare, in cents.", "example": 2000 }, "feeAmount": { "type": "number", "description": "Fees added to the fare, in cents.", "example": 0 }, "amount": { "type": "number", "description": "Total charged for the fare, in cents: `originalAmount` - `discountAmount` + `feeAmount`.", "example": 34000 }, "currency": { "type": "string", "description": "Currency, as the ISO 4217 alphabetic code.", "example": "BRL" }, "cancellationPolicies": { "type": "object", "properties": { "refundable": { "type": "boolean", "description": "Whether cancelling gives any money back.", "example": true }, "immediateFine": { "type": "boolean", "description": "Whether a fine applies to a cancellation made right after the booking.", "example": false }, "penalties": { "type": "array", "items": { "type": "object", "properties": { "from": { "type": "string", "nullable": true, "description": "First day (`YYYY-MM-DD`) on which this tier applies. `null` when the supplier gave no date.", "example": "2026-10-31" }, "currency": { "type": "string", "description": "Currency, as the ISO 4217 alphabetic code.", "example": "BRL" }, "fineAmount": { "type": "number", "nullable": true, "description": "Fine charged for cancelling from `from` onward, in cents. `null` when the amount is not available.", "example": 12000 } }, "required": [ "from", "currency", "fineAmount" ], "description": "One tier of the cancellation penalty schedule of a rental." }, "description": "Penalty tiers, each in effect from its own date. Empty when no scheduled penalty applies." } }, "required": [ "refundable", "immediateFine", "penalties" ], "description": "Cancellation rules of the fare." } }, "required": [ "originalAmount", "discountAmount", "feeAmount", "amount", "currency", "cancellationPolicies" ], "description": "Fare of the rental." }, "passengersId": { "type": "array", "items": { "type": "string", "example": "6710a3f2c9e77b0012a4d5e1" }, "description": "IDs of the passengers travelling on this rental — the trip's `passengers[]`. Empty when none was assigned.\n\n---\n\nExample: `[\"6710a3f2c9e77b0012a4d5e1\"]`" }, "locators": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "Kind of reference, such as `PNR` for an airline's booking code.", "example": "PNR" }, "code": { "type": "string", "description": "The reference itself, as the supplier issued it.", "example": "ABC123" } }, "required": [ "type", "code" ], "description": "A reference that identifies the booking with the supplier, such as an airline's booking code." }, "description": "Booking references of the rental with the rental company. Empty until the reservation is confirmed." } }, "required": [ "description", "fare", "passengersId", "locators" ], "description": "A booked rental." }, "description": "Rentals booked under this record." }, "locators": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "Kind of reference, such as `PNR` for an airline's booking code.", "example": "PNR" }, "code": { "type": "string", "description": "The reference itself, as the supplier issued it.", "example": "ABC123" } }, "required": [ "type", "code" ], "description": "A reference that identifies the booking with the supplier, such as an airline's booking code." }, "description": "Booking references of the reservation as a whole. Empty until the reservation is confirmed." } }, "required": [ "groupName", "class", "name", "sipp", "rentalCompany", "pickUpLocation", "dropOffLocation", "pickUpDate", "dropOffDate", "rentals", "locators" ], "description": "The booked vehicle rental: the vehicle, the rental company, the pick-up and drop-off places and dates, fares, passengers (by ID) and reservation locators. This is the shape of `productSnapshot` when the trip's `vertical` is `VEHICLE`. Amounts are integers in cents.", "title": "Vehicle trip" } ], "description": "The booked product: the itinerary, stay, ticket or rental as recorded by the travel provider — journeys and flights, the hotel and its rooms, the route and boarding information, the rental — with its fares, policies and booking locators. It does not repeat the trip's own fields (`state`, `status`, the amounts, the dates) and carries no identifier of the travel provider; passengers are referenced by their `id` in `passengers[]`. Its shape depends on `vertical`: a flight (`AIR`), a hotel stay (`HOTEL`), a bus ticket (`BUS`) or a vehicle rental (`VEHICLE`) — see the four schemas below. Omitted until the record is first fetched." }, "cancellation": { "type": "object", "properties": { "quoteId": { "type": "string", "description": "ID of the confirmed cancellation quote." }, "cancelType": { "type": "string", "enum": [ "CREDIT", "REFUND", "MANUAL_CANCEL", "VOID" ], "description": "Kind of cancellation: `VOID` for a trip not issued yet, `REFUND` or `CREDIT` for an issued one, `MANUAL_CANCEL` when the amounts are settled outside the system." }, "originalAmount": { "type": "number", "nullable": true, "description": "What the trip cost, in cents. Omitted when it couldn't be recorded; `null` for `MANUAL_CANCEL`." }, "remainingAmount": { "type": "number", "nullable": true, "description": "What is given back after the fine, in cents. Omitted when it couldn't be recorded; `null` for `MANUAL_CANCEL`." }, "fineAmount": { "type": "number", "nullable": true, "description": "Cancellation fine, in cents. Omitted when it couldn't be recorded; `null` for `MANUAL_CANCEL`." }, "currency": { "type": "string", "description": "Currency of the amounts, as the numeric ISO 4217 code (`986` is BRL)." }, "status": { "type": "string", "description": "Status of the quote when it was confirmed." }, "expiresAt": { "type": "string", "description": "When the quote would have expired.", "format": "date-time" }, "confirmedAt": { "type": "string", "description": "When the cancellation was confirmed.", "format": "date-time" }, "confirmedBy": { "type": "string", "description": "ID of the user who confirmed the cancellation. Omitted when a service did." } }, "required": [ "quoteId", "cancelType" ], "description": "The confirmed cancellation. Omitted until one is confirmed." }, "createdAt": { "type": "string", "description": "When the trip was created.", "example": "2026-10-01T13:45:12.000Z", "format": "date-time" }, "updatedAt": { "type": "string", "description": "When the trip last changed.", "example": "2026-10-01T13:46:03.000Z", "format": "date-time" } }, "required": [ "id", "realmId", "organizationId", "customFields", "vertical", "state", "status", "passengers" ], "description": "A trip: ONE booked product — a flight, a hotel stay, a bus ticket or a vehicle rental — for the organization's passengers, with its lifecycle. Booking several products means creating several trips." }, "examples": { "air-trip": { "summary": "Air trip", "value": { "id": "6711b4c0d8e1a30012b7c9f2", "realmId": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b", "organizationId": "c4bd3f21-dfbd-44e8-8055-68ba15bed410", "createdBy": "e3553bc1-5e20-4e17-b22a-a796fda0aa99", "customFields": { "cost-center": "CC-1020" }, "vertical": "AIR", "state": "RESERVED", "status": "RESERVED", "reservationExpiresAt": "2026-10-02T13:45:12.000Z", "originalAmount": 95000, "discountAmount": 3010, "feeAmount": 0, "totalAmount": 91990, "currency": "986", "passengers": [ { "id": "6710a3f2c9e77b0012a4d5e1", "userId": "e3553bc1-5e20-4e17-b22a-a796fda0aa99", "lead": true, "name": "Mariana Costa", "gender": "FEMALE", "birthDate": "1990-04-17" } ], "productSnapshot": { "journeys": [ { "id": "jour_V1StGXR8Z5jdHi6BmyT2k", "direction": "DEPARTURE", "origin": { "iata": "GRU", "name": "São Paulo/Guarulhos International Airport", "shortAddress": "Guarulhos, SP, Brazil", "locality": "Guarulhos", "administrativeArea": "SP", "phoneNumbers": [ "551133334444" ] }, "destination": { "iata": "SDU", "name": "Rio de Janeiro/Santos Dumont Airport", "shortAddress": "Rio de Janeiro, RJ, Brazil", "locality": "Rio de Janeiro", "administrativeArea": "RJ", "phoneNumbers": [ "552133339999" ] }, "departureDate": "2026-11-02T08:30:00", "arrivalDate": "2026-11-02T09:35:00", "duration": "01:05", "segments": [ { "airline": { "code": "LA", "name": "LATAM Airlines", "logo": "https://cdn.example.com/airlines/LA.png" }, "operation": { "code": "LA", "name": "LATAM Airlines", "logo": "https://cdn.example.com/airlines/LA.png" }, "origin": { "iata": "GRU", "name": "São Paulo/Guarulhos International Airport", "shortAddress": "Guarulhos, SP, Brazil", "locality": "Guarulhos", "administrativeArea": "SP", "phoneNumbers": [ "551133334444" ] }, "destination": { "iata": "SDU", "name": "Rio de Janeiro/Santos Dumont Airport", "shortAddress": "Rio de Janeiro, RJ, Brazil", "locality": "Rio de Janeiro", "administrativeArea": "RJ", "phoneNumbers": [ "552133339999" ] }, "flightNumber": "3101", "departureDate": "2026-11-02T08:30:00", "arrivalDate": "2026-11-02T09:35:00", "flightType": "REGULAR", "duration": "01:05", "equipment": "32Q", "cabin": "ECONOMY", "class": "Y", "fareBasis": "YOW", "flightInfo": null } ] } ], "tickets": [ { "passengerId": "6710a3f2c9e77b0012a4d5e1", "fareDescription": "GRU to SDU, LATAM Airlines, Economy", "ticketNumber": null, "fares": [ { "journeyId": "jour_V1StGXR8Z5jdHi6BmyT2k", "currency": "BRL", "originalAmount": 95000, "discountAmount": 3010, "feeAmount": 0, "amount": 91990, "cancellationPolicies": { "refundable": true, "immediateFine": false, "penalties": [ { "from": "2026-10-25", "currency": "BRL", "fineAmount": 15000 } ] }, "changePolicies": { "canChange": true, "immediateFine": false, "penalties": [ { "from": "2026-10-25", "currency": "BRL", "fineAmount": 8000 } ] } } ], "segments": [ { "flightNumber": "3101", "cabin": "ECONOMY", "class": "Y", "fareBasis": "YOW", "baggages": [ { "quantity": 1, "weight": 23, "type": "CHECKED" } ] } ] } ], "locators": [ { "type": "PNR", "code": "ABC123" } ], "flightInfoUpdatedAt": null }, "createdAt": "2026-10-01T13:45:12.000Z", "updatedAt": "2026-10-01T13:46:03.000Z" } }, "hotel-trip": { "summary": "Hotel trip", "value": { "id": "6711b4c0d8e1a30012b7c9f2", "realmId": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b", "organizationId": "c4bd3f21-dfbd-44e8-8055-68ba15bed410", "createdBy": "e3553bc1-5e20-4e17-b22a-a796fda0aa99", "customFields": { "cost-center": "CC-1020" }, "vertical": "HOTEL", "state": "RESERVED", "status": "RESERVED", "reservationExpiresAt": "2026-10-02T13:45:12.000Z", "originalAmount": 95000, "discountAmount": 3010, "feeAmount": 0, "totalAmount": 91990, "currency": "986", "passengers": [ { "id": "6710a3f2c9e77b0012a4d5e1", "userId": "e3553bc1-5e20-4e17-b22a-a796fda0aa99", "lead": true, "name": "Mariana Costa", "gender": "FEMALE", "birthDate": "1990-04-17" } ], "productSnapshot": { "hotel": { "name": "Hotel Paulista Plaza", "chain": { "brandName": "Ibis", "chainName": "Accor", "logo": "https://cdn.example.com/hotels/ibis.svg" }, "shortAddress": "Av. Paulista, 1500, São Paulo, SP, Brazil", "phoneNumbers": [ "551133335555" ], "locality": "São Paulo", "administrativeArea": "SP", "checkInTime": "14:00", "checkOutTime": "12:00" }, "checkIn": "2026-11-02", "checkOut": "2026-11-04", "rooms": [ { "name": "Standard Room, 1 Queen Bed", "fare": { "currency": "BRL", "originalAmount": 120000, "discountAmount": 8000, "feeAmount": 0, "amount": 112000, "boardType": "BREAKFAST", "cancellationPolicies": { "refundable": true, "immediateFine": false, "penalties": [ { "from": "2026-10-25", "currency": "BRL", "fineAmount": 15000 } ] } }, "passengersId": [ "6710a3f2c9e77b0012a4d5e1" ] } ], "locators": [ { "type": "PNR", "code": "ABC123" } ] }, "createdAt": "2026-10-01T13:45:12.000Z", "updatedAt": "2026-10-01T13:46:03.000Z" } }, "bus-trip": { "summary": "Bus trip", "value": { "id": "6711b4c0d8e1a30012b7c9f2", "realmId": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b", "organizationId": "c4bd3f21-dfbd-44e8-8055-68ba15bed410", "createdBy": "e3553bc1-5e20-4e17-b22a-a796fda0aa99", "customFields": { "cost-center": "CC-1020" }, "vertical": "BUS", "state": "RESERVED", "status": "RESERVED", "reservationExpiresAt": "2026-10-02T13:45:12.000Z", "originalAmount": 95000, "discountAmount": 3010, "feeAmount": 0, "totalAmount": 91990, "currency": "986", "passengers": [ { "id": "6710a3f2c9e77b0012a4d5e1", "userId": "e3553bc1-5e20-4e17-b22a-a796fda0aa99", "lead": true, "name": "Mariana Costa", "gender": "FEMALE", "birthDate": "1990-04-17" } ], "productSnapshot": { "type": "DIRECT", "origin": { "locality": "São Paulo", "administrativeArea": "SP", "name": "Terminal Rodoviário Tietê", "shortAddress": "Av. Cruzeiro do Sul, 1800, São Paulo, SP, Brazil", "phoneNumbers": [ "551133336666" ] }, "destination": { "locality": "Rio de Janeiro", "administrativeArea": "RJ", "name": "Rodoviária Novo Rio", "shortAddress": "Av. Francisco Bicalho, 1, Rio de Janeiro, RJ, Brazil", "phoneNumbers": [ "552133338888" ] }, "departureDate": "2026-11-02T08:30:00", "arrivalDate": "2026-11-02T14:45:00", "company": { "name": "Expresso Brasileiro", "logo": "https://cdn.example.com/bus/expresso-brasileiro.png" }, "passengerId": "6710a3f2c9e77b0012a4d5e1", "segments": [ { "seatNumber": 12, "serviceClass": "EXECUTIVE", "origin": { "locality": "São Paulo", "administrativeArea": "SP", "name": "Terminal Rodoviário Tietê", "shortAddress": "Av. Cruzeiro do Sul, 1800, São Paulo, SP, Brazil", "phoneNumbers": [ "551133336666" ] }, "destination": { "locality": "Rio de Janeiro", "administrativeArea": "RJ", "name": "Rodoviária Novo Rio", "shortAddress": "Av. Francisco Bicalho, 1, Rio de Janeiro, RJ, Brazil", "phoneNumbers": [ "552133338888" ] }, "departureDate": "2026-11-02T08:30:00", "arrivalDate": "2026-11-02T14:45:00", "duration": "06:15", "fare": { "originalAmount": 18000, "discountAmount": 1000, "feeAmount": 500, "amount": 17500, "currency": "BRL", "cancellationPolicies": { "refundable": true, "immediateFine": false, "penalties": [ { "from": "2026-10-25", "currency": "BRL", "fineAmount": 15000 } ] } }, "company": { "name": "Expresso Brasileiro", "logo": "https://cdn.example.com/bus/expresso-brasileiro.png" } } ], "routeDirection": "DEPARTURE", "boardingInfo": null }, "createdAt": "2026-10-01T13:45:12.000Z", "updatedAt": "2026-10-01T13:46:03.000Z" } }, "vehicle-trip": { "summary": "Vehicle trip", "value": { "id": "6711b4c0d8e1a30012b7c9f2", "realmId": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b", "organizationId": "c4bd3f21-dfbd-44e8-8055-68ba15bed410", "createdBy": "e3553bc1-5e20-4e17-b22a-a796fda0aa99", "customFields": { "cost-center": "CC-1020" }, "vertical": "VEHICLE", "state": "RESERVED", "status": "RESERVED", "reservationExpiresAt": "2026-10-02T13:45:12.000Z", "originalAmount": 95000, "discountAmount": 3010, "feeAmount": 0, "totalAmount": 91990, "currency": "986", "passengers": [ { "id": "6710a3f2c9e77b0012a4d5e1", "userId": "e3553bc1-5e20-4e17-b22a-a796fda0aa99", "lead": true, "name": "Mariana Costa", "gender": "FEMALE", "birthDate": "1990-04-17" } ], "productSnapshot": { "groupName": "ECONOMY", "class": "INTERMEDIATE", "name": "Fiat Mobi", "sipp": "ECMR", "rentalCompany": { "code": "LOC", "name": "Localiza", "logo": "https://cdn.example.com/rentals/localiza.svg" }, "pickUpLocation": { "name": "Localiza Aeroporto Guarulhos (GRU)", "phoneNumbers": [ "551133337777" ], "shortAddress": "Rod. Hélio Smidt, s/n, Guarulhos, SP, Brazil", "locality": "Guarulhos", "administrativeArea": "SP" }, "dropOffLocation": { "name": "Localiza Aeroporto Guarulhos (GRU)", "phoneNumbers": [ "551133337777" ], "shortAddress": "Rod. Hélio Smidt, s/n, Guarulhos, SP, Brazil", "locality": "Guarulhos", "administrativeArea": "SP" }, "pickUpDate": "2026-11-02T10:00:00", "dropOffDate": "2026-11-04T10:00:00", "rentals": [ { "description": "Compact car, air conditioning, unlimited mileage", "fare": { "originalAmount": 36000, "discountAmount": 2000, "feeAmount": 0, "amount": 34000, "currency": "BRL", "cancellationPolicies": { "refundable": true, "immediateFine": false, "penalties": [ { "from": "2026-10-31", "currency": "BRL", "fineAmount": 12000 } ] } }, "passengersId": [ "6710a3f2c9e77b0012a4d5e1" ], "locators": [ { "type": "PNR", "code": "ABC123" } ] } ], "locators": [ { "type": "PNR", "code": "ABC123" } ] }, "createdAt": "2026-10-01T13:45:12.000Z", "updatedAt": "2026-10-01T13:46:03.000Z" } } } } } }, "404": { "description": "`PASSENGER_NOT_FOUND` — A passenger ID in the body is not an active passenger of the organization; `fields` lists each one.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "PASSENGER_NOT_FOUND" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "TRAVEL" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b", "code": "PASSENGER_NOT_FOUND", "origin": "TRAVEL", "message": "Passenger not found" } } } }, "422": { "description": "`INVALID_CUSTOM_FIELD` — A custom field value is invalid, unknown or a required one is missing.\n\n`BAD_REQUEST` — A path parameter is not a valid ID or the body failed validation — including a body with none, or more than one, of `air`, `hotel`, `bus` and `vehicle`; `fields` lists each offending field.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "INVALID_CUSTOM_FIELD", "BAD_REQUEST" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "TRAVEL" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." }, "fields": { "type": "array", "description": "One entry per invalid request field (validation errors only).", "items": { "type": "object", "properties": { "field": { "type": "string", "description": "Path of the invalid field, e.g. `label` or `values[0].value`.", "example": "label" }, "message": { "type": "string", "description": "Why the field was rejected.", "example": "label is required" }, "code": { "type": "string", "description": "`_` — e.g. `LABEL_REQUIRED`, `TYPE_ONE_OF`, `VALUES_VALUE_TYPE_ERROR`.", "example": "LABEL_REQUIRED" }, "values": { "type": "array", "items": { "type": "string" }, "description": "The accepted values, when the field is an enumeration." } }, "required": [ "field", "message", "code" ] } } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b", "code": "INVALID_CUSTOM_FIELD", "origin": "TRAVEL", "message": "A custom field value is invalid, unknown or a required one is missing." } } } }, "502": { "description": "`TRIP_PROVIDER_RESPONSE_INVALID` — The provider accepted the booking but its answer could not be recorded as a trip; contact support before sending the request again, or it may book twice.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "TRIP_PROVIDER_RESPONSE_INVALID" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "TRAVEL" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b", "code": "TRIP_PROVIDER_RESPONSE_INVALID", "origin": "TRAVEL", "message": "The travel provider accepted the booking but answered with an unexpected result — contact support before retrying" } } } }, "503": { "description": "`PROVIDER_UNAVAILABLE` — The travel provider could not be reached or answered with an error. Nothing was recorded on our side, but the outcome at the provider is unknown — a request that timed out may still have been booked. Check with support before sending the request again, or it may book twice.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "PROVIDER_UNAVAILABLE" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "TRAVEL" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b", "code": "PROVIDER_UNAVAILABLE", "origin": "TRAVEL", "message": "Travel provider temporarily unavailable, please retry." } } } } }, "x-p3-confidence": { "response": "generated:typed", "request": "generated:typed", "note": "`.superRefine(…)` constraint not represented (runtime-dependent value)" } } }, "/realms/{realmId}/organizations/{organizationId}/passengers/{passengerId}/trips": { "get": { "operationId": "getRealmsByRealmIdOrganizationsByOrganizationIdPassengersByPassengerIdTrips", "summary": "List passenger trips", "tags": [ "Trips" ], "x-p3-sidebar-order": 4, "description": "Lists the trips a passenger travels on, newest first.", "x-mint": { "content": "A trip is listed when the passenger travels on it. An organization admin can list any passenger's trips; a user can list their own — those of the passenger linked to them. A passenger who is not a user can only be listed by an admin. Filter by creation date, requester and the type, state or status of the trip. Paginated — see [Pagination](/api-reference/pagination)." }, "parameters": [ { "name": "realmId", "in": "path", "required": true, "description": "ID of your realm.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b" }, { "name": "organizationId", "in": "path", "required": true, "description": "ID of the organization the passenger belongs to.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410" }, { "name": "passengerId", "in": "path", "required": true, "description": "ID of the passenger whose trips you want to list (24 hexadecimal characters).", "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$" }, "example": "6710a3f2c9e77b0012a4d5e1" }, { "name": "from", "in": "query", "required": false, "description": "Only trips created on or after this day (`YYYY-MM-DD`, UTC).", "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "example": "2026-10-01" }, { "name": "to", "in": "query", "required": false, "description": "Only trips created on or before this day (`YYYY-MM-DD`, UTC), the whole day included.", "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "example": "2026-10-31" }, { "name": "vertical", "in": "query", "required": false, "description": "Only trips of this type.", "schema": { "type": "string", "enum": [ "AIR", "HOTEL", "BUS", "VEHICLE" ] }, "example": "AIR" }, { "name": "state", "in": "query", "required": false, "description": "Only trips in this state.", "schema": { "type": "string", "enum": [ "PENDING", "RESERVED", "ISSUED", "CANCELED" ] }, "example": "RESERVED" }, { "name": "status", "in": "query", "required": false, "description": "Only trips in this status.", "schema": { "type": "string", "enum": [ "PROCESSING_RESERVATION", "RESERVATION_FAILED", "RESERVED", "PROCESSING_ISSUE", "ISSUED", "PROCESSING_CANCELLATION", "CANCELED", "AWAITING_MANUAL_CANCELLATION", "CANCELLATION_FAILED", "FAILED", "FAILED_BY_INCONSISTENT_DATA", "FAILED_BY_UNAVAILABLE_RESOURCE", "FAILED_BY_BUDGET_EXCEEDED", "EXPIRED", "BLOCKED", "UNKNOWN", "ISSUANCE_FAILED" ] }, "example": "PROCESSING_RESERVATION" }, { "name": "createdBy", "in": "query", "required": false, "description": "Only trips created by this user (`createdBy`).", "schema": { "type": "string", "maxLength": 100 }, "example": "e3553bc1-5e20-4e17-b22a-a796fda0aa99" }, { "name": "next", "in": "query", "required": false, "description": "Cursor returned as `next` by the previous page. Omit for the first page.", "schema": { "type": "string" }, "example": "eyJjIjoiMjAyNi0xMC0wMVQxMzo0NToxMi4wMDBaIiwiaSI6IjY3MTFiNGMwZDhlMWEzMDAxMmI3YzlmMiJ9" }, { "name": "limit", "in": "query", "required": false, "description": "Page size.", "schema": { "default": 15, "type": "integer", "minimum": 1, "maximum": 100 }, "example": 15 } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the trip.", "example": "6711b4c0d8e1a30012b7c9f2" }, "realmId": { "type": "string", "description": "ID of the realm the trip belongs to.", "example": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b", "format": "uuid" }, "organizationId": { "type": "string", "description": "ID of the organization the trip belongs to.", "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410", "format": "uuid" }, "createdBy": { "type": "string", "description": "ID of the user who created the trip. Omitted when a service did.", "example": "e3553bc1-5e20-4e17-b22a-a796fda0aa99", "format": "uuid" }, "customFields": { "type": "object", "additionalProperties": {}, "description": "Values of the organization's trip custom fields, keyed by the custom field's `slug`. Empty when none were set.\n\n---\n\nExample: `{\"cost-center\":\"CC-1020\"}`", "example": { "cost-center": "CC-1020" } }, "vertical": { "type": "string", "enum": [ "AIR", "HOTEL", "BUS", "VEHICLE" ], "description": "Type of product booked. It tells which shape `productSnapshot` has.", "example": "AIR" }, "state": { "type": "string", "enum": [ "PENDING", "RESERVED", "ISSUED", "CANCELED" ], "description": "Where the booking is in its life: `PENDING` while the reservation is being made, `RESERVED` once held (until `reservationExpiresAt`), `ISSUED` once ticketed and `CANCELED`. It only moves forward.", "example": "RESERVED" }, "status": { "type": "string", "enum": [ "PROCESSING_RESERVATION", "RESERVATION_FAILED", "RESERVED", "PROCESSING_ISSUE", "ISSUED", "PROCESSING_CANCELLATION", "CANCELED", "AWAITING_MANUAL_CANCELLATION", "CANCELLATION_FAILED", "FAILED", "FAILED_BY_INCONSISTENT_DATA", "FAILED_BY_UNAVAILABLE_RESOURCE", "FAILED_BY_BUDGET_EXCEEDED", "EXPIRED", "BLOCKED", "UNKNOWN", "ISSUANCE_FAILED" ], "description": "Finer-grained status: it also reports work in progress (`PROCESSING_*`) and failures, and can change back and forth. Use `state` to decide what the booking is; use `status` to tell what is happening to it.", "example": "RESERVED" }, "reservationExpiresAt": { "type": "string", "nullable": true, "description": "Until when the reservation is held. Past it, a trip that was not issued expires. `null` or omitted when there is no hold.", "example": "2026-10-02T13:45:12.000Z", "format": "date-time" }, "issuedAt": { "type": "string", "nullable": true, "description": "When the trip was issued. `null` or omitted until it is.", "format": "date-time" }, "originalAmount": { "type": "number", "description": "Price before discounts, in cents. Omitted until the price is known.", "example": 95000 }, "discountAmount": { "type": "number", "description": "Discount applied, in cents. Omitted until the price is known.", "example": 3010 }, "feeAmount": { "type": "number", "description": "Fees added, in cents. Omitted until the price is known.", "example": 0 }, "totalAmount": { "type": "number", "description": "Amount to pay, in cents: `originalAmount` - `discountAmount` + `feeAmount`. Omitted until the price is known.", "example": 91990 }, "currency": { "type": "string", "description": "Currency of the amounts, as the numeric ISO 4217 code (`986` is BRL).", "example": "986" }, "passengers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the passenger, as returned by the passenger endpoints.", "example": "6710a3f2c9e77b0012a4d5e1" }, "userId": { "type": "string", "description": "ID of the organization user the passenger is linked to. Omitted for a passenger who is not a user. A user sees the trips they travel on.", "example": "e3553bc1-5e20-4e17-b22a-a796fda0aa99", "format": "uuid" }, "lead": { "type": "boolean", "description": "Whether this passenger is the one responsible for the reservation.", "example": true }, "name": { "type": "string", "description": "Full name, as it appears on the passenger's travel documents.", "example": "Mariana Costa" }, "gender": { "type": "string", "enum": [ "MALE", "FEMALE" ], "description": "Gender.", "example": "FEMALE" }, "birthDate": { "type": "string", "description": "Date of birth (`YYYY-MM-DD`).", "example": "1990-04-17" } }, "required": [ "id", "lead", "name", "gender", "birthDate" ], "description": "A passenger of a trip: who travels, as recorded when the trip was booked. The passenger endpoints serve the full profile." }, "description": "The passengers booked on the trip." }, "productSnapshot": { "anyOf": [ { "type": "object", "properties": { "journeys": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the journey, referenced by `tickets[].fares[].journeyId`.", "example": "jour_V1StGXR8Z5jdHi6BmyT2k" }, "direction": { "type": "string", "enum": [ "DEPARTURE", "RETURN" ], "description": "Whether this is the outbound leg (`DEPARTURE`) or the return leg (`RETURN`).", "example": "DEPARTURE" }, "origin": { "type": "object", "properties": { "iata": { "type": "string", "description": "IATA code of the airport, 3 letters.", "example": "GRU" }, "name": { "type": "string", "nullable": true, "description": "Official name of the airport. `null` when unknown.", "example": "São Paulo/Guarulhos International Airport" }, "shortAddress": { "type": "string", "nullable": true, "description": "Readable single-line address of the airport. `null` when unknown.", "example": "Guarulhos, SP, Brazil" }, "locality": { "type": "string", "nullable": true, "description": "City the airport sits in. `null` when unknown.", "example": "Guarulhos" }, "administrativeArea": { "type": "string", "nullable": true, "description": "State, as its short code. `null` when unknown.", "example": "SP" }, "phoneNumbers": { "type": "array", "items": { "type": "string", "example": "551133334444" }, "description": "Contact phone numbers of the airport, digits only. Empty when none is registered.\n\n---\n\nExample: `[\"551133334444\"]`" } }, "required": [ "iata", "name", "shortAddress", "locality", "administrativeArea", "phoneNumbers" ], "description": "Airport the journey starts at." }, "destination": { "type": "object", "properties": { "iata": { "type": "string", "description": "IATA code of the airport, 3 letters.", "example": "GRU" }, "name": { "type": "string", "nullable": true, "description": "Official name of the airport. `null` when unknown.", "example": "São Paulo/Guarulhos International Airport" }, "shortAddress": { "type": "string", "nullable": true, "description": "Readable single-line address of the airport. `null` when unknown.", "example": "Guarulhos, SP, Brazil" }, "locality": { "type": "string", "nullable": true, "description": "City the airport sits in. `null` when unknown.", "example": "Guarulhos" }, "administrativeArea": { "type": "string", "nullable": true, "description": "State, as its short code. `null` when unknown.", "example": "SP" }, "phoneNumbers": { "type": "array", "items": { "type": "string", "example": "551133334444" }, "description": "Contact phone numbers of the airport, digits only. Empty when none is registered.\n\n---\n\nExample: `[\"551133334444\"]`" } }, "required": [ "iata", "name", "shortAddress", "locality", "administrativeArea", "phoneNumbers" ], "description": "Airport the journey ends at.", "example": { "iata": "SDU", "name": "Rio de Janeiro/Santos Dumont Airport", "shortAddress": "Rio de Janeiro, RJ, Brazil", "locality": "Rio de Janeiro", "administrativeArea": "RJ", "phoneNumbers": [ "552133339999" ] } }, "departureDate": { "type": "string", "description": "Departure date and time in the local time of the origin airport, as `YYYY-MM-DDTHH:mm:ss` with no time zone.", "example": "2026-11-02T08:30:00" }, "arrivalDate": { "type": "string", "description": "Arrival date and time in the local time of the destination airport, as `YYYY-MM-DDTHH:mm:ss` with no time zone.", "example": "2026-11-02T09:35:00" }, "duration": { "type": "string", "description": "Total travel time of the journey, connections included, as `HH:mm`.", "example": "01:05" }, "segments": { "type": "array", "items": { "type": "object", "properties": { "airline": { "type": "object", "properties": { "code": { "type": "string", "description": "IATA code of the airline.", "example": "LA" }, "name": { "type": "string", "nullable": true, "description": "Commercial name of the airline. `null` when unknown.", "example": "LATAM Airlines" }, "logo": { "type": "string", "nullable": true, "description": "URL of the airline's logo. `null` when there is none.", "example": "https://cdn.example.com/airlines/LA.png" } }, "required": [ "code", "name", "logo" ], "description": "Airline that sells the flight." }, "operation": { "type": "object", "properties": { "code": { "type": "string", "description": "IATA code of the airline.", "example": "LA" }, "name": { "type": "string", "nullable": true, "description": "Commercial name of the airline. `null` when unknown.", "example": "LATAM Airlines" }, "logo": { "type": "string", "nullable": true, "description": "URL of the airline's logo. `null` when there is none.", "example": "https://cdn.example.com/airlines/LA.png" } }, "required": [ "code", "name", "logo" ], "description": "Airline that operates the flight. It differs from `airline` on codeshare flights." }, "origin": { "type": "object", "properties": { "iata": { "type": "string", "description": "IATA code of the airport, 3 letters.", "example": "GRU" }, "name": { "type": "string", "nullable": true, "description": "Official name of the airport. `null` when unknown.", "example": "São Paulo/Guarulhos International Airport" }, "shortAddress": { "type": "string", "nullable": true, "description": "Readable single-line address of the airport. `null` when unknown.", "example": "Guarulhos, SP, Brazil" }, "locality": { "type": "string", "nullable": true, "description": "City the airport sits in. `null` when unknown.", "example": "Guarulhos" }, "administrativeArea": { "type": "string", "nullable": true, "description": "State, as its short code. `null` when unknown.", "example": "SP" }, "phoneNumbers": { "type": "array", "items": { "type": "string", "example": "551133334444" }, "description": "Contact phone numbers of the airport, digits only. Empty when none is registered.\n\n---\n\nExample: `[\"551133334444\"]`" } }, "required": [ "iata", "name", "shortAddress", "locality", "administrativeArea", "phoneNumbers" ], "description": "Airport the flight leaves from." }, "destination": { "type": "object", "properties": { "iata": { "type": "string", "description": "IATA code of the airport, 3 letters.", "example": "GRU" }, "name": { "type": "string", "nullable": true, "description": "Official name of the airport. `null` when unknown.", "example": "São Paulo/Guarulhos International Airport" }, "shortAddress": { "type": "string", "nullable": true, "description": "Readable single-line address of the airport. `null` when unknown.", "example": "Guarulhos, SP, Brazil" }, "locality": { "type": "string", "nullable": true, "description": "City the airport sits in. `null` when unknown.", "example": "Guarulhos" }, "administrativeArea": { "type": "string", "nullable": true, "description": "State, as its short code. `null` when unknown.", "example": "SP" }, "phoneNumbers": { "type": "array", "items": { "type": "string", "example": "551133334444" }, "description": "Contact phone numbers of the airport, digits only. Empty when none is registered.\n\n---\n\nExample: `[\"551133334444\"]`" } }, "required": [ "iata", "name", "shortAddress", "locality", "administrativeArea", "phoneNumbers" ], "description": "Airport the flight arrives at.", "example": { "iata": "SDU", "name": "Rio de Janeiro/Santos Dumont Airport", "shortAddress": "Rio de Janeiro, RJ, Brazil", "locality": "Rio de Janeiro", "administrativeArea": "RJ", "phoneNumbers": [ "552133339999" ] } }, "flightNumber": { "type": "string", "description": "Number of the flight, without the airline's code.", "example": "3101" }, "departureDate": { "type": "string", "description": "Departure date and time in the local time of the departure airport, as `YYYY-MM-DDTHH:mm:ss` with no time zone.", "example": "2026-11-02T08:30:00" }, "arrivalDate": { "type": "string", "description": "Arrival date and time in the local time of the arrival airport, as `YYYY-MM-DDTHH:mm:ss` with no time zone.", "example": "2026-11-02T09:35:00" }, "flightType": { "type": "string", "enum": [ "CHARTER", "ALLOTMENT", "REGULAR" ], "description": "Kind of flight: `REGULAR`, `CHARTER` or `ALLOTMENT`.", "example": "REGULAR" }, "duration": { "type": "string", "description": "Duration of the flight, as `HH:mm`.", "example": "01:05" }, "equipment": { "type": "string", "nullable": true, "description": "Aircraft scheduled for the flight, as the airline identifies it. `null` when not informed.", "example": "32Q" }, "cabin": { "type": "string", "enum": [ "ECONOMY", "PREMIUM_ECONOMY", "BUSINESS", "FIRST_CLASS", "UNDEFINED" ], "description": "Cabin booked for the flight.", "example": "ECONOMY" }, "class": { "type": "string", "nullable": true, "description": "Booking class (RBD) priced for the flight. Each airline defines its own codes. `null` when the airline does not expose it.", "example": "Y" }, "fareBasis": { "type": "string", "nullable": true, "description": "Fare basis code priced for the flight. Each airline defines its own codes. `null` when the airline does not expose it.", "example": "YOW" }, "flightInfo": { "description": "Live information about the flight. `null` until it is first collected, as the departure approaches.", "example": null, "type": "object", "properties": { "state": { "type": "string", "nullable": true, "enum": [ "SCHEDULED", "OUT_GATE", "IN_AIR", "LANDED", "IN_GATE", "CANCELED", "PROPOSED", "UNKNOWN", null ], "description": "Operational state of the flight. `null` when there is no live status yet.", "example": "SCHEDULED" }, "updatedAt": { "type": "string", "nullable": true, "description": "When the live status was captured. `null` when there is no live status yet.", "example": "2026-11-01T18:00:00.000Z" }, "aircraft": { "description": "Aircraft operating the flight. `null` when not known yet.", "type": "object", "properties": { "registration": { "type": "string", "nullable": true, "description": "Tail registration of the aircraft. `null` when not known yet.", "example": "PR-XBA" }, "type": { "type": "string", "nullable": true, "description": "ICAO code of the aircraft type. `null` when not known yet.", "example": "A21N" } }, "required": [ "registration", "type" ], "nullable": true }, "departure": { "type": "object", "properties": { "terminal": { "type": "string", "nullable": true, "description": "Terminal at the airport. `null` when not reported yet.", "example": "2" }, "gate": { "type": "string", "nullable": true, "description": "Gate at the airport. `null` when not reported yet.", "example": "B12" }, "baggage": { "type": "string", "nullable": true, "description": "Baggage belt, reported for arrivals only. `null` for departures and when not reported yet.", "example": "04" }, "estimatedTime": { "type": "string", "nullable": true, "description": "Estimated time at the gate, in UTC (ISO 8601). `null` when not known yet.", "example": "2026-11-02T11:30:00.000Z" }, "actualTime": { "type": "string", "nullable": true, "description": "Actual time at the gate, in UTC (ISO 8601), reported once the flight operates. `null` before that.", "example": "2026-11-02T11:34:00.000Z" }, "timeliness": { "type": "string", "nullable": true, "description": "Punctuality of the flight, such as `OnTime`, `Early` or `Delayed`. `null` when not known.", "example": "OnTime" }, "delayMinutes": { "type": "number", "nullable": true, "description": "Delay in minutes; negative when the flight is ahead of schedule. `null` when not known.", "example": 4 } }, "required": [ "terminal", "gate", "baggage", "estimatedTime", "actualTime", "timeliness", "delayMinutes" ], "description": "Live status at the departure airport." }, "arrival": { "type": "object", "properties": { "terminal": { "type": "string", "nullable": true, "description": "Terminal at the airport. `null` when not reported yet.", "example": "2" }, "gate": { "type": "string", "nullable": true, "description": "Gate at the airport. `null` when not reported yet.", "example": "B12" }, "baggage": { "type": "string", "nullable": true, "description": "Baggage belt, reported for arrivals only. `null` for departures and when not reported yet.", "example": "04" }, "estimatedTime": { "type": "string", "nullable": true, "description": "Estimated time at the gate, in UTC (ISO 8601). `null` when not known yet.", "example": "2026-11-02T11:30:00.000Z" }, "actualTime": { "type": "string", "nullable": true, "description": "Actual time at the gate, in UTC (ISO 8601), reported once the flight operates. `null` before that.", "example": "2026-11-02T11:34:00.000Z" }, "timeliness": { "type": "string", "nullable": true, "description": "Punctuality of the flight, such as `OnTime`, `Early` or `Delayed`. `null` when not known.", "example": "OnTime" }, "delayMinutes": { "type": "number", "nullable": true, "description": "Delay in minutes; negative when the flight is ahead of schedule. `null` when not known.", "example": 4 } }, "required": [ "terminal", "gate", "baggage", "estimatedTime", "actualTime", "timeliness", "delayMinutes" ], "description": "Live status at the arrival airport." } }, "required": [ "state", "updatedAt", "aircraft", "departure", "arrival" ], "nullable": true } }, "required": [ "airline", "operation", "origin", "destination", "flightNumber", "departureDate", "arrivalDate", "flightType", "duration", "equipment", "cabin", "class", "fareBasis", "flightInfo" ], "description": "One flight of a journey. A journey with connections has several." }, "description": "Flights of the journey, in chronological order, connections included." } }, "required": [ "id", "direction", "origin", "destination", "departureDate", "arrivalDate", "duration", "segments" ], "description": "One leg of the itinerary: the whole way from an origin to a destination, connections included." }, "description": "Legs of the itinerary, in travel order: one for a one-way trip, two (outbound and return) for a round trip." }, "tickets": { "type": "array", "items": { "type": "object", "properties": { "passengerId": { "type": "string", "description": "ID of the passenger holding this ticket — one of the trip's `passengers[]`. Omitted only if the passenger could not be matched to the trip's passengers.", "example": "6710a3f2c9e77b0012a4d5e1" }, "fareDescription": { "type": "string", "description": "Readable description of the fare of the ticket.", "example": "GRU to SDU, LATAM Airlines, Economy" }, "ticketNumber": { "type": "string", "nullable": true, "description": "Number of the ticket, as the airline issued it. `null` until the ticket is issued.", "example": null }, "fares": { "type": "array", "items": { "type": "object", "properties": { "journeyId": { "type": "string", "nullable": true, "description": "ID of the journey this fare covers — a `journeys[].id`. `null` when the fare covers the whole itinerary.", "example": "jour_V1StGXR8Z5jdHi6BmyT2k" }, "currency": { "type": "string", "description": "Currency, as the ISO 4217 alphabetic code.", "example": "BRL" }, "originalAmount": { "type": "number", "description": "Fare before discounts and fees, in cents.", "example": 95000 }, "discountAmount": { "type": "number", "description": "Discount applied to the fare, in cents.", "example": 3010 }, "feeAmount": { "type": "number", "description": "Fees added to the fare, in cents.", "example": 0 }, "amount": { "type": "number", "description": "Total charged for the fare, in cents: `originalAmount` - `discountAmount` + `feeAmount`.", "example": 91990 }, "cancellationPolicies": { "type": "object", "properties": { "refundable": { "type": "boolean", "description": "Whether cancelling gives any money back.", "example": true }, "immediateFine": { "type": "boolean", "description": "Whether a fine applies to a cancellation made right after the booking.", "example": false }, "penalties": { "type": "array", "items": { "type": "object", "properties": { "from": { "type": "string", "description": "First day (`YYYY-MM-DD`) on which this tier applies.", "example": "2026-10-25" }, "currency": { "type": "string", "description": "Currency, as the ISO 4217 alphabetic code.", "example": "BRL" }, "fineAmount": { "type": "number", "nullable": true, "description": "Fine charged for cancelling from `from` onward, in cents. `null` when the amount is not available.", "example": 15000 } }, "required": [ "from", "currency", "fineAmount" ], "description": "One tier of a cancellation penalty schedule." }, "description": "Penalty tiers, each in effect from its own date. Empty when no scheduled penalty applies." } }, "required": [ "refundable", "immediateFine", "penalties" ], "description": "Cancellation rules of the fare." }, "changePolicies": { "type": "object", "properties": { "canChange": { "type": "boolean", "description": "Whether the fare allows the booking to be changed.", "example": true }, "immediateFine": { "type": "boolean", "description": "Whether a fine applies to a change made right after the booking.", "example": false }, "penalties": { "type": "array", "items": { "type": "object", "properties": { "from": { "type": "string", "description": "First day (`YYYY-MM-DD`) on which this tier applies.", "example": "2026-10-25" }, "currency": { "type": "string", "description": "Currency, as the ISO 4217 alphabetic code.", "example": "BRL" }, "fineAmount": { "type": "number", "nullable": true, "description": "Fine charged for changing the booking from `from` onward, in cents. `null` when the amount is not available.", "example": 8000 } }, "required": [ "from", "currency", "fineAmount" ], "description": "One tier of a change penalty schedule." }, "description": "Penalty tiers, each in effect from its own date. Empty when no scheduled penalty applies." } }, "required": [ "canChange", "immediateFine", "penalties" ], "description": "Change rules of the fare." } }, "required": [ "journeyId", "currency", "originalAmount", "discountAmount", "feeAmount", "amount", "cancellationPolicies", "changePolicies" ], "description": "The fare of a ticket for one journey, or for the whole itinerary. Amounts are integers in cents." }, "description": "Fares of the ticket: one per journey, or a single one for the whole itinerary." }, "segments": { "type": "array", "items": { "type": "object", "properties": { "flightNumber": { "type": "string", "description": "Number of the flight this ticket covers, without the airline's code. It matches the `flightNumber` of one of the journeys' `segments`.", "example": "3101" }, "cabin": { "type": "string", "enum": [ "ECONOMY", "PREMIUM_ECONOMY", "BUSINESS", "FIRST_CLASS", "UNDEFINED" ], "description": "Cabin of the ticket on this flight.", "example": "ECONOMY" }, "class": { "type": "string", "nullable": true, "description": "Booking class (RBD) of the ticket on this flight. Each airline defines its own codes. `null` when the airline does not expose it.", "example": "Y" }, "fareBasis": { "type": "string", "nullable": true, "description": "Fare basis code of the ticket on this flight. Each airline defines its own codes. `null` when the airline does not expose it.", "example": "YOW" }, "baggages": { "type": "array", "items": { "type": "object", "properties": { "quantity": { "type": "number", "description": "Number of pieces included in the allowance.", "example": 1 }, "weight": { "type": "number", "nullable": true, "description": "Weight allowed per piece, in kg. `null` when the airline sets no weight limit per piece.", "example": 23 }, "type": { "type": "string", "enum": [ "CHECKED", "CARRY_ON", "PERSONAL_ITEM" ], "description": "Kind of baggage: `CHECKED`, `CARRY_ON` or `PERSONAL_ITEM`.", "example": "CHECKED" } }, "required": [ "quantity", "weight", "type" ], "description": "A baggage allowance of a ticket on one flight." }, "description": "Baggage allowance of the ticket on this flight. Empty for an infant on an adult's lap." } }, "required": [ "flightNumber", "cabin", "class", "fareBasis", "baggages" ], "description": "What a ticket covers on one flight of the itinerary: the cabin, the fare codes and the baggage allowance." }, "description": "What the ticket covers on each flight of the itinerary." } }, "required": [ "fareDescription", "ticketNumber", "fares", "segments" ], "description": "The ticket of one passenger. It covers the whole itinerary, with a fare per journey or a single fare for all of it." }, "description": "Tickets of the booking, one per passenger, each covering the whole itinerary." }, "locators": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "Kind of reference, such as `PNR` for an airline's booking code.", "example": "PNR" }, "code": { "type": "string", "description": "The reference itself, as the supplier issued it.", "example": "ABC123" } }, "required": [ "type", "code" ], "description": "A reference that identifies the booking with the supplier, such as an airline's booking code." }, "description": "Booking references issued by the airlines. Empty until the reservation is confirmed." }, "flightInfoUpdatedAt": { "type": "string", "nullable": true, "description": "When the live flight information was last collected. `null` until it is first collected.", "example": null, "format": "date-time" } }, "required": [ "journeys", "tickets", "locators", "flightInfoUpdatedAt" ], "description": "The booked flight: itinerary, the ticket of each passenger (by ID) with its fares and baggage, and reservation locators. This is the shape of `productSnapshot` when the trip's `vertical` is `AIR`. Amounts are integers in cents.", "title": "Air trip" }, { "type": "object", "properties": { "hotel": { "type": "object", "properties": { "name": { "type": "string", "description": "Official name of the hotel.", "example": "Hotel Paulista Plaza" }, "chain": { "type": "object", "properties": { "brandName": { "type": "string", "nullable": true, "description": "Brand within the chain. `null` when not informed.", "example": "Ibis" }, "chainName": { "type": "string", "nullable": true, "description": "Name of the chain. `null` for an independent hotel.", "example": "Accor" }, "logo": { "type": "string", "nullable": true, "description": "URL of the chain's logo. `null` when the hotel has no chain with a registered logo.", "example": "https://cdn.example.com/hotels/ibis.svg" } }, "required": [ "brandName", "chainName", "logo" ], "description": "Chain and brand of the hotel." }, "shortAddress": { "type": "string", "nullable": true, "description": "Readable single-line address of the hotel. `null` when unknown.", "example": "Av. Paulista, 1500, São Paulo, SP, Brazil" }, "phoneNumbers": { "type": "array", "items": { "type": "string", "example": "551133335555" }, "description": "Contact phone numbers of the hotel, digits only. Empty when none is registered.\n\n---\n\nExample: `[\"551133335555\"]`" }, "locality": { "type": "string", "nullable": true, "description": "City the hotel sits in. `null` when unknown.", "example": "São Paulo" }, "administrativeArea": { "type": "string", "nullable": true, "description": "State, as its short code. `null` when unknown.", "example": "SP" }, "checkInTime": { "type": "string", "nullable": true, "description": "Time of day, in the hotel's local time (`HH:mm`), from which guests can check in. `null` when unknown.", "example": "14:00" }, "checkOutTime": { "type": "string", "nullable": true, "description": "Time of day, in the hotel's local time (`HH:mm`), by which guests must check out. `null` when unknown.", "example": "12:00" } }, "required": [ "name", "chain", "shortAddress", "phoneNumbers", "locality", "administrativeArea", "checkInTime", "checkOutTime" ], "description": "Hotel where the stay is booked." }, "checkIn": { "type": "string", "description": "Check-in date (`YYYY-MM-DD`).", "example": "2026-11-02" }, "checkOut": { "type": "string", "description": "Check-out date (`YYYY-MM-DD`).", "example": "2026-11-04" }, "rooms": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the room, as the hotel offers it.", "example": "Standard Room, 1 Queen Bed" }, "fare": { "type": "object", "properties": { "currency": { "type": "string", "description": "Currency, as the ISO 4217 alphabetic code.", "example": "BRL" }, "originalAmount": { "type": "number", "description": "Fare before discounts and fees, in cents.", "example": 120000 }, "discountAmount": { "type": "number", "description": "Discount applied to the fare, in cents.", "example": 8000 }, "feeAmount": { "type": "number", "description": "Fees added to the fare, in cents.", "example": 0 }, "amount": { "type": "number", "description": "Total charged for the fare, in cents: `originalAmount` - `discountAmount` + `feeAmount`.", "example": 112000 }, "boardType": { "type": "string", "enum": [ "ONLY_ROOM", "BREAKFAST", "HALF_BOARD", "FULL_BOARD", "ALL_INCLUSIVE" ], "description": "Meals included in the fare.", "example": "BREAKFAST" }, "cancellationPolicies": { "type": "object", "properties": { "refundable": { "type": "boolean", "description": "Whether cancelling gives any money back.", "example": true }, "immediateFine": { "type": "boolean", "description": "Whether a fine applies to a cancellation made right after the booking.", "example": false }, "penalties": { "type": "array", "items": { "type": "object", "properties": { "from": { "type": "string", "description": "First day (`YYYY-MM-DD`) on which this tier applies.", "example": "2026-10-25" }, "currency": { "type": "string", "description": "Currency, as the ISO 4217 alphabetic code.", "example": "BRL" }, "fineAmount": { "type": "number", "nullable": true, "description": "Fine charged for cancelling from `from` onward, in cents. `null` when the amount is not available.", "example": 15000 } }, "required": [ "from", "currency", "fineAmount" ], "description": "One tier of a cancellation penalty schedule." }, "description": "Penalty tiers, each in effect from its own date. Empty when no scheduled penalty applies." } }, "required": [ "refundable", "immediateFine", "penalties" ], "description": "Cancellation rules of the fare." } }, "required": [ "currency", "originalAmount", "discountAmount", "feeAmount", "amount", "boardType", "cancellationPolicies" ], "description": "Fare of the room." }, "passengersId": { "type": "array", "items": { "type": "string", "example": "6710a3f2c9e77b0012a4d5e1" }, "description": "IDs of the passengers staying in this room — the trip's `passengers[]`.\n\n---\n\nExample: `[\"6710a3f2c9e77b0012a4d5e1\"]`" } }, "required": [ "name", "fare", "passengersId" ], "description": "A booked room." }, "description": "Rooms booked for the stay." }, "locators": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "Kind of reference, such as `PNR` for an airline's booking code.", "example": "PNR" }, "code": { "type": "string", "description": "The reference itself, as the supplier issued it.", "example": "ABC123" } }, "required": [ "type", "code" ], "description": "A reference that identifies the booking with the supplier, such as an airline's booking code." }, "description": "Booking references issued by the hotel. Empty until the reservation is confirmed." } }, "required": [ "hotel", "checkIn", "checkOut", "rooms", "locators" ], "description": "The booked hotel stay: the hotel, the dates, the rooms with their fares and guests (by ID), and the reservation locators. This is the shape of `productSnapshot` when the trip's `vertical` is `HOTEL`. Amounts are integers in cents.", "title": "Hotel trip" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "DIRECT", "CONNECTION", "ONE_STOP" ], "description": "Kind of trip: `DIRECT`, `CONNECTION` or `ONE_STOP`.", "example": "DIRECT" }, "origin": { "type": "object", "properties": { "locality": { "type": "string", "description": "City the station sits in.", "example": "São Paulo" }, "administrativeArea": { "type": "string", "description": "State, as its short code.", "example": "SP" }, "name": { "type": "string", "nullable": true, "description": "Official name of the station. `null` when unknown.", "example": "Terminal Rodoviário Tietê" }, "shortAddress": { "type": "string", "nullable": true, "description": "Readable single-line address of the station. `null` when unknown.", "example": "Av. Cruzeiro do Sul, 1800, São Paulo, SP, Brazil" }, "phoneNumbers": { "type": "array", "items": { "type": "string", "example": "551133336666" }, "description": "Contact phone numbers of the station, digits only. Empty when none is registered.\n\n---\n\nExample: `[\"551133336666\"]`" } }, "required": [ "locality", "administrativeArea", "name", "shortAddress", "phoneNumbers" ], "description": "Station the trip starts at." }, "destination": { "type": "object", "properties": { "locality": { "type": "string", "description": "City the station sits in.", "example": "São Paulo" }, "administrativeArea": { "type": "string", "description": "State, as its short code.", "example": "SP" }, "name": { "type": "string", "nullable": true, "description": "Official name of the station. `null` when unknown.", "example": "Terminal Rodoviário Tietê" }, "shortAddress": { "type": "string", "nullable": true, "description": "Readable single-line address of the station. `null` when unknown.", "example": "Av. Cruzeiro do Sul, 1800, São Paulo, SP, Brazil" }, "phoneNumbers": { "type": "array", "items": { "type": "string", "example": "551133336666" }, "description": "Contact phone numbers of the station, digits only. Empty when none is registered.\n\n---\n\nExample: `[\"551133336666\"]`" } }, "required": [ "locality", "administrativeArea", "name", "shortAddress", "phoneNumbers" ], "description": "Station the trip ends at.", "example": { "locality": "Rio de Janeiro", "administrativeArea": "RJ", "name": "Rodoviária Novo Rio", "shortAddress": "Av. Francisco Bicalho, 1, Rio de Janeiro, RJ, Brazil", "phoneNumbers": [ "552133338888" ] } }, "departureDate": { "type": "string", "description": "Departure date and time in the local time of the origin station, as `YYYY-MM-DDTHH:mm:ss` with no time zone.", "example": "2026-11-02T08:30:00" }, "arrivalDate": { "type": "string", "description": "Arrival date and time in the local time of the destination station, as `YYYY-MM-DDTHH:mm:ss` with no time zone.", "example": "2026-11-02T14:45:00" }, "company": { "type": "object", "properties": { "name": { "type": "string", "description": "Commercial name of the company.", "example": "Expresso Brasileiro" }, "logo": { "type": "string", "nullable": true, "description": "URL of the company's logo. `null` when there is none.", "example": "https://cdn.example.com/bus/expresso-brasileiro.png" } }, "required": [ "name", "logo" ], "description": "Company that operates the trip." }, "passengerId": { "type": "string", "description": "ID of the passenger travelling on this ticket — one of the trip's `passengers[]`. Omitted only if the passenger could not be matched to the trip's passengers.", "example": "6710a3f2c9e77b0012a4d5e1" }, "segments": { "type": "array", "items": { "type": "object", "properties": { "seatNumber": { "type": "number", "description": "Seat reserved on the segment.", "example": 12 }, "serviceClass": { "type": "string", "enum": [ "SLEEPER_BED", "BED", "SEMI_BED", "EXECUTIVE", "CONVENTIONAL", "UNDEFINED" ], "description": "Class of service booked for the segment.", "example": "EXECUTIVE" }, "origin": { "type": "object", "properties": { "locality": { "type": "string", "description": "City the station sits in.", "example": "São Paulo" }, "administrativeArea": { "type": "string", "description": "State, as its short code.", "example": "SP" }, "name": { "type": "string", "nullable": true, "description": "Official name of the station. `null` when unknown.", "example": "Terminal Rodoviário Tietê" }, "shortAddress": { "type": "string", "nullable": true, "description": "Readable single-line address of the station. `null` when unknown.", "example": "Av. Cruzeiro do Sul, 1800, São Paulo, SP, Brazil" }, "phoneNumbers": { "type": "array", "items": { "type": "string", "example": "551133336666" }, "description": "Contact phone numbers of the station, digits only. Empty when none is registered.\n\n---\n\nExample: `[\"551133336666\"]`" } }, "required": [ "locality", "administrativeArea", "name", "shortAddress", "phoneNumbers" ], "description": "Station the segment leaves from." }, "destination": { "type": "object", "properties": { "locality": { "type": "string", "description": "City the station sits in.", "example": "São Paulo" }, "administrativeArea": { "type": "string", "description": "State, as its short code.", "example": "SP" }, "name": { "type": "string", "nullable": true, "description": "Official name of the station. `null` when unknown.", "example": "Terminal Rodoviário Tietê" }, "shortAddress": { "type": "string", "nullable": true, "description": "Readable single-line address of the station. `null` when unknown.", "example": "Av. Cruzeiro do Sul, 1800, São Paulo, SP, Brazil" }, "phoneNumbers": { "type": "array", "items": { "type": "string", "example": "551133336666" }, "description": "Contact phone numbers of the station, digits only. Empty when none is registered.\n\n---\n\nExample: `[\"551133336666\"]`" } }, "required": [ "locality", "administrativeArea", "name", "shortAddress", "phoneNumbers" ], "description": "Station the segment arrives at.", "example": { "locality": "Rio de Janeiro", "administrativeArea": "RJ", "name": "Rodoviária Novo Rio", "shortAddress": "Av. Francisco Bicalho, 1, Rio de Janeiro, RJ, Brazil", "phoneNumbers": [ "552133338888" ] } }, "departureDate": { "type": "string", "description": "Departure date and time in the local time of the origin station, as `YYYY-MM-DDTHH:mm:ss` with no time zone.", "example": "2026-11-02T08:30:00" }, "arrivalDate": { "type": "string", "description": "Arrival date and time in the local time of the destination station, as `YYYY-MM-DDTHH:mm:ss` with no time zone.", "example": "2026-11-02T14:45:00" }, "duration": { "type": "string", "nullable": true, "description": "Duration of the leg, as `HH:mm`. `null` when not available.", "example": "06:15" }, "fare": { "type": "object", "properties": { "originalAmount": { "type": "number", "description": "Fare before discounts and fees, in cents.", "example": 18000 }, "discountAmount": { "type": "number", "description": "Discount applied to the fare, in cents.", "example": 1000 }, "feeAmount": { "type": "number", "description": "Fees added to the fare, in cents.", "example": 500 }, "amount": { "type": "number", "description": "Total charged for the fare, in cents: `originalAmount` - `discountAmount` + `feeAmount`.", "example": 17500 }, "currency": { "type": "string", "description": "Currency, as the ISO 4217 alphabetic code.", "example": "BRL" }, "cancellationPolicies": { "type": "object", "properties": { "refundable": { "type": "boolean", "description": "Whether cancelling gives any money back.", "example": true }, "immediateFine": { "type": "boolean", "description": "Whether a fine applies to a cancellation made right after the booking.", "example": false }, "penalties": { "type": "array", "items": { "type": "object", "properties": { "from": { "type": "string", "description": "First day (`YYYY-MM-DD`) on which this tier applies.", "example": "2026-10-25" }, "currency": { "type": "string", "description": "Currency, as the ISO 4217 alphabetic code.", "example": "BRL" }, "fineAmount": { "type": "number", "nullable": true, "description": "Fine charged for cancelling from `from` onward, in cents. `null` when the amount is not available.", "example": 15000 } }, "required": [ "from", "currency", "fineAmount" ], "description": "One tier of a cancellation penalty schedule." }, "description": "Penalty tiers, each in effect from its own date. Empty when no scheduled penalty applies." } }, "required": [ "refundable", "immediateFine", "penalties" ], "description": "Cancellation rules of the fare." } }, "required": [ "originalAmount", "discountAmount", "feeAmount", "amount", "currency", "cancellationPolicies" ], "description": "Fare of the segment." }, "company": { "type": "object", "properties": { "name": { "type": "string", "description": "Commercial name of the company.", "example": "Expresso Brasileiro" }, "logo": { "type": "string", "nullable": true, "description": "URL of the company's logo. `null` when there is none.", "example": "https://cdn.example.com/bus/expresso-brasileiro.png" } }, "required": [ "name", "logo" ], "description": "Operator running this leg." } }, "required": [ "seatNumber", "serviceClass", "origin", "destination", "departureDate", "arrivalDate", "duration", "fare", "company" ], "description": "One leg of the bus trip, with the seat booked on it." }, "description": "Segments of the trip, one per leg, each with its seat, fare and operator." }, "routeDirection": { "type": "string", "enum": [ "DEPARTURE", "RETURN" ], "description": "Whether this booking is the outbound trip (`DEPARTURE`) or the return trip (`RETURN`).", "example": "DEPARTURE" }, "boardingInfo": { "description": "Boarding pass and, per leg, platform and ticket codes. `null` until it is first collected, as the departure approaches.", "example": null, "type": "object", "properties": { "boardingPass": { "type": "string", "nullable": true, "description": "The boarding pass PDF, base64-encoded. `null` when not available yet.", "example": "JVBERi0xLjcK" }, "routes": { "type": "array", "items": { "type": "object", "properties": { "origin": { "type": "string", "description": "City the leg starts in.", "example": "São Paulo" }, "destination": { "type": "string", "description": "City the leg ends in.", "example": "Rio de Janeiro" }, "platform": { "type": "string", "nullable": true, "description": "Boarding platform at the origin station. `null` when not assigned or not applicable.", "example": "14" }, "departureDate": { "type": "string", "description": "Departure date and time in local time, as `YYYY-MM-DDTHH:mm:ss` with no time zone.", "example": "2026-11-02T08:30:00" }, "arrivalDate": { "type": "string", "description": "Arrival date and time in local time, as `YYYY-MM-DDTHH:mm:ss` with no time zone.", "example": "2026-11-02T14:45:00" }, "tickets": { "type": "array", "items": { "type": "object", "properties": { "passengerId": { "type": "string", "description": "ID of the passenger the ticket belongs to — one of the trip's `passengers[]`. Omitted only if the passenger could not be matched to the trip's passengers.", "example": "6710a3f2c9e77b0012a4d5e1" }, "locators": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "Kind of reference, such as `PNR` for an airline's booking code.", "example": "PNR" }, "code": { "type": "string", "description": "The reference itself, as the supplier issued it.", "example": "ABC123" } }, "required": [ "type", "code" ], "description": "A reference that identifies the booking with the supplier, such as an airline's booking code." }, "description": "Booking references of the ticket. Empty when none is available." }, "ticketCode": { "type": "string", "nullable": true, "description": "Code of the ticket. `null` when not available.", "example": "EB123456" }, "qrCode": { "type": "string", "nullable": true, "description": "The boarding QR code image, base64-encoded. `null` when not available.", "example": "iVBORw0KGgo=" }, "bpeNumber": { "type": "string", "nullable": true, "description": "Number of the electronic bus ticket (BP-e). `null` when not available.", "example": "35261112345678000190630010000123451000123456" } }, "required": [ "locators", "ticketCode", "qrCode", "bpeNumber" ], "description": "The boarding ticket of one passenger on one leg." }, "description": "Tickets of the leg, one per passenger." } }, "required": [ "origin", "destination", "platform", "departureDate", "arrivalDate", "tickets" ], "description": "The boarding details of one leg of the trip." }, "description": "Boarding details per leg. A connection has two legs; direct and one-stop trips have one." } }, "required": [ "boardingPass", "routes" ], "nullable": true } }, "required": [ "type", "origin", "destination", "departureDate", "arrivalDate", "company", "segments", "routeDirection", "boardingInfo" ], "description": "The booked bus trip of one passenger (by ID): stations, operator, the legs with their seats and fares, and boarding information. This is the shape of `productSnapshot` when the trip's `vertical` is `BUS`. Amounts are integers in cents.", "title": "Bus trip" }, { "type": "object", "properties": { "groupName": { "type": "string", "description": "Commercial group the vehicle belongs to, such as `ECONOMY` or `SUV`.", "example": "ECONOMY" }, "class": { "type": "string", "description": "Class of the vehicle within its group.", "example": "INTERMEDIATE" }, "name": { "type": "string", "description": "Name of the vehicle, as the rental company displays it.", "example": "Fiat Mobi" }, "sipp": { "type": "string", "description": "SIPP code that classifies the vehicle by size, doors, transmission and fuel.", "example": "ECMR" }, "rentalCompany": { "type": "object", "properties": { "code": { "type": "string", "description": "Code of the rental company.", "example": "LOC" }, "name": { "type": "string", "description": "Commercial name of the rental company.", "example": "Localiza" }, "logo": { "type": "string", "nullable": true, "description": "URL of the rental company's logo. `null` when the company has no registered logo.", "example": "https://cdn.example.com/rentals/localiza.svg" } }, "required": [ "code", "name", "logo" ], "description": "Rental company that holds the booking." }, "pickUpLocation": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the rental location.", "example": "Localiza Aeroporto Guarulhos (GRU)" }, "phoneNumbers": { "type": "array", "items": { "type": "string", "example": "551133337777" }, "description": "Contact phone numbers of the location, digits only. Empty when none is registered.\n\n---\n\nExample: `[\"551133337777\"]`" }, "shortAddress": { "type": "string", "nullable": true, "description": "Readable single-line address of the location. `null` when unknown.", "example": "Rod. Hélio Smidt, s/n, Guarulhos, SP, Brazil" }, "locality": { "type": "string", "nullable": true, "description": "City the location sits in. `null` when unknown.", "example": "Guarulhos" }, "administrativeArea": { "type": "string", "nullable": true, "description": "State, as its short code. `null` when unknown.", "example": "SP" } }, "required": [ "name", "phoneNumbers", "shortAddress", "locality", "administrativeArea" ], "description": "Where the vehicle is picked up." }, "dropOffLocation": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the rental location.", "example": "Localiza Aeroporto Guarulhos (GRU)" }, "phoneNumbers": { "type": "array", "items": { "type": "string", "example": "551133337777" }, "description": "Contact phone numbers of the location, digits only. Empty when none is registered.\n\n---\n\nExample: `[\"551133337777\"]`" }, "shortAddress": { "type": "string", "nullable": true, "description": "Readable single-line address of the location. `null` when unknown.", "example": "Rod. Hélio Smidt, s/n, Guarulhos, SP, Brazil" }, "locality": { "type": "string", "nullable": true, "description": "City the location sits in. `null` when unknown.", "example": "Guarulhos" }, "administrativeArea": { "type": "string", "nullable": true, "description": "State, as its short code. `null` when unknown.", "example": "SP" } }, "required": [ "name", "phoneNumbers", "shortAddress", "locality", "administrativeArea" ], "description": "Where the vehicle is dropped off." }, "pickUpDate": { "type": "string", "description": "Pick-up date and time in the local time of the pick-up location, as `YYYY-MM-DDTHH:mm:ss` with no time zone.", "example": "2026-11-02T10:00:00" }, "dropOffDate": { "type": "string", "description": "Drop-off date and time in the local time of the drop-off location, as `YYYY-MM-DDTHH:mm:ss` with no time zone.", "example": "2026-11-04T10:00:00" }, "rentals": { "type": "array", "items": { "type": "object", "properties": { "description": { "type": "string", "nullable": true, "description": "Readable description of the rental option. `null` when not provided.", "example": "Compact car, air conditioning, unlimited mileage" }, "fare": { "type": "object", "properties": { "originalAmount": { "type": "number", "description": "Fare before discounts and fees, in cents.", "example": 36000 }, "discountAmount": { "type": "number", "description": "Discount applied to the fare, in cents.", "example": 2000 }, "feeAmount": { "type": "number", "description": "Fees added to the fare, in cents.", "example": 0 }, "amount": { "type": "number", "description": "Total charged for the fare, in cents: `originalAmount` - `discountAmount` + `feeAmount`.", "example": 34000 }, "currency": { "type": "string", "description": "Currency, as the ISO 4217 alphabetic code.", "example": "BRL" }, "cancellationPolicies": { "type": "object", "properties": { "refundable": { "type": "boolean", "description": "Whether cancelling gives any money back.", "example": true }, "immediateFine": { "type": "boolean", "description": "Whether a fine applies to a cancellation made right after the booking.", "example": false }, "penalties": { "type": "array", "items": { "type": "object", "properties": { "from": { "type": "string", "nullable": true, "description": "First day (`YYYY-MM-DD`) on which this tier applies. `null` when the supplier gave no date.", "example": "2026-10-31" }, "currency": { "type": "string", "description": "Currency, as the ISO 4217 alphabetic code.", "example": "BRL" }, "fineAmount": { "type": "number", "nullable": true, "description": "Fine charged for cancelling from `from` onward, in cents. `null` when the amount is not available.", "example": 12000 } }, "required": [ "from", "currency", "fineAmount" ], "description": "One tier of the cancellation penalty schedule of a rental." }, "description": "Penalty tiers, each in effect from its own date. Empty when no scheduled penalty applies." } }, "required": [ "refundable", "immediateFine", "penalties" ], "description": "Cancellation rules of the fare." } }, "required": [ "originalAmount", "discountAmount", "feeAmount", "amount", "currency", "cancellationPolicies" ], "description": "Fare of the rental." }, "passengersId": { "type": "array", "items": { "type": "string", "example": "6710a3f2c9e77b0012a4d5e1" }, "description": "IDs of the passengers travelling on this rental — the trip's `passengers[]`. Empty when none was assigned.\n\n---\n\nExample: `[\"6710a3f2c9e77b0012a4d5e1\"]`" }, "locators": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "Kind of reference, such as `PNR` for an airline's booking code.", "example": "PNR" }, "code": { "type": "string", "description": "The reference itself, as the supplier issued it.", "example": "ABC123" } }, "required": [ "type", "code" ], "description": "A reference that identifies the booking with the supplier, such as an airline's booking code." }, "description": "Booking references of the rental with the rental company. Empty until the reservation is confirmed." } }, "required": [ "description", "fare", "passengersId", "locators" ], "description": "A booked rental." }, "description": "Rentals booked under this record." }, "locators": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "Kind of reference, such as `PNR` for an airline's booking code.", "example": "PNR" }, "code": { "type": "string", "description": "The reference itself, as the supplier issued it.", "example": "ABC123" } }, "required": [ "type", "code" ], "description": "A reference that identifies the booking with the supplier, such as an airline's booking code." }, "description": "Booking references of the reservation as a whole. Empty until the reservation is confirmed." } }, "required": [ "groupName", "class", "name", "sipp", "rentalCompany", "pickUpLocation", "dropOffLocation", "pickUpDate", "dropOffDate", "rentals", "locators" ], "description": "The booked vehicle rental: the vehicle, the rental company, the pick-up and drop-off places and dates, fares, passengers (by ID) and reservation locators. This is the shape of `productSnapshot` when the trip's `vertical` is `VEHICLE`. Amounts are integers in cents.", "title": "Vehicle trip" } ], "description": "The booked product: the itinerary, stay, ticket or rental as recorded by the travel provider — journeys and flights, the hotel and its rooms, the route and boarding information, the rental — with its fares, policies and booking locators. It does not repeat the trip's own fields (`state`, `status`, the amounts, the dates) and carries no identifier of the travel provider; passengers are referenced by their `id` in `passengers[]`. Its shape depends on `vertical`: a flight (`AIR`), a hotel stay (`HOTEL`), a bus ticket (`BUS`) or a vehicle rental (`VEHICLE`) — see the four schemas below. Omitted until the record is first fetched." }, "cancellation": { "type": "object", "properties": { "quoteId": { "type": "string", "description": "ID of the confirmed cancellation quote." }, "cancelType": { "type": "string", "enum": [ "CREDIT", "REFUND", "MANUAL_CANCEL", "VOID" ], "description": "Kind of cancellation: `VOID` for a trip not issued yet, `REFUND` or `CREDIT` for an issued one, `MANUAL_CANCEL` when the amounts are settled outside the system." }, "originalAmount": { "type": "number", "nullable": true, "description": "What the trip cost, in cents. Omitted when it couldn't be recorded; `null` for `MANUAL_CANCEL`." }, "remainingAmount": { "type": "number", "nullable": true, "description": "What is given back after the fine, in cents. Omitted when it couldn't be recorded; `null` for `MANUAL_CANCEL`." }, "fineAmount": { "type": "number", "nullable": true, "description": "Cancellation fine, in cents. Omitted when it couldn't be recorded; `null` for `MANUAL_CANCEL`." }, "currency": { "type": "string", "description": "Currency of the amounts, as the numeric ISO 4217 code (`986` is BRL)." }, "status": { "type": "string", "description": "Status of the quote when it was confirmed." }, "expiresAt": { "type": "string", "description": "When the quote would have expired.", "format": "date-time" }, "confirmedAt": { "type": "string", "description": "When the cancellation was confirmed.", "format": "date-time" }, "confirmedBy": { "type": "string", "description": "ID of the user who confirmed the cancellation. Omitted when a service did." } }, "required": [ "quoteId", "cancelType" ], "description": "The confirmed cancellation. Omitted until one is confirmed." }, "createdAt": { "type": "string", "description": "When the trip was created.", "example": "2026-10-01T13:45:12.000Z", "format": "date-time" }, "updatedAt": { "type": "string", "description": "When the trip last changed.", "example": "2026-10-01T13:46:03.000Z", "format": "date-time" } }, "required": [ "id", "realmId", "organizationId", "customFields", "vertical", "state", "status", "passengers" ], "description": "A trip: ONE booked product — a flight, a hotel stay, a bus ticket or a vehicle rental — for the organization's passengers, with its lifecycle. Booking several products means creating several trips." }, "description": "Trips, newest first." }, "next": { "type": "string", "nullable": true, "description": "Cursor for the next page. `null` on the last page.", "example": "eyJjIjoiMjAyNi0xMC0wMVQxMzo0NToxMi4wMDBaIiwiaSI6IjY3MTFiNGMwZDhlMWEzMDAxMmI3YzlmMiJ9" } }, "required": [ "items", "next" ], "description": "One page of the trip list." } } } }, "403": { "description": "`TRAVEL_ADMIN_OR_SELF_REQUIRED` — You are neither an organization admin nor the user the passenger is linked to.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "TRAVEL_ADMIN_OR_SELF_REQUIRED" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "TRAVEL" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b", "code": "TRAVEL_ADMIN_OR_SELF_REQUIRED", "origin": "TRAVEL", "message": "Organization admin or the passenger themself required" } } } }, "404": { "description": "`PASSENGER_NOT_FOUND` — No active passenger with this ID exists in the organization.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "PASSENGER_NOT_FOUND" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "TRAVEL" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b", "code": "PASSENGER_NOT_FOUND", "origin": "TRAVEL", "message": "Passenger not found" } } } }, "422": { "description": "`BAD_REQUEST` — A path or query parameter is invalid; `fields` lists each one.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "BAD_REQUEST" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "TRAVEL" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." }, "fields": { "type": "array", "description": "One entry per invalid request field (validation errors only).", "items": { "type": "object", "properties": { "field": { "type": "string", "description": "Path of the invalid field, e.g. `label` or `values[0].value`.", "example": "label" }, "message": { "type": "string", "description": "Why the field was rejected.", "example": "label is required" }, "code": { "type": "string", "description": "`_` — e.g. `LABEL_REQUIRED`, `TYPE_ONE_OF`, `VALUES_VALUE_TYPE_ERROR`.", "example": "LABEL_REQUIRED" }, "values": { "type": "array", "items": { "type": "string" }, "description": "The accepted values, when the field is an enumeration." } }, "required": [ "field", "message", "code" ] } } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "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": "vertical", "message": "Invalid option: expected one of \"AIR\"|\"HOTEL\"|\"BUS\"|\"VEHICLE\"", "code": "VERTICAL_ONE_OF" } ] } } } } }, "x-p3-confidence": { "response": "generated:typed", "parameters": "generated:typed", "note": "`.refine(…)` constraint not represented (runtime-dependent value)" } } }, "/realms/{realmId}/organizations/{organizationId}/trips/{tripId}": { "get": { "operationId": "getRealmsByRealmIdOrganizationsByOrganizationIdTripsByTripId", "summary": "Get a trip", "tags": [ "Trips" ], "x-p3-sidebar-order": 5, "description": "Returns a trip: its booked product, passengers and where the booking is.", "x-mint": { "content": "An organization admin can read any trip of the organization; a user can read the trips they travel on. Requesting a trip grants no access to it: someone who booked it for others, and is not on it, doesn't see it. The trip is brought up to date with the travel provider before the answer, so the state you read is current; if the provider can't be reached you get the last recorded one." }, "parameters": [ { "name": "realmId", "in": "path", "required": true, "description": "ID of your realm.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b" }, { "name": "organizationId", "in": "path", "required": true, "description": "ID of the organization the trip belongs to.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410" }, { "name": "tripId", "in": "path", "required": true, "description": "ID of the trip (24 hexadecimal characters).", "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$" }, "example": "6711b4c0d8e1a30012b7c9f2" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the trip.", "example": "6711b4c0d8e1a30012b7c9f2" }, "realmId": { "type": "string", "description": "ID of the realm the trip belongs to.", "example": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b", "format": "uuid" }, "organizationId": { "type": "string", "description": "ID of the organization the trip belongs to.", "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410", "format": "uuid" }, "createdBy": { "type": "string", "description": "ID of the user who created the trip. Omitted when a service did.", "example": "e3553bc1-5e20-4e17-b22a-a796fda0aa99", "format": "uuid" }, "customFields": { "type": "object", "additionalProperties": {}, "description": "Values of the organization's trip custom fields, keyed by the custom field's `slug`. Empty when none were set.\n\n---\n\nExample: `{\"cost-center\":\"CC-1020\"}`", "example": { "cost-center": "CC-1020" } }, "vertical": { "type": "string", "enum": [ "AIR", "HOTEL", "BUS", "VEHICLE" ], "description": "Type of product booked. It tells which shape `productSnapshot` has.", "example": "AIR" }, "state": { "type": "string", "enum": [ "PENDING", "RESERVED", "ISSUED", "CANCELED" ], "description": "Where the booking is in its life: `PENDING` while the reservation is being made, `RESERVED` once held (until `reservationExpiresAt`), `ISSUED` once ticketed and `CANCELED`. It only moves forward.", "example": "RESERVED" }, "status": { "type": "string", "enum": [ "PROCESSING_RESERVATION", "RESERVATION_FAILED", "RESERVED", "PROCESSING_ISSUE", "ISSUED", "PROCESSING_CANCELLATION", "CANCELED", "AWAITING_MANUAL_CANCELLATION", "CANCELLATION_FAILED", "FAILED", "FAILED_BY_INCONSISTENT_DATA", "FAILED_BY_UNAVAILABLE_RESOURCE", "FAILED_BY_BUDGET_EXCEEDED", "EXPIRED", "BLOCKED", "UNKNOWN", "ISSUANCE_FAILED" ], "description": "Finer-grained status: it also reports work in progress (`PROCESSING_*`) and failures, and can change back and forth. Use `state` to decide what the booking is; use `status` to tell what is happening to it.", "example": "RESERVED" }, "reservationExpiresAt": { "type": "string", "nullable": true, "description": "Until when the reservation is held. Past it, a trip that was not issued expires. `null` or omitted when there is no hold.", "example": "2026-10-02T13:45:12.000Z", "format": "date-time" }, "issuedAt": { "type": "string", "nullable": true, "description": "When the trip was issued. `null` or omitted until it is.", "format": "date-time" }, "originalAmount": { "type": "number", "description": "Price before discounts, in cents. Omitted until the price is known.", "example": 95000 }, "discountAmount": { "type": "number", "description": "Discount applied, in cents. Omitted until the price is known.", "example": 3010 }, "feeAmount": { "type": "number", "description": "Fees added, in cents. Omitted until the price is known.", "example": 0 }, "totalAmount": { "type": "number", "description": "Amount to pay, in cents: `originalAmount` - `discountAmount` + `feeAmount`. Omitted until the price is known.", "example": 91990 }, "currency": { "type": "string", "description": "Currency of the amounts, as the numeric ISO 4217 code (`986` is BRL).", "example": "986" }, "passengers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the passenger, as returned by the passenger endpoints.", "example": "6710a3f2c9e77b0012a4d5e1" }, "userId": { "type": "string", "description": "ID of the organization user the passenger is linked to. Omitted for a passenger who is not a user. A user sees the trips they travel on.", "example": "e3553bc1-5e20-4e17-b22a-a796fda0aa99", "format": "uuid" }, "lead": { "type": "boolean", "description": "Whether this passenger is the one responsible for the reservation.", "example": true }, "name": { "type": "string", "description": "Full name, as it appears on the passenger's travel documents.", "example": "Mariana Costa" }, "gender": { "type": "string", "enum": [ "MALE", "FEMALE" ], "description": "Gender.", "example": "FEMALE" }, "birthDate": { "type": "string", "description": "Date of birth (`YYYY-MM-DD`).", "example": "1990-04-17" } }, "required": [ "id", "lead", "name", "gender", "birthDate" ], "description": "A passenger of a trip: who travels, as recorded when the trip was booked. The passenger endpoints serve the full profile." }, "description": "The passengers booked on the trip." }, "productSnapshot": { "anyOf": [ { "type": "object", "properties": { "journeys": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the journey, referenced by `tickets[].fares[].journeyId`.", "example": "jour_V1StGXR8Z5jdHi6BmyT2k" }, "direction": { "type": "string", "enum": [ "DEPARTURE", "RETURN" ], "description": "Whether this is the outbound leg (`DEPARTURE`) or the return leg (`RETURN`).", "example": "DEPARTURE" }, "origin": { "type": "object", "properties": { "iata": { "type": "string", "description": "IATA code of the airport, 3 letters.", "example": "GRU" }, "name": { "type": "string", "nullable": true, "description": "Official name of the airport. `null` when unknown.", "example": "São Paulo/Guarulhos International Airport" }, "shortAddress": { "type": "string", "nullable": true, "description": "Readable single-line address of the airport. `null` when unknown.", "example": "Guarulhos, SP, Brazil" }, "locality": { "type": "string", "nullable": true, "description": "City the airport sits in. `null` when unknown.", "example": "Guarulhos" }, "administrativeArea": { "type": "string", "nullable": true, "description": "State, as its short code. `null` when unknown.", "example": "SP" }, "phoneNumbers": { "type": "array", "items": { "type": "string", "example": "551133334444" }, "description": "Contact phone numbers of the airport, digits only. Empty when none is registered.\n\n---\n\nExample: `[\"551133334444\"]`" } }, "required": [ "iata", "name", "shortAddress", "locality", "administrativeArea", "phoneNumbers" ], "description": "Airport the journey starts at." }, "destination": { "type": "object", "properties": { "iata": { "type": "string", "description": "IATA code of the airport, 3 letters.", "example": "GRU" }, "name": { "type": "string", "nullable": true, "description": "Official name of the airport. `null` when unknown.", "example": "São Paulo/Guarulhos International Airport" }, "shortAddress": { "type": "string", "nullable": true, "description": "Readable single-line address of the airport. `null` when unknown.", "example": "Guarulhos, SP, Brazil" }, "locality": { "type": "string", "nullable": true, "description": "City the airport sits in. `null` when unknown.", "example": "Guarulhos" }, "administrativeArea": { "type": "string", "nullable": true, "description": "State, as its short code. `null` when unknown.", "example": "SP" }, "phoneNumbers": { "type": "array", "items": { "type": "string", "example": "551133334444" }, "description": "Contact phone numbers of the airport, digits only. Empty when none is registered.\n\n---\n\nExample: `[\"551133334444\"]`" } }, "required": [ "iata", "name", "shortAddress", "locality", "administrativeArea", "phoneNumbers" ], "description": "Airport the journey ends at.", "example": { "iata": "SDU", "name": "Rio de Janeiro/Santos Dumont Airport", "shortAddress": "Rio de Janeiro, RJ, Brazil", "locality": "Rio de Janeiro", "administrativeArea": "RJ", "phoneNumbers": [ "552133339999" ] } }, "departureDate": { "type": "string", "description": "Departure date and time in the local time of the origin airport, as `YYYY-MM-DDTHH:mm:ss` with no time zone.", "example": "2026-11-02T08:30:00" }, "arrivalDate": { "type": "string", "description": "Arrival date and time in the local time of the destination airport, as `YYYY-MM-DDTHH:mm:ss` with no time zone.", "example": "2026-11-02T09:35:00" }, "duration": { "type": "string", "description": "Total travel time of the journey, connections included, as `HH:mm`.", "example": "01:05" }, "segments": { "type": "array", "items": { "type": "object", "properties": { "airline": { "type": "object", "properties": { "code": { "type": "string", "description": "IATA code of the airline.", "example": "LA" }, "name": { "type": "string", "nullable": true, "description": "Commercial name of the airline. `null` when unknown.", "example": "LATAM Airlines" }, "logo": { "type": "string", "nullable": true, "description": "URL of the airline's logo. `null` when there is none.", "example": "https://cdn.example.com/airlines/LA.png" } }, "required": [ "code", "name", "logo" ], "description": "Airline that sells the flight." }, "operation": { "type": "object", "properties": { "code": { "type": "string", "description": "IATA code of the airline.", "example": "LA" }, "name": { "type": "string", "nullable": true, "description": "Commercial name of the airline. `null` when unknown.", "example": "LATAM Airlines" }, "logo": { "type": "string", "nullable": true, "description": "URL of the airline's logo. `null` when there is none.", "example": "https://cdn.example.com/airlines/LA.png" } }, "required": [ "code", "name", "logo" ], "description": "Airline that operates the flight. It differs from `airline` on codeshare flights." }, "origin": { "type": "object", "properties": { "iata": { "type": "string", "description": "IATA code of the airport, 3 letters.", "example": "GRU" }, "name": { "type": "string", "nullable": true, "description": "Official name of the airport. `null` when unknown.", "example": "São Paulo/Guarulhos International Airport" }, "shortAddress": { "type": "string", "nullable": true, "description": "Readable single-line address of the airport. `null` when unknown.", "example": "Guarulhos, SP, Brazil" }, "locality": { "type": "string", "nullable": true, "description": "City the airport sits in. `null` when unknown.", "example": "Guarulhos" }, "administrativeArea": { "type": "string", "nullable": true, "description": "State, as its short code. `null` when unknown.", "example": "SP" }, "phoneNumbers": { "type": "array", "items": { "type": "string", "example": "551133334444" }, "description": "Contact phone numbers of the airport, digits only. Empty when none is registered.\n\n---\n\nExample: `[\"551133334444\"]`" } }, "required": [ "iata", "name", "shortAddress", "locality", "administrativeArea", "phoneNumbers" ], "description": "Airport the flight leaves from." }, "destination": { "type": "object", "properties": { "iata": { "type": "string", "description": "IATA code of the airport, 3 letters.", "example": "GRU" }, "name": { "type": "string", "nullable": true, "description": "Official name of the airport. `null` when unknown.", "example": "São Paulo/Guarulhos International Airport" }, "shortAddress": { "type": "string", "nullable": true, "description": "Readable single-line address of the airport. `null` when unknown.", "example": "Guarulhos, SP, Brazil" }, "locality": { "type": "string", "nullable": true, "description": "City the airport sits in. `null` when unknown.", "example": "Guarulhos" }, "administrativeArea": { "type": "string", "nullable": true, "description": "State, as its short code. `null` when unknown.", "example": "SP" }, "phoneNumbers": { "type": "array", "items": { "type": "string", "example": "551133334444" }, "description": "Contact phone numbers of the airport, digits only. Empty when none is registered.\n\n---\n\nExample: `[\"551133334444\"]`" } }, "required": [ "iata", "name", "shortAddress", "locality", "administrativeArea", "phoneNumbers" ], "description": "Airport the flight arrives at.", "example": { "iata": "SDU", "name": "Rio de Janeiro/Santos Dumont Airport", "shortAddress": "Rio de Janeiro, RJ, Brazil", "locality": "Rio de Janeiro", "administrativeArea": "RJ", "phoneNumbers": [ "552133339999" ] } }, "flightNumber": { "type": "string", "description": "Number of the flight, without the airline's code.", "example": "3101" }, "departureDate": { "type": "string", "description": "Departure date and time in the local time of the departure airport, as `YYYY-MM-DDTHH:mm:ss` with no time zone.", "example": "2026-11-02T08:30:00" }, "arrivalDate": { "type": "string", "description": "Arrival date and time in the local time of the arrival airport, as `YYYY-MM-DDTHH:mm:ss` with no time zone.", "example": "2026-11-02T09:35:00" }, "flightType": { "type": "string", "enum": [ "CHARTER", "ALLOTMENT", "REGULAR" ], "description": "Kind of flight: `REGULAR`, `CHARTER` or `ALLOTMENT`.", "example": "REGULAR" }, "duration": { "type": "string", "description": "Duration of the flight, as `HH:mm`.", "example": "01:05" }, "equipment": { "type": "string", "nullable": true, "description": "Aircraft scheduled for the flight, as the airline identifies it. `null` when not informed.", "example": "32Q" }, "cabin": { "type": "string", "enum": [ "ECONOMY", "PREMIUM_ECONOMY", "BUSINESS", "FIRST_CLASS", "UNDEFINED" ], "description": "Cabin booked for the flight.", "example": "ECONOMY" }, "class": { "type": "string", "nullable": true, "description": "Booking class (RBD) priced for the flight. Each airline defines its own codes. `null` when the airline does not expose it.", "example": "Y" }, "fareBasis": { "type": "string", "nullable": true, "description": "Fare basis code priced for the flight. Each airline defines its own codes. `null` when the airline does not expose it.", "example": "YOW" }, "flightInfo": { "description": "Live information about the flight. `null` until it is first collected, as the departure approaches.", "example": null, "type": "object", "properties": { "state": { "type": "string", "nullable": true, "enum": [ "SCHEDULED", "OUT_GATE", "IN_AIR", "LANDED", "IN_GATE", "CANCELED", "PROPOSED", "UNKNOWN", null ], "description": "Operational state of the flight. `null` when there is no live status yet.", "example": "SCHEDULED" }, "updatedAt": { "type": "string", "nullable": true, "description": "When the live status was captured. `null` when there is no live status yet.", "example": "2026-11-01T18:00:00.000Z" }, "aircraft": { "description": "Aircraft operating the flight. `null` when not known yet.", "type": "object", "properties": { "registration": { "type": "string", "nullable": true, "description": "Tail registration of the aircraft. `null` when not known yet.", "example": "PR-XBA" }, "type": { "type": "string", "nullable": true, "description": "ICAO code of the aircraft type. `null` when not known yet.", "example": "A21N" } }, "required": [ "registration", "type" ], "nullable": true }, "departure": { "type": "object", "properties": { "terminal": { "type": "string", "nullable": true, "description": "Terminal at the airport. `null` when not reported yet.", "example": "2" }, "gate": { "type": "string", "nullable": true, "description": "Gate at the airport. `null` when not reported yet.", "example": "B12" }, "baggage": { "type": "string", "nullable": true, "description": "Baggage belt, reported for arrivals only. `null` for departures and when not reported yet.", "example": "04" }, "estimatedTime": { "type": "string", "nullable": true, "description": "Estimated time at the gate, in UTC (ISO 8601). `null` when not known yet.", "example": "2026-11-02T11:30:00.000Z" }, "actualTime": { "type": "string", "nullable": true, "description": "Actual time at the gate, in UTC (ISO 8601), reported once the flight operates. `null` before that.", "example": "2026-11-02T11:34:00.000Z" }, "timeliness": { "type": "string", "nullable": true, "description": "Punctuality of the flight, such as `OnTime`, `Early` or `Delayed`. `null` when not known.", "example": "OnTime" }, "delayMinutes": { "type": "number", "nullable": true, "description": "Delay in minutes; negative when the flight is ahead of schedule. `null` when not known.", "example": 4 } }, "required": [ "terminal", "gate", "baggage", "estimatedTime", "actualTime", "timeliness", "delayMinutes" ], "description": "Live status at the departure airport." }, "arrival": { "type": "object", "properties": { "terminal": { "type": "string", "nullable": true, "description": "Terminal at the airport. `null` when not reported yet.", "example": "2" }, "gate": { "type": "string", "nullable": true, "description": "Gate at the airport. `null` when not reported yet.", "example": "B12" }, "baggage": { "type": "string", "nullable": true, "description": "Baggage belt, reported for arrivals only. `null` for departures and when not reported yet.", "example": "04" }, "estimatedTime": { "type": "string", "nullable": true, "description": "Estimated time at the gate, in UTC (ISO 8601). `null` when not known yet.", "example": "2026-11-02T11:30:00.000Z" }, "actualTime": { "type": "string", "nullable": true, "description": "Actual time at the gate, in UTC (ISO 8601), reported once the flight operates. `null` before that.", "example": "2026-11-02T11:34:00.000Z" }, "timeliness": { "type": "string", "nullable": true, "description": "Punctuality of the flight, such as `OnTime`, `Early` or `Delayed`. `null` when not known.", "example": "OnTime" }, "delayMinutes": { "type": "number", "nullable": true, "description": "Delay in minutes; negative when the flight is ahead of schedule. `null` when not known.", "example": 4 } }, "required": [ "terminal", "gate", "baggage", "estimatedTime", "actualTime", "timeliness", "delayMinutes" ], "description": "Live status at the arrival airport." } }, "required": [ "state", "updatedAt", "aircraft", "departure", "arrival" ], "nullable": true } }, "required": [ "airline", "operation", "origin", "destination", "flightNumber", "departureDate", "arrivalDate", "flightType", "duration", "equipment", "cabin", "class", "fareBasis", "flightInfo" ], "description": "One flight of a journey. A journey with connections has several." }, "description": "Flights of the journey, in chronological order, connections included." } }, "required": [ "id", "direction", "origin", "destination", "departureDate", "arrivalDate", "duration", "segments" ], "description": "One leg of the itinerary: the whole way from an origin to a destination, connections included." }, "description": "Legs of the itinerary, in travel order: one for a one-way trip, two (outbound and return) for a round trip." }, "tickets": { "type": "array", "items": { "type": "object", "properties": { "passengerId": { "type": "string", "description": "ID of the passenger holding this ticket — one of the trip's `passengers[]`. Omitted only if the passenger could not be matched to the trip's passengers.", "example": "6710a3f2c9e77b0012a4d5e1" }, "fareDescription": { "type": "string", "description": "Readable description of the fare of the ticket.", "example": "GRU to SDU, LATAM Airlines, Economy" }, "ticketNumber": { "type": "string", "nullable": true, "description": "Number of the ticket, as the airline issued it. `null` until the ticket is issued.", "example": null }, "fares": { "type": "array", "items": { "type": "object", "properties": { "journeyId": { "type": "string", "nullable": true, "description": "ID of the journey this fare covers — a `journeys[].id`. `null` when the fare covers the whole itinerary.", "example": "jour_V1StGXR8Z5jdHi6BmyT2k" }, "currency": { "type": "string", "description": "Currency, as the ISO 4217 alphabetic code.", "example": "BRL" }, "originalAmount": { "type": "number", "description": "Fare before discounts and fees, in cents.", "example": 95000 }, "discountAmount": { "type": "number", "description": "Discount applied to the fare, in cents.", "example": 3010 }, "feeAmount": { "type": "number", "description": "Fees added to the fare, in cents.", "example": 0 }, "amount": { "type": "number", "description": "Total charged for the fare, in cents: `originalAmount` - `discountAmount` + `feeAmount`.", "example": 91990 }, "cancellationPolicies": { "type": "object", "properties": { "refundable": { "type": "boolean", "description": "Whether cancelling gives any money back.", "example": true }, "immediateFine": { "type": "boolean", "description": "Whether a fine applies to a cancellation made right after the booking.", "example": false }, "penalties": { "type": "array", "items": { "type": "object", "properties": { "from": { "type": "string", "description": "First day (`YYYY-MM-DD`) on which this tier applies.", "example": "2026-10-25" }, "currency": { "type": "string", "description": "Currency, as the ISO 4217 alphabetic code.", "example": "BRL" }, "fineAmount": { "type": "number", "nullable": true, "description": "Fine charged for cancelling from `from` onward, in cents. `null` when the amount is not available.", "example": 15000 } }, "required": [ "from", "currency", "fineAmount" ], "description": "One tier of a cancellation penalty schedule." }, "description": "Penalty tiers, each in effect from its own date. Empty when no scheduled penalty applies." } }, "required": [ "refundable", "immediateFine", "penalties" ], "description": "Cancellation rules of the fare." }, "changePolicies": { "type": "object", "properties": { "canChange": { "type": "boolean", "description": "Whether the fare allows the booking to be changed.", "example": true }, "immediateFine": { "type": "boolean", "description": "Whether a fine applies to a change made right after the booking.", "example": false }, "penalties": { "type": "array", "items": { "type": "object", "properties": { "from": { "type": "string", "description": "First day (`YYYY-MM-DD`) on which this tier applies.", "example": "2026-10-25" }, "currency": { "type": "string", "description": "Currency, as the ISO 4217 alphabetic code.", "example": "BRL" }, "fineAmount": { "type": "number", "nullable": true, "description": "Fine charged for changing the booking from `from` onward, in cents. `null` when the amount is not available.", "example": 8000 } }, "required": [ "from", "currency", "fineAmount" ], "description": "One tier of a change penalty schedule." }, "description": "Penalty tiers, each in effect from its own date. Empty when no scheduled penalty applies." } }, "required": [ "canChange", "immediateFine", "penalties" ], "description": "Change rules of the fare." } }, "required": [ "journeyId", "currency", "originalAmount", "discountAmount", "feeAmount", "amount", "cancellationPolicies", "changePolicies" ], "description": "The fare of a ticket for one journey, or for the whole itinerary. Amounts are integers in cents." }, "description": "Fares of the ticket: one per journey, or a single one for the whole itinerary." }, "segments": { "type": "array", "items": { "type": "object", "properties": { "flightNumber": { "type": "string", "description": "Number of the flight this ticket covers, without the airline's code. It matches the `flightNumber` of one of the journeys' `segments`.", "example": "3101" }, "cabin": { "type": "string", "enum": [ "ECONOMY", "PREMIUM_ECONOMY", "BUSINESS", "FIRST_CLASS", "UNDEFINED" ], "description": "Cabin of the ticket on this flight.", "example": "ECONOMY" }, "class": { "type": "string", "nullable": true, "description": "Booking class (RBD) of the ticket on this flight. Each airline defines its own codes. `null` when the airline does not expose it.", "example": "Y" }, "fareBasis": { "type": "string", "nullable": true, "description": "Fare basis code of the ticket on this flight. Each airline defines its own codes. `null` when the airline does not expose it.", "example": "YOW" }, "baggages": { "type": "array", "items": { "type": "object", "properties": { "quantity": { "type": "number", "description": "Number of pieces included in the allowance.", "example": 1 }, "weight": { "type": "number", "nullable": true, "description": "Weight allowed per piece, in kg. `null` when the airline sets no weight limit per piece.", "example": 23 }, "type": { "type": "string", "enum": [ "CHECKED", "CARRY_ON", "PERSONAL_ITEM" ], "description": "Kind of baggage: `CHECKED`, `CARRY_ON` or `PERSONAL_ITEM`.", "example": "CHECKED" } }, "required": [ "quantity", "weight", "type" ], "description": "A baggage allowance of a ticket on one flight." }, "description": "Baggage allowance of the ticket on this flight. Empty for an infant on an adult's lap." } }, "required": [ "flightNumber", "cabin", "class", "fareBasis", "baggages" ], "description": "What a ticket covers on one flight of the itinerary: the cabin, the fare codes and the baggage allowance." }, "description": "What the ticket covers on each flight of the itinerary." } }, "required": [ "fareDescription", "ticketNumber", "fares", "segments" ], "description": "The ticket of one passenger. It covers the whole itinerary, with a fare per journey or a single fare for all of it." }, "description": "Tickets of the booking, one per passenger, each covering the whole itinerary." }, "locators": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "Kind of reference, such as `PNR` for an airline's booking code.", "example": "PNR" }, "code": { "type": "string", "description": "The reference itself, as the supplier issued it.", "example": "ABC123" } }, "required": [ "type", "code" ], "description": "A reference that identifies the booking with the supplier, such as an airline's booking code." }, "description": "Booking references issued by the airlines. Empty until the reservation is confirmed." }, "flightInfoUpdatedAt": { "type": "string", "nullable": true, "description": "When the live flight information was last collected. `null` until it is first collected.", "example": null, "format": "date-time" } }, "required": [ "journeys", "tickets", "locators", "flightInfoUpdatedAt" ], "description": "The booked flight: itinerary, the ticket of each passenger (by ID) with its fares and baggage, and reservation locators. This is the shape of `productSnapshot` when the trip's `vertical` is `AIR`. Amounts are integers in cents.", "title": "Air trip" }, { "type": "object", "properties": { "hotel": { "type": "object", "properties": { "name": { "type": "string", "description": "Official name of the hotel.", "example": "Hotel Paulista Plaza" }, "chain": { "type": "object", "properties": { "brandName": { "type": "string", "nullable": true, "description": "Brand within the chain. `null` when not informed.", "example": "Ibis" }, "chainName": { "type": "string", "nullable": true, "description": "Name of the chain. `null` for an independent hotel.", "example": "Accor" }, "logo": { "type": "string", "nullable": true, "description": "URL of the chain's logo. `null` when the hotel has no chain with a registered logo.", "example": "https://cdn.example.com/hotels/ibis.svg" } }, "required": [ "brandName", "chainName", "logo" ], "description": "Chain and brand of the hotel." }, "shortAddress": { "type": "string", "nullable": true, "description": "Readable single-line address of the hotel. `null` when unknown.", "example": "Av. Paulista, 1500, São Paulo, SP, Brazil" }, "phoneNumbers": { "type": "array", "items": { "type": "string", "example": "551133335555" }, "description": "Contact phone numbers of the hotel, digits only. Empty when none is registered.\n\n---\n\nExample: `[\"551133335555\"]`" }, "locality": { "type": "string", "nullable": true, "description": "City the hotel sits in. `null` when unknown.", "example": "São Paulo" }, "administrativeArea": { "type": "string", "nullable": true, "description": "State, as its short code. `null` when unknown.", "example": "SP" }, "checkInTime": { "type": "string", "nullable": true, "description": "Time of day, in the hotel's local time (`HH:mm`), from which guests can check in. `null` when unknown.", "example": "14:00" }, "checkOutTime": { "type": "string", "nullable": true, "description": "Time of day, in the hotel's local time (`HH:mm`), by which guests must check out. `null` when unknown.", "example": "12:00" } }, "required": [ "name", "chain", "shortAddress", "phoneNumbers", "locality", "administrativeArea", "checkInTime", "checkOutTime" ], "description": "Hotel where the stay is booked." }, "checkIn": { "type": "string", "description": "Check-in date (`YYYY-MM-DD`).", "example": "2026-11-02" }, "checkOut": { "type": "string", "description": "Check-out date (`YYYY-MM-DD`).", "example": "2026-11-04" }, "rooms": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the room, as the hotel offers it.", "example": "Standard Room, 1 Queen Bed" }, "fare": { "type": "object", "properties": { "currency": { "type": "string", "description": "Currency, as the ISO 4217 alphabetic code.", "example": "BRL" }, "originalAmount": { "type": "number", "description": "Fare before discounts and fees, in cents.", "example": 120000 }, "discountAmount": { "type": "number", "description": "Discount applied to the fare, in cents.", "example": 8000 }, "feeAmount": { "type": "number", "description": "Fees added to the fare, in cents.", "example": 0 }, "amount": { "type": "number", "description": "Total charged for the fare, in cents: `originalAmount` - `discountAmount` + `feeAmount`.", "example": 112000 }, "boardType": { "type": "string", "enum": [ "ONLY_ROOM", "BREAKFAST", "HALF_BOARD", "FULL_BOARD", "ALL_INCLUSIVE" ], "description": "Meals included in the fare.", "example": "BREAKFAST" }, "cancellationPolicies": { "type": "object", "properties": { "refundable": { "type": "boolean", "description": "Whether cancelling gives any money back.", "example": true }, "immediateFine": { "type": "boolean", "description": "Whether a fine applies to a cancellation made right after the booking.", "example": false }, "penalties": { "type": "array", "items": { "type": "object", "properties": { "from": { "type": "string", "description": "First day (`YYYY-MM-DD`) on which this tier applies.", "example": "2026-10-25" }, "currency": { "type": "string", "description": "Currency, as the ISO 4217 alphabetic code.", "example": "BRL" }, "fineAmount": { "type": "number", "nullable": true, "description": "Fine charged for cancelling from `from` onward, in cents. `null` when the amount is not available.", "example": 15000 } }, "required": [ "from", "currency", "fineAmount" ], "description": "One tier of a cancellation penalty schedule." }, "description": "Penalty tiers, each in effect from its own date. Empty when no scheduled penalty applies." } }, "required": [ "refundable", "immediateFine", "penalties" ], "description": "Cancellation rules of the fare." } }, "required": [ "currency", "originalAmount", "discountAmount", "feeAmount", "amount", "boardType", "cancellationPolicies" ], "description": "Fare of the room." }, "passengersId": { "type": "array", "items": { "type": "string", "example": "6710a3f2c9e77b0012a4d5e1" }, "description": "IDs of the passengers staying in this room — the trip's `passengers[]`.\n\n---\n\nExample: `[\"6710a3f2c9e77b0012a4d5e1\"]`" } }, "required": [ "name", "fare", "passengersId" ], "description": "A booked room." }, "description": "Rooms booked for the stay." }, "locators": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "Kind of reference, such as `PNR` for an airline's booking code.", "example": "PNR" }, "code": { "type": "string", "description": "The reference itself, as the supplier issued it.", "example": "ABC123" } }, "required": [ "type", "code" ], "description": "A reference that identifies the booking with the supplier, such as an airline's booking code." }, "description": "Booking references issued by the hotel. Empty until the reservation is confirmed." } }, "required": [ "hotel", "checkIn", "checkOut", "rooms", "locators" ], "description": "The booked hotel stay: the hotel, the dates, the rooms with their fares and guests (by ID), and the reservation locators. This is the shape of `productSnapshot` when the trip's `vertical` is `HOTEL`. Amounts are integers in cents.", "title": "Hotel trip" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "DIRECT", "CONNECTION", "ONE_STOP" ], "description": "Kind of trip: `DIRECT`, `CONNECTION` or `ONE_STOP`.", "example": "DIRECT" }, "origin": { "type": "object", "properties": { "locality": { "type": "string", "description": "City the station sits in.", "example": "São Paulo" }, "administrativeArea": { "type": "string", "description": "State, as its short code.", "example": "SP" }, "name": { "type": "string", "nullable": true, "description": "Official name of the station. `null` when unknown.", "example": "Terminal Rodoviário Tietê" }, "shortAddress": { "type": "string", "nullable": true, "description": "Readable single-line address of the station. `null` when unknown.", "example": "Av. Cruzeiro do Sul, 1800, São Paulo, SP, Brazil" }, "phoneNumbers": { "type": "array", "items": { "type": "string", "example": "551133336666" }, "description": "Contact phone numbers of the station, digits only. Empty when none is registered.\n\n---\n\nExample: `[\"551133336666\"]`" } }, "required": [ "locality", "administrativeArea", "name", "shortAddress", "phoneNumbers" ], "description": "Station the trip starts at." }, "destination": { "type": "object", "properties": { "locality": { "type": "string", "description": "City the station sits in.", "example": "São Paulo" }, "administrativeArea": { "type": "string", "description": "State, as its short code.", "example": "SP" }, "name": { "type": "string", "nullable": true, "description": "Official name of the station. `null` when unknown.", "example": "Terminal Rodoviário Tietê" }, "shortAddress": { "type": "string", "nullable": true, "description": "Readable single-line address of the station. `null` when unknown.", "example": "Av. Cruzeiro do Sul, 1800, São Paulo, SP, Brazil" }, "phoneNumbers": { "type": "array", "items": { "type": "string", "example": "551133336666" }, "description": "Contact phone numbers of the station, digits only. Empty when none is registered.\n\n---\n\nExample: `[\"551133336666\"]`" } }, "required": [ "locality", "administrativeArea", "name", "shortAddress", "phoneNumbers" ], "description": "Station the trip ends at.", "example": { "locality": "Rio de Janeiro", "administrativeArea": "RJ", "name": "Rodoviária Novo Rio", "shortAddress": "Av. Francisco Bicalho, 1, Rio de Janeiro, RJ, Brazil", "phoneNumbers": [ "552133338888" ] } }, "departureDate": { "type": "string", "description": "Departure date and time in the local time of the origin station, as `YYYY-MM-DDTHH:mm:ss` with no time zone.", "example": "2026-11-02T08:30:00" }, "arrivalDate": { "type": "string", "description": "Arrival date and time in the local time of the destination station, as `YYYY-MM-DDTHH:mm:ss` with no time zone.", "example": "2026-11-02T14:45:00" }, "company": { "type": "object", "properties": { "name": { "type": "string", "description": "Commercial name of the company.", "example": "Expresso Brasileiro" }, "logo": { "type": "string", "nullable": true, "description": "URL of the company's logo. `null` when there is none.", "example": "https://cdn.example.com/bus/expresso-brasileiro.png" } }, "required": [ "name", "logo" ], "description": "Company that operates the trip." }, "passengerId": { "type": "string", "description": "ID of the passenger travelling on this ticket — one of the trip's `passengers[]`. Omitted only if the passenger could not be matched to the trip's passengers.", "example": "6710a3f2c9e77b0012a4d5e1" }, "segments": { "type": "array", "items": { "type": "object", "properties": { "seatNumber": { "type": "number", "description": "Seat reserved on the segment.", "example": 12 }, "serviceClass": { "type": "string", "enum": [ "SLEEPER_BED", "BED", "SEMI_BED", "EXECUTIVE", "CONVENTIONAL", "UNDEFINED" ], "description": "Class of service booked for the segment.", "example": "EXECUTIVE" }, "origin": { "type": "object", "properties": { "locality": { "type": "string", "description": "City the station sits in.", "example": "São Paulo" }, "administrativeArea": { "type": "string", "description": "State, as its short code.", "example": "SP" }, "name": { "type": "string", "nullable": true, "description": "Official name of the station. `null` when unknown.", "example": "Terminal Rodoviário Tietê" }, "shortAddress": { "type": "string", "nullable": true, "description": "Readable single-line address of the station. `null` when unknown.", "example": "Av. Cruzeiro do Sul, 1800, São Paulo, SP, Brazil" }, "phoneNumbers": { "type": "array", "items": { "type": "string", "example": "551133336666" }, "description": "Contact phone numbers of the station, digits only. Empty when none is registered.\n\n---\n\nExample: `[\"551133336666\"]`" } }, "required": [ "locality", "administrativeArea", "name", "shortAddress", "phoneNumbers" ], "description": "Station the segment leaves from." }, "destination": { "type": "object", "properties": { "locality": { "type": "string", "description": "City the station sits in.", "example": "São Paulo" }, "administrativeArea": { "type": "string", "description": "State, as its short code.", "example": "SP" }, "name": { "type": "string", "nullable": true, "description": "Official name of the station. `null` when unknown.", "example": "Terminal Rodoviário Tietê" }, "shortAddress": { "type": "string", "nullable": true, "description": "Readable single-line address of the station. `null` when unknown.", "example": "Av. Cruzeiro do Sul, 1800, São Paulo, SP, Brazil" }, "phoneNumbers": { "type": "array", "items": { "type": "string", "example": "551133336666" }, "description": "Contact phone numbers of the station, digits only. Empty when none is registered.\n\n---\n\nExample: `[\"551133336666\"]`" } }, "required": [ "locality", "administrativeArea", "name", "shortAddress", "phoneNumbers" ], "description": "Station the segment arrives at.", "example": { "locality": "Rio de Janeiro", "administrativeArea": "RJ", "name": "Rodoviária Novo Rio", "shortAddress": "Av. Francisco Bicalho, 1, Rio de Janeiro, RJ, Brazil", "phoneNumbers": [ "552133338888" ] } }, "departureDate": { "type": "string", "description": "Departure date and time in the local time of the origin station, as `YYYY-MM-DDTHH:mm:ss` with no time zone.", "example": "2026-11-02T08:30:00" }, "arrivalDate": { "type": "string", "description": "Arrival date and time in the local time of the destination station, as `YYYY-MM-DDTHH:mm:ss` with no time zone.", "example": "2026-11-02T14:45:00" }, "duration": { "type": "string", "nullable": true, "description": "Duration of the leg, as `HH:mm`. `null` when not available.", "example": "06:15" }, "fare": { "type": "object", "properties": { "originalAmount": { "type": "number", "description": "Fare before discounts and fees, in cents.", "example": 18000 }, "discountAmount": { "type": "number", "description": "Discount applied to the fare, in cents.", "example": 1000 }, "feeAmount": { "type": "number", "description": "Fees added to the fare, in cents.", "example": 500 }, "amount": { "type": "number", "description": "Total charged for the fare, in cents: `originalAmount` - `discountAmount` + `feeAmount`.", "example": 17500 }, "currency": { "type": "string", "description": "Currency, as the ISO 4217 alphabetic code.", "example": "BRL" }, "cancellationPolicies": { "type": "object", "properties": { "refundable": { "type": "boolean", "description": "Whether cancelling gives any money back.", "example": true }, "immediateFine": { "type": "boolean", "description": "Whether a fine applies to a cancellation made right after the booking.", "example": false }, "penalties": { "type": "array", "items": { "type": "object", "properties": { "from": { "type": "string", "description": "First day (`YYYY-MM-DD`) on which this tier applies.", "example": "2026-10-25" }, "currency": { "type": "string", "description": "Currency, as the ISO 4217 alphabetic code.", "example": "BRL" }, "fineAmount": { "type": "number", "nullable": true, "description": "Fine charged for cancelling from `from` onward, in cents. `null` when the amount is not available.", "example": 15000 } }, "required": [ "from", "currency", "fineAmount" ], "description": "One tier of a cancellation penalty schedule." }, "description": "Penalty tiers, each in effect from its own date. Empty when no scheduled penalty applies." } }, "required": [ "refundable", "immediateFine", "penalties" ], "description": "Cancellation rules of the fare." } }, "required": [ "originalAmount", "discountAmount", "feeAmount", "amount", "currency", "cancellationPolicies" ], "description": "Fare of the segment." }, "company": { "type": "object", "properties": { "name": { "type": "string", "description": "Commercial name of the company.", "example": "Expresso Brasileiro" }, "logo": { "type": "string", "nullable": true, "description": "URL of the company's logo. `null` when there is none.", "example": "https://cdn.example.com/bus/expresso-brasileiro.png" } }, "required": [ "name", "logo" ], "description": "Operator running this leg." } }, "required": [ "seatNumber", "serviceClass", "origin", "destination", "departureDate", "arrivalDate", "duration", "fare", "company" ], "description": "One leg of the bus trip, with the seat booked on it." }, "description": "Segments of the trip, one per leg, each with its seat, fare and operator." }, "routeDirection": { "type": "string", "enum": [ "DEPARTURE", "RETURN" ], "description": "Whether this booking is the outbound trip (`DEPARTURE`) or the return trip (`RETURN`).", "example": "DEPARTURE" }, "boardingInfo": { "description": "Boarding pass and, per leg, platform and ticket codes. `null` until it is first collected, as the departure approaches.", "example": null, "type": "object", "properties": { "boardingPass": { "type": "string", "nullable": true, "description": "The boarding pass PDF, base64-encoded. `null` when not available yet.", "example": "JVBERi0xLjcK" }, "routes": { "type": "array", "items": { "type": "object", "properties": { "origin": { "type": "string", "description": "City the leg starts in.", "example": "São Paulo" }, "destination": { "type": "string", "description": "City the leg ends in.", "example": "Rio de Janeiro" }, "platform": { "type": "string", "nullable": true, "description": "Boarding platform at the origin station. `null` when not assigned or not applicable.", "example": "14" }, "departureDate": { "type": "string", "description": "Departure date and time in local time, as `YYYY-MM-DDTHH:mm:ss` with no time zone.", "example": "2026-11-02T08:30:00" }, "arrivalDate": { "type": "string", "description": "Arrival date and time in local time, as `YYYY-MM-DDTHH:mm:ss` with no time zone.", "example": "2026-11-02T14:45:00" }, "tickets": { "type": "array", "items": { "type": "object", "properties": { "passengerId": { "type": "string", "description": "ID of the passenger the ticket belongs to — one of the trip's `passengers[]`. Omitted only if the passenger could not be matched to the trip's passengers.", "example": "6710a3f2c9e77b0012a4d5e1" }, "locators": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "Kind of reference, such as `PNR` for an airline's booking code.", "example": "PNR" }, "code": { "type": "string", "description": "The reference itself, as the supplier issued it.", "example": "ABC123" } }, "required": [ "type", "code" ], "description": "A reference that identifies the booking with the supplier, such as an airline's booking code." }, "description": "Booking references of the ticket. Empty when none is available." }, "ticketCode": { "type": "string", "nullable": true, "description": "Code of the ticket. `null` when not available.", "example": "EB123456" }, "qrCode": { "type": "string", "nullable": true, "description": "The boarding QR code image, base64-encoded. `null` when not available.", "example": "iVBORw0KGgo=" }, "bpeNumber": { "type": "string", "nullable": true, "description": "Number of the electronic bus ticket (BP-e). `null` when not available.", "example": "35261112345678000190630010000123451000123456" } }, "required": [ "locators", "ticketCode", "qrCode", "bpeNumber" ], "description": "The boarding ticket of one passenger on one leg." }, "description": "Tickets of the leg, one per passenger." } }, "required": [ "origin", "destination", "platform", "departureDate", "arrivalDate", "tickets" ], "description": "The boarding details of one leg of the trip." }, "description": "Boarding details per leg. A connection has two legs; direct and one-stop trips have one." } }, "required": [ "boardingPass", "routes" ], "nullable": true } }, "required": [ "type", "origin", "destination", "departureDate", "arrivalDate", "company", "segments", "routeDirection", "boardingInfo" ], "description": "The booked bus trip of one passenger (by ID): stations, operator, the legs with their seats and fares, and boarding information. This is the shape of `productSnapshot` when the trip's `vertical` is `BUS`. Amounts are integers in cents.", "title": "Bus trip" }, { "type": "object", "properties": { "groupName": { "type": "string", "description": "Commercial group the vehicle belongs to, such as `ECONOMY` or `SUV`.", "example": "ECONOMY" }, "class": { "type": "string", "description": "Class of the vehicle within its group.", "example": "INTERMEDIATE" }, "name": { "type": "string", "description": "Name of the vehicle, as the rental company displays it.", "example": "Fiat Mobi" }, "sipp": { "type": "string", "description": "SIPP code that classifies the vehicle by size, doors, transmission and fuel.", "example": "ECMR" }, "rentalCompany": { "type": "object", "properties": { "code": { "type": "string", "description": "Code of the rental company.", "example": "LOC" }, "name": { "type": "string", "description": "Commercial name of the rental company.", "example": "Localiza" }, "logo": { "type": "string", "nullable": true, "description": "URL of the rental company's logo. `null` when the company has no registered logo.", "example": "https://cdn.example.com/rentals/localiza.svg" } }, "required": [ "code", "name", "logo" ], "description": "Rental company that holds the booking." }, "pickUpLocation": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the rental location.", "example": "Localiza Aeroporto Guarulhos (GRU)" }, "phoneNumbers": { "type": "array", "items": { "type": "string", "example": "551133337777" }, "description": "Contact phone numbers of the location, digits only. Empty when none is registered.\n\n---\n\nExample: `[\"551133337777\"]`" }, "shortAddress": { "type": "string", "nullable": true, "description": "Readable single-line address of the location. `null` when unknown.", "example": "Rod. Hélio Smidt, s/n, Guarulhos, SP, Brazil" }, "locality": { "type": "string", "nullable": true, "description": "City the location sits in. `null` when unknown.", "example": "Guarulhos" }, "administrativeArea": { "type": "string", "nullable": true, "description": "State, as its short code. `null` when unknown.", "example": "SP" } }, "required": [ "name", "phoneNumbers", "shortAddress", "locality", "administrativeArea" ], "description": "Where the vehicle is picked up." }, "dropOffLocation": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the rental location.", "example": "Localiza Aeroporto Guarulhos (GRU)" }, "phoneNumbers": { "type": "array", "items": { "type": "string", "example": "551133337777" }, "description": "Contact phone numbers of the location, digits only. Empty when none is registered.\n\n---\n\nExample: `[\"551133337777\"]`" }, "shortAddress": { "type": "string", "nullable": true, "description": "Readable single-line address of the location. `null` when unknown.", "example": "Rod. Hélio Smidt, s/n, Guarulhos, SP, Brazil" }, "locality": { "type": "string", "nullable": true, "description": "City the location sits in. `null` when unknown.", "example": "Guarulhos" }, "administrativeArea": { "type": "string", "nullable": true, "description": "State, as its short code. `null` when unknown.", "example": "SP" } }, "required": [ "name", "phoneNumbers", "shortAddress", "locality", "administrativeArea" ], "description": "Where the vehicle is dropped off." }, "pickUpDate": { "type": "string", "description": "Pick-up date and time in the local time of the pick-up location, as `YYYY-MM-DDTHH:mm:ss` with no time zone.", "example": "2026-11-02T10:00:00" }, "dropOffDate": { "type": "string", "description": "Drop-off date and time in the local time of the drop-off location, as `YYYY-MM-DDTHH:mm:ss` with no time zone.", "example": "2026-11-04T10:00:00" }, "rentals": { "type": "array", "items": { "type": "object", "properties": { "description": { "type": "string", "nullable": true, "description": "Readable description of the rental option. `null` when not provided.", "example": "Compact car, air conditioning, unlimited mileage" }, "fare": { "type": "object", "properties": { "originalAmount": { "type": "number", "description": "Fare before discounts and fees, in cents.", "example": 36000 }, "discountAmount": { "type": "number", "description": "Discount applied to the fare, in cents.", "example": 2000 }, "feeAmount": { "type": "number", "description": "Fees added to the fare, in cents.", "example": 0 }, "amount": { "type": "number", "description": "Total charged for the fare, in cents: `originalAmount` - `discountAmount` + `feeAmount`.", "example": 34000 }, "currency": { "type": "string", "description": "Currency, as the ISO 4217 alphabetic code.", "example": "BRL" }, "cancellationPolicies": { "type": "object", "properties": { "refundable": { "type": "boolean", "description": "Whether cancelling gives any money back.", "example": true }, "immediateFine": { "type": "boolean", "description": "Whether a fine applies to a cancellation made right after the booking.", "example": false }, "penalties": { "type": "array", "items": { "type": "object", "properties": { "from": { "type": "string", "nullable": true, "description": "First day (`YYYY-MM-DD`) on which this tier applies. `null` when the supplier gave no date.", "example": "2026-10-31" }, "currency": { "type": "string", "description": "Currency, as the ISO 4217 alphabetic code.", "example": "BRL" }, "fineAmount": { "type": "number", "nullable": true, "description": "Fine charged for cancelling from `from` onward, in cents. `null` when the amount is not available.", "example": 12000 } }, "required": [ "from", "currency", "fineAmount" ], "description": "One tier of the cancellation penalty schedule of a rental." }, "description": "Penalty tiers, each in effect from its own date. Empty when no scheduled penalty applies." } }, "required": [ "refundable", "immediateFine", "penalties" ], "description": "Cancellation rules of the fare." } }, "required": [ "originalAmount", "discountAmount", "feeAmount", "amount", "currency", "cancellationPolicies" ], "description": "Fare of the rental." }, "passengersId": { "type": "array", "items": { "type": "string", "example": "6710a3f2c9e77b0012a4d5e1" }, "description": "IDs of the passengers travelling on this rental — the trip's `passengers[]`. Empty when none was assigned.\n\n---\n\nExample: `[\"6710a3f2c9e77b0012a4d5e1\"]`" }, "locators": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "Kind of reference, such as `PNR` for an airline's booking code.", "example": "PNR" }, "code": { "type": "string", "description": "The reference itself, as the supplier issued it.", "example": "ABC123" } }, "required": [ "type", "code" ], "description": "A reference that identifies the booking with the supplier, such as an airline's booking code." }, "description": "Booking references of the rental with the rental company. Empty until the reservation is confirmed." } }, "required": [ "description", "fare", "passengersId", "locators" ], "description": "A booked rental." }, "description": "Rentals booked under this record." }, "locators": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "Kind of reference, such as `PNR` for an airline's booking code.", "example": "PNR" }, "code": { "type": "string", "description": "The reference itself, as the supplier issued it.", "example": "ABC123" } }, "required": [ "type", "code" ], "description": "A reference that identifies the booking with the supplier, such as an airline's booking code." }, "description": "Booking references of the reservation as a whole. Empty until the reservation is confirmed." } }, "required": [ "groupName", "class", "name", "sipp", "rentalCompany", "pickUpLocation", "dropOffLocation", "pickUpDate", "dropOffDate", "rentals", "locators" ], "description": "The booked vehicle rental: the vehicle, the rental company, the pick-up and drop-off places and dates, fares, passengers (by ID) and reservation locators. This is the shape of `productSnapshot` when the trip's `vertical` is `VEHICLE`. Amounts are integers in cents.", "title": "Vehicle trip" } ], "description": "The booked product: the itinerary, stay, ticket or rental as recorded by the travel provider — journeys and flights, the hotel and its rooms, the route and boarding information, the rental — with its fares, policies and booking locators. It does not repeat the trip's own fields (`state`, `status`, the amounts, the dates) and carries no identifier of the travel provider; passengers are referenced by their `id` in `passengers[]`. Its shape depends on `vertical`: a flight (`AIR`), a hotel stay (`HOTEL`), a bus ticket (`BUS`) or a vehicle rental (`VEHICLE`) — see the four schemas below. Omitted until the record is first fetched." }, "cancellation": { "type": "object", "properties": { "quoteId": { "type": "string", "description": "ID of the confirmed cancellation quote." }, "cancelType": { "type": "string", "enum": [ "CREDIT", "REFUND", "MANUAL_CANCEL", "VOID" ], "description": "Kind of cancellation: `VOID` for a trip not issued yet, `REFUND` or `CREDIT` for an issued one, `MANUAL_CANCEL` when the amounts are settled outside the system." }, "originalAmount": { "type": "number", "nullable": true, "description": "What the trip cost, in cents. Omitted when it couldn't be recorded; `null` for `MANUAL_CANCEL`." }, "remainingAmount": { "type": "number", "nullable": true, "description": "What is given back after the fine, in cents. Omitted when it couldn't be recorded; `null` for `MANUAL_CANCEL`." }, "fineAmount": { "type": "number", "nullable": true, "description": "Cancellation fine, in cents. Omitted when it couldn't be recorded; `null` for `MANUAL_CANCEL`." }, "currency": { "type": "string", "description": "Currency of the amounts, as the numeric ISO 4217 code (`986` is BRL)." }, "status": { "type": "string", "description": "Status of the quote when it was confirmed." }, "expiresAt": { "type": "string", "description": "When the quote would have expired.", "format": "date-time" }, "confirmedAt": { "type": "string", "description": "When the cancellation was confirmed.", "format": "date-time" }, "confirmedBy": { "type": "string", "description": "ID of the user who confirmed the cancellation. Omitted when a service did." } }, "required": [ "quoteId", "cancelType" ], "description": "The confirmed cancellation. Omitted until one is confirmed." }, "createdAt": { "type": "string", "description": "When the trip was created.", "example": "2026-10-01T13:45:12.000Z", "format": "date-time" }, "updatedAt": { "type": "string", "description": "When the trip last changed.", "example": "2026-10-01T13:46:03.000Z", "format": "date-time" } }, "required": [ "id", "realmId", "organizationId", "customFields", "vertical", "state", "status", "passengers" ], "description": "A trip: ONE booked product — a flight, a hotel stay, a bus ticket or a vehicle rental — for the organization's passengers, with its lifecycle. Booking several products means creating several trips." }, "examples": { "air-trip": { "summary": "Air trip", "value": { "id": "6711b4c0d8e1a30012b7c9f2", "realmId": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b", "organizationId": "c4bd3f21-dfbd-44e8-8055-68ba15bed410", "createdBy": "e3553bc1-5e20-4e17-b22a-a796fda0aa99", "customFields": { "cost-center": "CC-1020" }, "vertical": "AIR", "state": "RESERVED", "status": "RESERVED", "reservationExpiresAt": "2026-10-02T13:45:12.000Z", "originalAmount": 95000, "discountAmount": 3010, "feeAmount": 0, "totalAmount": 91990, "currency": "986", "passengers": [ { "id": "6710a3f2c9e77b0012a4d5e1", "userId": "e3553bc1-5e20-4e17-b22a-a796fda0aa99", "lead": true, "name": "Mariana Costa", "gender": "FEMALE", "birthDate": "1990-04-17" } ], "productSnapshot": { "journeys": [ { "id": "jour_V1StGXR8Z5jdHi6BmyT2k", "direction": "DEPARTURE", "origin": { "iata": "GRU", "name": "São Paulo/Guarulhos International Airport", "shortAddress": "Guarulhos, SP, Brazil", "locality": "Guarulhos", "administrativeArea": "SP", "phoneNumbers": [ "551133334444" ] }, "destination": { "iata": "SDU", "name": "Rio de Janeiro/Santos Dumont Airport", "shortAddress": "Rio de Janeiro, RJ, Brazil", "locality": "Rio de Janeiro", "administrativeArea": "RJ", "phoneNumbers": [ "552133339999" ] }, "departureDate": "2026-11-02T08:30:00", "arrivalDate": "2026-11-02T09:35:00", "duration": "01:05", "segments": [ { "airline": { "code": "LA", "name": "LATAM Airlines", "logo": "https://cdn.example.com/airlines/LA.png" }, "operation": { "code": "LA", "name": "LATAM Airlines", "logo": "https://cdn.example.com/airlines/LA.png" }, "origin": { "iata": "GRU", "name": "São Paulo/Guarulhos International Airport", "shortAddress": "Guarulhos, SP, Brazil", "locality": "Guarulhos", "administrativeArea": "SP", "phoneNumbers": [ "551133334444" ] }, "destination": { "iata": "SDU", "name": "Rio de Janeiro/Santos Dumont Airport", "shortAddress": "Rio de Janeiro, RJ, Brazil", "locality": "Rio de Janeiro", "administrativeArea": "RJ", "phoneNumbers": [ "552133339999" ] }, "flightNumber": "3101", "departureDate": "2026-11-02T08:30:00", "arrivalDate": "2026-11-02T09:35:00", "flightType": "REGULAR", "duration": "01:05", "equipment": "32Q", "cabin": "ECONOMY", "class": "Y", "fareBasis": "YOW", "flightInfo": null } ] } ], "tickets": [ { "passengerId": "6710a3f2c9e77b0012a4d5e1", "fareDescription": "GRU to SDU, LATAM Airlines, Economy", "ticketNumber": null, "fares": [ { "journeyId": "jour_V1StGXR8Z5jdHi6BmyT2k", "currency": "BRL", "originalAmount": 95000, "discountAmount": 3010, "feeAmount": 0, "amount": 91990, "cancellationPolicies": { "refundable": true, "immediateFine": false, "penalties": [ { "from": "2026-10-25", "currency": "BRL", "fineAmount": 15000 } ] }, "changePolicies": { "canChange": true, "immediateFine": false, "penalties": [ { "from": "2026-10-25", "currency": "BRL", "fineAmount": 8000 } ] } } ], "segments": [ { "flightNumber": "3101", "cabin": "ECONOMY", "class": "Y", "fareBasis": "YOW", "baggages": [ { "quantity": 1, "weight": 23, "type": "CHECKED" } ] } ] } ], "locators": [ { "type": "PNR", "code": "ABC123" } ], "flightInfoUpdatedAt": null }, "createdAt": "2026-10-01T13:45:12.000Z", "updatedAt": "2026-10-01T13:46:03.000Z" } }, "hotel-trip": { "summary": "Hotel trip", "value": { "id": "6711b4c0d8e1a30012b7c9f2", "realmId": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b", "organizationId": "c4bd3f21-dfbd-44e8-8055-68ba15bed410", "createdBy": "e3553bc1-5e20-4e17-b22a-a796fda0aa99", "customFields": { "cost-center": "CC-1020" }, "vertical": "HOTEL", "state": "RESERVED", "status": "RESERVED", "reservationExpiresAt": "2026-10-02T13:45:12.000Z", "originalAmount": 95000, "discountAmount": 3010, "feeAmount": 0, "totalAmount": 91990, "currency": "986", "passengers": [ { "id": "6710a3f2c9e77b0012a4d5e1", "userId": "e3553bc1-5e20-4e17-b22a-a796fda0aa99", "lead": true, "name": "Mariana Costa", "gender": "FEMALE", "birthDate": "1990-04-17" } ], "productSnapshot": { "hotel": { "name": "Hotel Paulista Plaza", "chain": { "brandName": "Ibis", "chainName": "Accor", "logo": "https://cdn.example.com/hotels/ibis.svg" }, "shortAddress": "Av. Paulista, 1500, São Paulo, SP, Brazil", "phoneNumbers": [ "551133335555" ], "locality": "São Paulo", "administrativeArea": "SP", "checkInTime": "14:00", "checkOutTime": "12:00" }, "checkIn": "2026-11-02", "checkOut": "2026-11-04", "rooms": [ { "name": "Standard Room, 1 Queen Bed", "fare": { "currency": "BRL", "originalAmount": 120000, "discountAmount": 8000, "feeAmount": 0, "amount": 112000, "boardType": "BREAKFAST", "cancellationPolicies": { "refundable": true, "immediateFine": false, "penalties": [ { "from": "2026-10-25", "currency": "BRL", "fineAmount": 15000 } ] } }, "passengersId": [ "6710a3f2c9e77b0012a4d5e1" ] } ], "locators": [ { "type": "PNR", "code": "ABC123" } ] }, "createdAt": "2026-10-01T13:45:12.000Z", "updatedAt": "2026-10-01T13:46:03.000Z" } }, "bus-trip": { "summary": "Bus trip", "value": { "id": "6711b4c0d8e1a30012b7c9f2", "realmId": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b", "organizationId": "c4bd3f21-dfbd-44e8-8055-68ba15bed410", "createdBy": "e3553bc1-5e20-4e17-b22a-a796fda0aa99", "customFields": { "cost-center": "CC-1020" }, "vertical": "BUS", "state": "RESERVED", "status": "RESERVED", "reservationExpiresAt": "2026-10-02T13:45:12.000Z", "originalAmount": 95000, "discountAmount": 3010, "feeAmount": 0, "totalAmount": 91990, "currency": "986", "passengers": [ { "id": "6710a3f2c9e77b0012a4d5e1", "userId": "e3553bc1-5e20-4e17-b22a-a796fda0aa99", "lead": true, "name": "Mariana Costa", "gender": "FEMALE", "birthDate": "1990-04-17" } ], "productSnapshot": { "type": "DIRECT", "origin": { "locality": "São Paulo", "administrativeArea": "SP", "name": "Terminal Rodoviário Tietê", "shortAddress": "Av. Cruzeiro do Sul, 1800, São Paulo, SP, Brazil", "phoneNumbers": [ "551133336666" ] }, "destination": { "locality": "Rio de Janeiro", "administrativeArea": "RJ", "name": "Rodoviária Novo Rio", "shortAddress": "Av. Francisco Bicalho, 1, Rio de Janeiro, RJ, Brazil", "phoneNumbers": [ "552133338888" ] }, "departureDate": "2026-11-02T08:30:00", "arrivalDate": "2026-11-02T14:45:00", "company": { "name": "Expresso Brasileiro", "logo": "https://cdn.example.com/bus/expresso-brasileiro.png" }, "passengerId": "6710a3f2c9e77b0012a4d5e1", "segments": [ { "seatNumber": 12, "serviceClass": "EXECUTIVE", "origin": { "locality": "São Paulo", "administrativeArea": "SP", "name": "Terminal Rodoviário Tietê", "shortAddress": "Av. Cruzeiro do Sul, 1800, São Paulo, SP, Brazil", "phoneNumbers": [ "551133336666" ] }, "destination": { "locality": "Rio de Janeiro", "administrativeArea": "RJ", "name": "Rodoviária Novo Rio", "shortAddress": "Av. Francisco Bicalho, 1, Rio de Janeiro, RJ, Brazil", "phoneNumbers": [ "552133338888" ] }, "departureDate": "2026-11-02T08:30:00", "arrivalDate": "2026-11-02T14:45:00", "duration": "06:15", "fare": { "originalAmount": 18000, "discountAmount": 1000, "feeAmount": 500, "amount": 17500, "currency": "BRL", "cancellationPolicies": { "refundable": true, "immediateFine": false, "penalties": [ { "from": "2026-10-25", "currency": "BRL", "fineAmount": 15000 } ] } }, "company": { "name": "Expresso Brasileiro", "logo": "https://cdn.example.com/bus/expresso-brasileiro.png" } } ], "routeDirection": "DEPARTURE", "boardingInfo": null }, "createdAt": "2026-10-01T13:45:12.000Z", "updatedAt": "2026-10-01T13:46:03.000Z" } }, "vehicle-trip": { "summary": "Vehicle trip", "value": { "id": "6711b4c0d8e1a30012b7c9f2", "realmId": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b", "organizationId": "c4bd3f21-dfbd-44e8-8055-68ba15bed410", "createdBy": "e3553bc1-5e20-4e17-b22a-a796fda0aa99", "customFields": { "cost-center": "CC-1020" }, "vertical": "VEHICLE", "state": "RESERVED", "status": "RESERVED", "reservationExpiresAt": "2026-10-02T13:45:12.000Z", "originalAmount": 95000, "discountAmount": 3010, "feeAmount": 0, "totalAmount": 91990, "currency": "986", "passengers": [ { "id": "6710a3f2c9e77b0012a4d5e1", "userId": "e3553bc1-5e20-4e17-b22a-a796fda0aa99", "lead": true, "name": "Mariana Costa", "gender": "FEMALE", "birthDate": "1990-04-17" } ], "productSnapshot": { "groupName": "ECONOMY", "class": "INTERMEDIATE", "name": "Fiat Mobi", "sipp": "ECMR", "rentalCompany": { "code": "LOC", "name": "Localiza", "logo": "https://cdn.example.com/rentals/localiza.svg" }, "pickUpLocation": { "name": "Localiza Aeroporto Guarulhos (GRU)", "phoneNumbers": [ "551133337777" ], "shortAddress": "Rod. Hélio Smidt, s/n, Guarulhos, SP, Brazil", "locality": "Guarulhos", "administrativeArea": "SP" }, "dropOffLocation": { "name": "Localiza Aeroporto Guarulhos (GRU)", "phoneNumbers": [ "551133337777" ], "shortAddress": "Rod. Hélio Smidt, s/n, Guarulhos, SP, Brazil", "locality": "Guarulhos", "administrativeArea": "SP" }, "pickUpDate": "2026-11-02T10:00:00", "dropOffDate": "2026-11-04T10:00:00", "rentals": [ { "description": "Compact car, air conditioning, unlimited mileage", "fare": { "originalAmount": 36000, "discountAmount": 2000, "feeAmount": 0, "amount": 34000, "currency": "BRL", "cancellationPolicies": { "refundable": true, "immediateFine": false, "penalties": [ { "from": "2026-10-31", "currency": "BRL", "fineAmount": 12000 } ] } }, "passengersId": [ "6710a3f2c9e77b0012a4d5e1" ], "locators": [ { "type": "PNR", "code": "ABC123" } ] } ], "locators": [ { "type": "PNR", "code": "ABC123" } ] }, "createdAt": "2026-10-01T13:45:12.000Z", "updatedAt": "2026-10-01T13:46:03.000Z" } } } } } }, "404": { "description": "`TRIP_NOT_FOUND` — No trip with this ID is visible to you in the organization: it doesn't exist, belongs to another organization, or you are neither an organization admin nor a passenger on it.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "TRIP_NOT_FOUND" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "TRAVEL" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b", "code": "TRIP_NOT_FOUND", "origin": "TRAVEL", "message": "Trip not found" } } } }, "422": { "description": "`BAD_REQUEST` — A path parameter is not a valid ID; `fields` lists each one.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "BAD_REQUEST" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "TRAVEL" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." }, "fields": { "type": "array", "description": "One entry per invalid request field (validation errors only).", "items": { "type": "object", "properties": { "field": { "type": "string", "description": "Path of the invalid field, e.g. `label` or `values[0].value`.", "example": "label" }, "message": { "type": "string", "description": "Why the field was rejected.", "example": "label is required" }, "code": { "type": "string", "description": "`_` — e.g. `LABEL_REQUIRED`, `TYPE_ONE_OF`, `VALUES_VALUE_TYPE_ERROR`.", "example": "LABEL_REQUIRED" }, "values": { "type": "array", "items": { "type": "string" }, "description": "The accepted values, when the field is an enumeration." } }, "required": [ "field", "message", "code" ] } } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "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": "organizationId", "message": "Invalid UUID", "code": "ORGANIZATIONID_UUID" } ] } } } } }, "x-p3-confidence": { "response": "generated:typed" } } }, "/realms/{realmId}/organizations/{organizationId}/trips/{tripId}/history": { "get": { "operationId": "getRealmsByRealmIdOrganizationsByOrganizationIdTripsByTripIdHistory", "summary": "List trip history", "tags": [ "Trips" ], "x-p3-sidebar-order": 6, "description": "Lists the changes of a trip's state and status, oldest first.", "x-mint": { "content": "The first entry is the booking being recorded. Each following one is a change, with how it was learned: `API` when a read or an action of yours found it, `WEBHOOK` when the travel provider reported it, `POLL` when a periodic check did. The trip is brought up to date with the provider before the answer, so a change the provider already made shows up as a fresh entry. Empty while the trip is still being created. Visible to an organization admin and to the users the trip carries, like the trip itself." }, "parameters": [ { "name": "realmId", "in": "path", "required": true, "description": "ID of your realm.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b" }, { "name": "organizationId", "in": "path", "required": true, "description": "ID of the organization the trip belongs to.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410" }, { "name": "tripId", "in": "path", "required": true, "description": "ID of the trip (24 hexadecimal characters).", "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$" }, "example": "6711b4c0d8e1a30012b7c9f2" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "PROCESSING_RESERVATION", "RESERVATION_FAILED", "RESERVED", "PROCESSING_ISSUE", "ISSUED", "PROCESSING_CANCELLATION", "CANCELED", "AWAITING_MANUAL_CANCELLATION", "CANCELLATION_FAILED", "FAILED", "FAILED_BY_INCONSISTENT_DATA", "FAILED_BY_UNAVAILABLE_RESOURCE", "FAILED_BY_BUDGET_EXCEEDED", "EXPIRED", "BLOCKED", "UNKNOWN", "ISSUANCE_FAILED" ], "description": "The status the trip changed to.", "example": "RESERVED" }, "state": { "type": "string", "enum": [ "PENDING", "RESERVED", "ISSUED", "CANCELED" ], "description": "The state the trip was in.", "example": "RESERVED" }, "at": { "type": "string", "description": "When the change was recorded.", "example": "2026-10-01T13:46:03.000Z", "format": "date-time" }, "source": { "type": "string", "enum": [ "WEBHOOK", "POLL", "API" ], "description": "How the change was learned: `API` when you or the system read or acted on the trip, `WEBHOOK` when the travel provider reported it, `POLL` when a periodic check found it.", "example": "API" } }, "required": [ "status", "state", "at", "source" ], "description": "One change of a trip's state or status." }, "description": "Changes in chronological order, the oldest first." } }, "required": [ "items" ], "description": "The history of a trip." } } } }, "404": { "description": "`TRIP_NOT_FOUND` — No trip with this ID is visible to you in the organization: it doesn't exist, belongs to another organization, or you are neither an organization admin nor a passenger on it.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "TRIP_NOT_FOUND" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "TRAVEL" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b", "code": "TRIP_NOT_FOUND", "origin": "TRAVEL", "message": "Trip not found" } } } }, "422": { "description": "`BAD_REQUEST` — A path parameter is not a valid ID; `fields` lists each one.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "BAD_REQUEST" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "TRAVEL" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." }, "fields": { "type": "array", "description": "One entry per invalid request field (validation errors only).", "items": { "type": "object", "properties": { "field": { "type": "string", "description": "Path of the invalid field, e.g. `label` or `values[0].value`.", "example": "label" }, "message": { "type": "string", "description": "Why the field was rejected.", "example": "label is required" }, "code": { "type": "string", "description": "`_` — e.g. `LABEL_REQUIRED`, `TYPE_ONE_OF`, `VALUES_VALUE_TYPE_ERROR`.", "example": "LABEL_REQUIRED" }, "values": { "type": "array", "items": { "type": "string" }, "description": "The accepted values, when the field is an enumeration." } }, "required": [ "field", "message", "code" ] } } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "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": "organizationId", "message": "Invalid UUID", "code": "ORGANIZATIONID_UUID" } ] } } } } }, "x-p3-confidence": { "response": "generated:typed" } } }, "/realms/{realmId}/organizations/{organizationId}/trips/{tripId}/issue": { "post": { "operationId": "postRealmsByRealmIdOrganizationsByOrganizationIdTripsByTripIdIssue", "summary": "Issue a trip", "tags": [ "Trips" ], "x-p3-sidebar-order": 7, "description": "Issues a reserved trip: the ticket, voucher or rental is emitted.", "x-mint": { "content": "Issuing is asynchronous: the answer is `202 Accepted` with the trip in `PROCESSING_ISSUE`. Read the trip, or its history, to see it become `ISSUED`. Only a trip whose `status` is `RESERVED` can be issued. Issue it before its `reservationExpiresAt`, when the hold ends. Visible to an organization admin and to the users the trip carries, like the trip itself." }, "parameters": [ { "name": "realmId", "in": "path", "required": true, "description": "ID of your realm.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b" }, { "name": "organizationId", "in": "path", "required": true, "description": "ID of the organization the trip belongs to.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410" }, { "name": "tripId", "in": "path", "required": true, "description": "ID of the trip (24 hexadecimal characters).", "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$" }, "example": "6711b4c0d8e1a30012b7c9f2" } ], "responses": { "202": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the trip.", "example": "6711b4c0d8e1a30012b7c9f2" }, "realmId": { "type": "string", "description": "ID of the realm the trip belongs to.", "example": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b", "format": "uuid" }, "organizationId": { "type": "string", "description": "ID of the organization the trip belongs to.", "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410", "format": "uuid" }, "createdBy": { "type": "string", "description": "ID of the user who created the trip. Omitted when a service did.", "example": "e3553bc1-5e20-4e17-b22a-a796fda0aa99", "format": "uuid" }, "customFields": { "type": "object", "additionalProperties": {}, "description": "Values of the organization's trip custom fields, keyed by the custom field's `slug`. Empty when none were set.\n\n---\n\nExample: `{\"cost-center\":\"CC-1020\"}`", "example": { "cost-center": "CC-1020" } }, "vertical": { "type": "string", "enum": [ "AIR", "HOTEL", "BUS", "VEHICLE" ], "description": "Type of product booked. It tells which shape `productSnapshot` has.", "example": "AIR" }, "state": { "type": "string", "enum": [ "PENDING", "RESERVED", "ISSUED", "CANCELED" ], "description": "Where the booking is in its life: `PENDING` while the reservation is being made, `RESERVED` once held (until `reservationExpiresAt`), `ISSUED` once ticketed and `CANCELED`. It only moves forward.", "example": "RESERVED" }, "status": { "type": "string", "enum": [ "PROCESSING_RESERVATION", "RESERVATION_FAILED", "RESERVED", "PROCESSING_ISSUE", "ISSUED", "PROCESSING_CANCELLATION", "CANCELED", "AWAITING_MANUAL_CANCELLATION", "CANCELLATION_FAILED", "FAILED", "FAILED_BY_INCONSISTENT_DATA", "FAILED_BY_UNAVAILABLE_RESOURCE", "FAILED_BY_BUDGET_EXCEEDED", "EXPIRED", "BLOCKED", "UNKNOWN", "ISSUANCE_FAILED" ], "description": "Finer-grained status: it also reports work in progress (`PROCESSING_*`) and failures, and can change back and forth. Use `state` to decide what the booking is; use `status` to tell what is happening to it.", "example": "RESERVED" }, "reservationExpiresAt": { "type": "string", "nullable": true, "description": "Until when the reservation is held. Past it, a trip that was not issued expires. `null` or omitted when there is no hold.", "example": "2026-10-02T13:45:12.000Z", "format": "date-time" }, "issuedAt": { "type": "string", "nullable": true, "description": "When the trip was issued. `null` or omitted until it is.", "format": "date-time" }, "originalAmount": { "type": "number", "description": "Price before discounts, in cents. Omitted until the price is known.", "example": 95000 }, "discountAmount": { "type": "number", "description": "Discount applied, in cents. Omitted until the price is known.", "example": 3010 }, "feeAmount": { "type": "number", "description": "Fees added, in cents. Omitted until the price is known.", "example": 0 }, "totalAmount": { "type": "number", "description": "Amount to pay, in cents: `originalAmount` - `discountAmount` + `feeAmount`. Omitted until the price is known.", "example": 91990 }, "currency": { "type": "string", "description": "Currency of the amounts, as the numeric ISO 4217 code (`986` is BRL).", "example": "986" }, "passengers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the passenger, as returned by the passenger endpoints.", "example": "6710a3f2c9e77b0012a4d5e1" }, "userId": { "type": "string", "description": "ID of the organization user the passenger is linked to. Omitted for a passenger who is not a user. A user sees the trips they travel on.", "example": "e3553bc1-5e20-4e17-b22a-a796fda0aa99", "format": "uuid" }, "lead": { "type": "boolean", "description": "Whether this passenger is the one responsible for the reservation.", "example": true }, "name": { "type": "string", "description": "Full name, as it appears on the passenger's travel documents.", "example": "Mariana Costa" }, "gender": { "type": "string", "enum": [ "MALE", "FEMALE" ], "description": "Gender.", "example": "FEMALE" }, "birthDate": { "type": "string", "description": "Date of birth (`YYYY-MM-DD`).", "example": "1990-04-17" } }, "required": [ "id", "lead", "name", "gender", "birthDate" ], "description": "A passenger of a trip: who travels, as recorded when the trip was booked. The passenger endpoints serve the full profile." }, "description": "The passengers booked on the trip." }, "productSnapshot": { "anyOf": [ { "type": "object", "properties": { "journeys": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the journey, referenced by `tickets[].fares[].journeyId`.", "example": "jour_V1StGXR8Z5jdHi6BmyT2k" }, "direction": { "type": "string", "enum": [ "DEPARTURE", "RETURN" ], "description": "Whether this is the outbound leg (`DEPARTURE`) or the return leg (`RETURN`).", "example": "DEPARTURE" }, "origin": { "type": "object", "properties": { "iata": { "type": "string", "description": "IATA code of the airport, 3 letters.", "example": "GRU" }, "name": { "type": "string", "nullable": true, "description": "Official name of the airport. `null` when unknown.", "example": "São Paulo/Guarulhos International Airport" }, "shortAddress": { "type": "string", "nullable": true, "description": "Readable single-line address of the airport. `null` when unknown.", "example": "Guarulhos, SP, Brazil" }, "locality": { "type": "string", "nullable": true, "description": "City the airport sits in. `null` when unknown.", "example": "Guarulhos" }, "administrativeArea": { "type": "string", "nullable": true, "description": "State, as its short code. `null` when unknown.", "example": "SP" }, "phoneNumbers": { "type": "array", "items": { "type": "string", "example": "551133334444" }, "description": "Contact phone numbers of the airport, digits only. Empty when none is registered.\n\n---\n\nExample: `[\"551133334444\"]`" } }, "required": [ "iata", "name", "shortAddress", "locality", "administrativeArea", "phoneNumbers" ], "description": "Airport the journey starts at." }, "destination": { "type": "object", "properties": { "iata": { "type": "string", "description": "IATA code of the airport, 3 letters.", "example": "GRU" }, "name": { "type": "string", "nullable": true, "description": "Official name of the airport. `null` when unknown.", "example": "São Paulo/Guarulhos International Airport" }, "shortAddress": { "type": "string", "nullable": true, "description": "Readable single-line address of the airport. `null` when unknown.", "example": "Guarulhos, SP, Brazil" }, "locality": { "type": "string", "nullable": true, "description": "City the airport sits in. `null` when unknown.", "example": "Guarulhos" }, "administrativeArea": { "type": "string", "nullable": true, "description": "State, as its short code. `null` when unknown.", "example": "SP" }, "phoneNumbers": { "type": "array", "items": { "type": "string", "example": "551133334444" }, "description": "Contact phone numbers of the airport, digits only. Empty when none is registered.\n\n---\n\nExample: `[\"551133334444\"]`" } }, "required": [ "iata", "name", "shortAddress", "locality", "administrativeArea", "phoneNumbers" ], "description": "Airport the journey ends at.", "example": { "iata": "SDU", "name": "Rio de Janeiro/Santos Dumont Airport", "shortAddress": "Rio de Janeiro, RJ, Brazil", "locality": "Rio de Janeiro", "administrativeArea": "RJ", "phoneNumbers": [ "552133339999" ] } }, "departureDate": { "type": "string", "description": "Departure date and time in the local time of the origin airport, as `YYYY-MM-DDTHH:mm:ss` with no time zone.", "example": "2026-11-02T08:30:00" }, "arrivalDate": { "type": "string", "description": "Arrival date and time in the local time of the destination airport, as `YYYY-MM-DDTHH:mm:ss` with no time zone.", "example": "2026-11-02T09:35:00" }, "duration": { "type": "string", "description": "Total travel time of the journey, connections included, as `HH:mm`.", "example": "01:05" }, "segments": { "type": "array", "items": { "type": "object", "properties": { "airline": { "type": "object", "properties": { "code": { "type": "string", "description": "IATA code of the airline.", "example": "LA" }, "name": { "type": "string", "nullable": true, "description": "Commercial name of the airline. `null` when unknown.", "example": "LATAM Airlines" }, "logo": { "type": "string", "nullable": true, "description": "URL of the airline's logo. `null` when there is none.", "example": "https://cdn.example.com/airlines/LA.png" } }, "required": [ "code", "name", "logo" ], "description": "Airline that sells the flight." }, "operation": { "type": "object", "properties": { "code": { "type": "string", "description": "IATA code of the airline.", "example": "LA" }, "name": { "type": "string", "nullable": true, "description": "Commercial name of the airline. `null` when unknown.", "example": "LATAM Airlines" }, "logo": { "type": "string", "nullable": true, "description": "URL of the airline's logo. `null` when there is none.", "example": "https://cdn.example.com/airlines/LA.png" } }, "required": [ "code", "name", "logo" ], "description": "Airline that operates the flight. It differs from `airline` on codeshare flights." }, "origin": { "type": "object", "properties": { "iata": { "type": "string", "description": "IATA code of the airport, 3 letters.", "example": "GRU" }, "name": { "type": "string", "nullable": true, "description": "Official name of the airport. `null` when unknown.", "example": "São Paulo/Guarulhos International Airport" }, "shortAddress": { "type": "string", "nullable": true, "description": "Readable single-line address of the airport. `null` when unknown.", "example": "Guarulhos, SP, Brazil" }, "locality": { "type": "string", "nullable": true, "description": "City the airport sits in. `null` when unknown.", "example": "Guarulhos" }, "administrativeArea": { "type": "string", "nullable": true, "description": "State, as its short code. `null` when unknown.", "example": "SP" }, "phoneNumbers": { "type": "array", "items": { "type": "string", "example": "551133334444" }, "description": "Contact phone numbers of the airport, digits only. Empty when none is registered.\n\n---\n\nExample: `[\"551133334444\"]`" } }, "required": [ "iata", "name", "shortAddress", "locality", "administrativeArea", "phoneNumbers" ], "description": "Airport the flight leaves from." }, "destination": { "type": "object", "properties": { "iata": { "type": "string", "description": "IATA code of the airport, 3 letters.", "example": "GRU" }, "name": { "type": "string", "nullable": true, "description": "Official name of the airport. `null` when unknown.", "example": "São Paulo/Guarulhos International Airport" }, "shortAddress": { "type": "string", "nullable": true, "description": "Readable single-line address of the airport. `null` when unknown.", "example": "Guarulhos, SP, Brazil" }, "locality": { "type": "string", "nullable": true, "description": "City the airport sits in. `null` when unknown.", "example": "Guarulhos" }, "administrativeArea": { "type": "string", "nullable": true, "description": "State, as its short code. `null` when unknown.", "example": "SP" }, "phoneNumbers": { "type": "array", "items": { "type": "string", "example": "551133334444" }, "description": "Contact phone numbers of the airport, digits only. Empty when none is registered.\n\n---\n\nExample: `[\"551133334444\"]`" } }, "required": [ "iata", "name", "shortAddress", "locality", "administrativeArea", "phoneNumbers" ], "description": "Airport the flight arrives at.", "example": { "iata": "SDU", "name": "Rio de Janeiro/Santos Dumont Airport", "shortAddress": "Rio de Janeiro, RJ, Brazil", "locality": "Rio de Janeiro", "administrativeArea": "RJ", "phoneNumbers": [ "552133339999" ] } }, "flightNumber": { "type": "string", "description": "Number of the flight, without the airline's code.", "example": "3101" }, "departureDate": { "type": "string", "description": "Departure date and time in the local time of the departure airport, as `YYYY-MM-DDTHH:mm:ss` with no time zone.", "example": "2026-11-02T08:30:00" }, "arrivalDate": { "type": "string", "description": "Arrival date and time in the local time of the arrival airport, as `YYYY-MM-DDTHH:mm:ss` with no time zone.", "example": "2026-11-02T09:35:00" }, "flightType": { "type": "string", "enum": [ "CHARTER", "ALLOTMENT", "REGULAR" ], "description": "Kind of flight: `REGULAR`, `CHARTER` or `ALLOTMENT`.", "example": "REGULAR" }, "duration": { "type": "string", "description": "Duration of the flight, as `HH:mm`.", "example": "01:05" }, "equipment": { "type": "string", "nullable": true, "description": "Aircraft scheduled for the flight, as the airline identifies it. `null` when not informed.", "example": "32Q" }, "cabin": { "type": "string", "enum": [ "ECONOMY", "PREMIUM_ECONOMY", "BUSINESS", "FIRST_CLASS", "UNDEFINED" ], "description": "Cabin booked for the flight.", "example": "ECONOMY" }, "class": { "type": "string", "nullable": true, "description": "Booking class (RBD) priced for the flight. Each airline defines its own codes. `null` when the airline does not expose it.", "example": "Y" }, "fareBasis": { "type": "string", "nullable": true, "description": "Fare basis code priced for the flight. Each airline defines its own codes. `null` when the airline does not expose it.", "example": "YOW" }, "flightInfo": { "description": "Live information about the flight. `null` until it is first collected, as the departure approaches.", "example": null, "type": "object", "properties": { "state": { "type": "string", "nullable": true, "enum": [ "SCHEDULED", "OUT_GATE", "IN_AIR", "LANDED", "IN_GATE", "CANCELED", "PROPOSED", "UNKNOWN", null ], "description": "Operational state of the flight. `null` when there is no live status yet.", "example": "SCHEDULED" }, "updatedAt": { "type": "string", "nullable": true, "description": "When the live status was captured. `null` when there is no live status yet.", "example": "2026-11-01T18:00:00.000Z" }, "aircraft": { "description": "Aircraft operating the flight. `null` when not known yet.", "type": "object", "properties": { "registration": { "type": "string", "nullable": true, "description": "Tail registration of the aircraft. `null` when not known yet.", "example": "PR-XBA" }, "type": { "type": "string", "nullable": true, "description": "ICAO code of the aircraft type. `null` when not known yet.", "example": "A21N" } }, "required": [ "registration", "type" ], "nullable": true }, "departure": { "type": "object", "properties": { "terminal": { "type": "string", "nullable": true, "description": "Terminal at the airport. `null` when not reported yet.", "example": "2" }, "gate": { "type": "string", "nullable": true, "description": "Gate at the airport. `null` when not reported yet.", "example": "B12" }, "baggage": { "type": "string", "nullable": true, "description": "Baggage belt, reported for arrivals only. `null` for departures and when not reported yet.", "example": "04" }, "estimatedTime": { "type": "string", "nullable": true, "description": "Estimated time at the gate, in UTC (ISO 8601). `null` when not known yet.", "example": "2026-11-02T11:30:00.000Z" }, "actualTime": { "type": "string", "nullable": true, "description": "Actual time at the gate, in UTC (ISO 8601), reported once the flight operates. `null` before that.", "example": "2026-11-02T11:34:00.000Z" }, "timeliness": { "type": "string", "nullable": true, "description": "Punctuality of the flight, such as `OnTime`, `Early` or `Delayed`. `null` when not known.", "example": "OnTime" }, "delayMinutes": { "type": "number", "nullable": true, "description": "Delay in minutes; negative when the flight is ahead of schedule. `null` when not known.", "example": 4 } }, "required": [ "terminal", "gate", "baggage", "estimatedTime", "actualTime", "timeliness", "delayMinutes" ], "description": "Live status at the departure airport." }, "arrival": { "type": "object", "properties": { "terminal": { "type": "string", "nullable": true, "description": "Terminal at the airport. `null` when not reported yet.", "example": "2" }, "gate": { "type": "string", "nullable": true, "description": "Gate at the airport. `null` when not reported yet.", "example": "B12" }, "baggage": { "type": "string", "nullable": true, "description": "Baggage belt, reported for arrivals only. `null` for departures and when not reported yet.", "example": "04" }, "estimatedTime": { "type": "string", "nullable": true, "description": "Estimated time at the gate, in UTC (ISO 8601). `null` when not known yet.", "example": "2026-11-02T11:30:00.000Z" }, "actualTime": { "type": "string", "nullable": true, "description": "Actual time at the gate, in UTC (ISO 8601), reported once the flight operates. `null` before that.", "example": "2026-11-02T11:34:00.000Z" }, "timeliness": { "type": "string", "nullable": true, "description": "Punctuality of the flight, such as `OnTime`, `Early` or `Delayed`. `null` when not known.", "example": "OnTime" }, "delayMinutes": { "type": "number", "nullable": true, "description": "Delay in minutes; negative when the flight is ahead of schedule. `null` when not known.", "example": 4 } }, "required": [ "terminal", "gate", "baggage", "estimatedTime", "actualTime", "timeliness", "delayMinutes" ], "description": "Live status at the arrival airport." } }, "required": [ "state", "updatedAt", "aircraft", "departure", "arrival" ], "nullable": true } }, "required": [ "airline", "operation", "origin", "destination", "flightNumber", "departureDate", "arrivalDate", "flightType", "duration", "equipment", "cabin", "class", "fareBasis", "flightInfo" ], "description": "One flight of a journey. A journey with connections has several." }, "description": "Flights of the journey, in chronological order, connections included." } }, "required": [ "id", "direction", "origin", "destination", "departureDate", "arrivalDate", "duration", "segments" ], "description": "One leg of the itinerary: the whole way from an origin to a destination, connections included." }, "description": "Legs of the itinerary, in travel order: one for a one-way trip, two (outbound and return) for a round trip." }, "tickets": { "type": "array", "items": { "type": "object", "properties": { "passengerId": { "type": "string", "description": "ID of the passenger holding this ticket — one of the trip's `passengers[]`. Omitted only if the passenger could not be matched to the trip's passengers.", "example": "6710a3f2c9e77b0012a4d5e1" }, "fareDescription": { "type": "string", "description": "Readable description of the fare of the ticket.", "example": "GRU to SDU, LATAM Airlines, Economy" }, "ticketNumber": { "type": "string", "nullable": true, "description": "Number of the ticket, as the airline issued it. `null` until the ticket is issued.", "example": null }, "fares": { "type": "array", "items": { "type": "object", "properties": { "journeyId": { "type": "string", "nullable": true, "description": "ID of the journey this fare covers — a `journeys[].id`. `null` when the fare covers the whole itinerary.", "example": "jour_V1StGXR8Z5jdHi6BmyT2k" }, "currency": { "type": "string", "description": "Currency, as the ISO 4217 alphabetic code.", "example": "BRL" }, "originalAmount": { "type": "number", "description": "Fare before discounts and fees, in cents.", "example": 95000 }, "discountAmount": { "type": "number", "description": "Discount applied to the fare, in cents.", "example": 3010 }, "feeAmount": { "type": "number", "description": "Fees added to the fare, in cents.", "example": 0 }, "amount": { "type": "number", "description": "Total charged for the fare, in cents: `originalAmount` - `discountAmount` + `feeAmount`.", "example": 91990 }, "cancellationPolicies": { "type": "object", "properties": { "refundable": { "type": "boolean", "description": "Whether cancelling gives any money back.", "example": true }, "immediateFine": { "type": "boolean", "description": "Whether a fine applies to a cancellation made right after the booking.", "example": false }, "penalties": { "type": "array", "items": { "type": "object", "properties": { "from": { "type": "string", "description": "First day (`YYYY-MM-DD`) on which this tier applies.", "example": "2026-10-25" }, "currency": { "type": "string", "description": "Currency, as the ISO 4217 alphabetic code.", "example": "BRL" }, "fineAmount": { "type": "number", "nullable": true, "description": "Fine charged for cancelling from `from` onward, in cents. `null` when the amount is not available.", "example": 15000 } }, "required": [ "from", "currency", "fineAmount" ], "description": "One tier of a cancellation penalty schedule." }, "description": "Penalty tiers, each in effect from its own date. Empty when no scheduled penalty applies." } }, "required": [ "refundable", "immediateFine", "penalties" ], "description": "Cancellation rules of the fare." }, "changePolicies": { "type": "object", "properties": { "canChange": { "type": "boolean", "description": "Whether the fare allows the booking to be changed.", "example": true }, "immediateFine": { "type": "boolean", "description": "Whether a fine applies to a change made right after the booking.", "example": false }, "penalties": { "type": "array", "items": { "type": "object", "properties": { "from": { "type": "string", "description": "First day (`YYYY-MM-DD`) on which this tier applies.", "example": "2026-10-25" }, "currency": { "type": "string", "description": "Currency, as the ISO 4217 alphabetic code.", "example": "BRL" }, "fineAmount": { "type": "number", "nullable": true, "description": "Fine charged for changing the booking from `from` onward, in cents. `null` when the amount is not available.", "example": 8000 } }, "required": [ "from", "currency", "fineAmount" ], "description": "One tier of a change penalty schedule." }, "description": "Penalty tiers, each in effect from its own date. Empty when no scheduled penalty applies." } }, "required": [ "canChange", "immediateFine", "penalties" ], "description": "Change rules of the fare." } }, "required": [ "journeyId", "currency", "originalAmount", "discountAmount", "feeAmount", "amount", "cancellationPolicies", "changePolicies" ], "description": "The fare of a ticket for one journey, or for the whole itinerary. Amounts are integers in cents." }, "description": "Fares of the ticket: one per journey, or a single one for the whole itinerary." }, "segments": { "type": "array", "items": { "type": "object", "properties": { "flightNumber": { "type": "string", "description": "Number of the flight this ticket covers, without the airline's code. It matches the `flightNumber` of one of the journeys' `segments`.", "example": "3101" }, "cabin": { "type": "string", "enum": [ "ECONOMY", "PREMIUM_ECONOMY", "BUSINESS", "FIRST_CLASS", "UNDEFINED" ], "description": "Cabin of the ticket on this flight.", "example": "ECONOMY" }, "class": { "type": "string", "nullable": true, "description": "Booking class (RBD) of the ticket on this flight. Each airline defines its own codes. `null` when the airline does not expose it.", "example": "Y" }, "fareBasis": { "type": "string", "nullable": true, "description": "Fare basis code of the ticket on this flight. Each airline defines its own codes. `null` when the airline does not expose it.", "example": "YOW" }, "baggages": { "type": "array", "items": { "type": "object", "properties": { "quantity": { "type": "number", "description": "Number of pieces included in the allowance.", "example": 1 }, "weight": { "type": "number", "nullable": true, "description": "Weight allowed per piece, in kg. `null` when the airline sets no weight limit per piece.", "example": 23 }, "type": { "type": "string", "enum": [ "CHECKED", "CARRY_ON", "PERSONAL_ITEM" ], "description": "Kind of baggage: `CHECKED`, `CARRY_ON` or `PERSONAL_ITEM`.", "example": "CHECKED" } }, "required": [ "quantity", "weight", "type" ], "description": "A baggage allowance of a ticket on one flight." }, "description": "Baggage allowance of the ticket on this flight. Empty for an infant on an adult's lap." } }, "required": [ "flightNumber", "cabin", "class", "fareBasis", "baggages" ], "description": "What a ticket covers on one flight of the itinerary: the cabin, the fare codes and the baggage allowance." }, "description": "What the ticket covers on each flight of the itinerary." } }, "required": [ "fareDescription", "ticketNumber", "fares", "segments" ], "description": "The ticket of one passenger. It covers the whole itinerary, with a fare per journey or a single fare for all of it." }, "description": "Tickets of the booking, one per passenger, each covering the whole itinerary." }, "locators": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "Kind of reference, such as `PNR` for an airline's booking code.", "example": "PNR" }, "code": { "type": "string", "description": "The reference itself, as the supplier issued it.", "example": "ABC123" } }, "required": [ "type", "code" ], "description": "A reference that identifies the booking with the supplier, such as an airline's booking code." }, "description": "Booking references issued by the airlines. Empty until the reservation is confirmed." }, "flightInfoUpdatedAt": { "type": "string", "nullable": true, "description": "When the live flight information was last collected. `null` until it is first collected.", "example": null, "format": "date-time" } }, "required": [ "journeys", "tickets", "locators", "flightInfoUpdatedAt" ], "description": "The booked flight: itinerary, the ticket of each passenger (by ID) with its fares and baggage, and reservation locators. This is the shape of `productSnapshot` when the trip's `vertical` is `AIR`. Amounts are integers in cents.", "title": "Air trip" }, { "type": "object", "properties": { "hotel": { "type": "object", "properties": { "name": { "type": "string", "description": "Official name of the hotel.", "example": "Hotel Paulista Plaza" }, "chain": { "type": "object", "properties": { "brandName": { "type": "string", "nullable": true, "description": "Brand within the chain. `null` when not informed.", "example": "Ibis" }, "chainName": { "type": "string", "nullable": true, "description": "Name of the chain. `null` for an independent hotel.", "example": "Accor" }, "logo": { "type": "string", "nullable": true, "description": "URL of the chain's logo. `null` when the hotel has no chain with a registered logo.", "example": "https://cdn.example.com/hotels/ibis.svg" } }, "required": [ "brandName", "chainName", "logo" ], "description": "Chain and brand of the hotel." }, "shortAddress": { "type": "string", "nullable": true, "description": "Readable single-line address of the hotel. `null` when unknown.", "example": "Av. Paulista, 1500, São Paulo, SP, Brazil" }, "phoneNumbers": { "type": "array", "items": { "type": "string", "example": "551133335555" }, "description": "Contact phone numbers of the hotel, digits only. Empty when none is registered.\n\n---\n\nExample: `[\"551133335555\"]`" }, "locality": { "type": "string", "nullable": true, "description": "City the hotel sits in. `null` when unknown.", "example": "São Paulo" }, "administrativeArea": { "type": "string", "nullable": true, "description": "State, as its short code. `null` when unknown.", "example": "SP" }, "checkInTime": { "type": "string", "nullable": true, "description": "Time of day, in the hotel's local time (`HH:mm`), from which guests can check in. `null` when unknown.", "example": "14:00" }, "checkOutTime": { "type": "string", "nullable": true, "description": "Time of day, in the hotel's local time (`HH:mm`), by which guests must check out. `null` when unknown.", "example": "12:00" } }, "required": [ "name", "chain", "shortAddress", "phoneNumbers", "locality", "administrativeArea", "checkInTime", "checkOutTime" ], "description": "Hotel where the stay is booked." }, "checkIn": { "type": "string", "description": "Check-in date (`YYYY-MM-DD`).", "example": "2026-11-02" }, "checkOut": { "type": "string", "description": "Check-out date (`YYYY-MM-DD`).", "example": "2026-11-04" }, "rooms": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the room, as the hotel offers it.", "example": "Standard Room, 1 Queen Bed" }, "fare": { "type": "object", "properties": { "currency": { "type": "string", "description": "Currency, as the ISO 4217 alphabetic code.", "example": "BRL" }, "originalAmount": { "type": "number", "description": "Fare before discounts and fees, in cents.", "example": 120000 }, "discountAmount": { "type": "number", "description": "Discount applied to the fare, in cents.", "example": 8000 }, "feeAmount": { "type": "number", "description": "Fees added to the fare, in cents.", "example": 0 }, "amount": { "type": "number", "description": "Total charged for the fare, in cents: `originalAmount` - `discountAmount` + `feeAmount`.", "example": 112000 }, "boardType": { "type": "string", "enum": [ "ONLY_ROOM", "BREAKFAST", "HALF_BOARD", "FULL_BOARD", "ALL_INCLUSIVE" ], "description": "Meals included in the fare.", "example": "BREAKFAST" }, "cancellationPolicies": { "type": "object", "properties": { "refundable": { "type": "boolean", "description": "Whether cancelling gives any money back.", "example": true }, "immediateFine": { "type": "boolean", "description": "Whether a fine applies to a cancellation made right after the booking.", "example": false }, "penalties": { "type": "array", "items": { "type": "object", "properties": { "from": { "type": "string", "description": "First day (`YYYY-MM-DD`) on which this tier applies.", "example": "2026-10-25" }, "currency": { "type": "string", "description": "Currency, as the ISO 4217 alphabetic code.", "example": "BRL" }, "fineAmount": { "type": "number", "nullable": true, "description": "Fine charged for cancelling from `from` onward, in cents. `null` when the amount is not available.", "example": 15000 } }, "required": [ "from", "currency", "fineAmount" ], "description": "One tier of a cancellation penalty schedule." }, "description": "Penalty tiers, each in effect from its own date. Empty when no scheduled penalty applies." } }, "required": [ "refundable", "immediateFine", "penalties" ], "description": "Cancellation rules of the fare." } }, "required": [ "currency", "originalAmount", "discountAmount", "feeAmount", "amount", "boardType", "cancellationPolicies" ], "description": "Fare of the room." }, "passengersId": { "type": "array", "items": { "type": "string", "example": "6710a3f2c9e77b0012a4d5e1" }, "description": "IDs of the passengers staying in this room — the trip's `passengers[]`.\n\n---\n\nExample: `[\"6710a3f2c9e77b0012a4d5e1\"]`" } }, "required": [ "name", "fare", "passengersId" ], "description": "A booked room." }, "description": "Rooms booked for the stay." }, "locators": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "Kind of reference, such as `PNR` for an airline's booking code.", "example": "PNR" }, "code": { "type": "string", "description": "The reference itself, as the supplier issued it.", "example": "ABC123" } }, "required": [ "type", "code" ], "description": "A reference that identifies the booking with the supplier, such as an airline's booking code." }, "description": "Booking references issued by the hotel. Empty until the reservation is confirmed." } }, "required": [ "hotel", "checkIn", "checkOut", "rooms", "locators" ], "description": "The booked hotel stay: the hotel, the dates, the rooms with their fares and guests (by ID), and the reservation locators. This is the shape of `productSnapshot` when the trip's `vertical` is `HOTEL`. Amounts are integers in cents.", "title": "Hotel trip" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "DIRECT", "CONNECTION", "ONE_STOP" ], "description": "Kind of trip: `DIRECT`, `CONNECTION` or `ONE_STOP`.", "example": "DIRECT" }, "origin": { "type": "object", "properties": { "locality": { "type": "string", "description": "City the station sits in.", "example": "São Paulo" }, "administrativeArea": { "type": "string", "description": "State, as its short code.", "example": "SP" }, "name": { "type": "string", "nullable": true, "description": "Official name of the station. `null` when unknown.", "example": "Terminal Rodoviário Tietê" }, "shortAddress": { "type": "string", "nullable": true, "description": "Readable single-line address of the station. `null` when unknown.", "example": "Av. Cruzeiro do Sul, 1800, São Paulo, SP, Brazil" }, "phoneNumbers": { "type": "array", "items": { "type": "string", "example": "551133336666" }, "description": "Contact phone numbers of the station, digits only. Empty when none is registered.\n\n---\n\nExample: `[\"551133336666\"]`" } }, "required": [ "locality", "administrativeArea", "name", "shortAddress", "phoneNumbers" ], "description": "Station the trip starts at." }, "destination": { "type": "object", "properties": { "locality": { "type": "string", "description": "City the station sits in.", "example": "São Paulo" }, "administrativeArea": { "type": "string", "description": "State, as its short code.", "example": "SP" }, "name": { "type": "string", "nullable": true, "description": "Official name of the station. `null` when unknown.", "example": "Terminal Rodoviário Tietê" }, "shortAddress": { "type": "string", "nullable": true, "description": "Readable single-line address of the station. `null` when unknown.", "example": "Av. Cruzeiro do Sul, 1800, São Paulo, SP, Brazil" }, "phoneNumbers": { "type": "array", "items": { "type": "string", "example": "551133336666" }, "description": "Contact phone numbers of the station, digits only. Empty when none is registered.\n\n---\n\nExample: `[\"551133336666\"]`" } }, "required": [ "locality", "administrativeArea", "name", "shortAddress", "phoneNumbers" ], "description": "Station the trip ends at.", "example": { "locality": "Rio de Janeiro", "administrativeArea": "RJ", "name": "Rodoviária Novo Rio", "shortAddress": "Av. Francisco Bicalho, 1, Rio de Janeiro, RJ, Brazil", "phoneNumbers": [ "552133338888" ] } }, "departureDate": { "type": "string", "description": "Departure date and time in the local time of the origin station, as `YYYY-MM-DDTHH:mm:ss` with no time zone.", "example": "2026-11-02T08:30:00" }, "arrivalDate": { "type": "string", "description": "Arrival date and time in the local time of the destination station, as `YYYY-MM-DDTHH:mm:ss` with no time zone.", "example": "2026-11-02T14:45:00" }, "company": { "type": "object", "properties": { "name": { "type": "string", "description": "Commercial name of the company.", "example": "Expresso Brasileiro" }, "logo": { "type": "string", "nullable": true, "description": "URL of the company's logo. `null` when there is none.", "example": "https://cdn.example.com/bus/expresso-brasileiro.png" } }, "required": [ "name", "logo" ], "description": "Company that operates the trip." }, "passengerId": { "type": "string", "description": "ID of the passenger travelling on this ticket — one of the trip's `passengers[]`. Omitted only if the passenger could not be matched to the trip's passengers.", "example": "6710a3f2c9e77b0012a4d5e1" }, "segments": { "type": "array", "items": { "type": "object", "properties": { "seatNumber": { "type": "number", "description": "Seat reserved on the segment.", "example": 12 }, "serviceClass": { "type": "string", "enum": [ "SLEEPER_BED", "BED", "SEMI_BED", "EXECUTIVE", "CONVENTIONAL", "UNDEFINED" ], "description": "Class of service booked for the segment.", "example": "EXECUTIVE" }, "origin": { "type": "object", "properties": { "locality": { "type": "string", "description": "City the station sits in.", "example": "São Paulo" }, "administrativeArea": { "type": "string", "description": "State, as its short code.", "example": "SP" }, "name": { "type": "string", "nullable": true, "description": "Official name of the station. `null` when unknown.", "example": "Terminal Rodoviário Tietê" }, "shortAddress": { "type": "string", "nullable": true, "description": "Readable single-line address of the station. `null` when unknown.", "example": "Av. Cruzeiro do Sul, 1800, São Paulo, SP, Brazil" }, "phoneNumbers": { "type": "array", "items": { "type": "string", "example": "551133336666" }, "description": "Contact phone numbers of the station, digits only. Empty when none is registered.\n\n---\n\nExample: `[\"551133336666\"]`" } }, "required": [ "locality", "administrativeArea", "name", "shortAddress", "phoneNumbers" ], "description": "Station the segment leaves from." }, "destination": { "type": "object", "properties": { "locality": { "type": "string", "description": "City the station sits in.", "example": "São Paulo" }, "administrativeArea": { "type": "string", "description": "State, as its short code.", "example": "SP" }, "name": { "type": "string", "nullable": true, "description": "Official name of the station. `null` when unknown.", "example": "Terminal Rodoviário Tietê" }, "shortAddress": { "type": "string", "nullable": true, "description": "Readable single-line address of the station. `null` when unknown.", "example": "Av. Cruzeiro do Sul, 1800, São Paulo, SP, Brazil" }, "phoneNumbers": { "type": "array", "items": { "type": "string", "example": "551133336666" }, "description": "Contact phone numbers of the station, digits only. Empty when none is registered.\n\n---\n\nExample: `[\"551133336666\"]`" } }, "required": [ "locality", "administrativeArea", "name", "shortAddress", "phoneNumbers" ], "description": "Station the segment arrives at.", "example": { "locality": "Rio de Janeiro", "administrativeArea": "RJ", "name": "Rodoviária Novo Rio", "shortAddress": "Av. Francisco Bicalho, 1, Rio de Janeiro, RJ, Brazil", "phoneNumbers": [ "552133338888" ] } }, "departureDate": { "type": "string", "description": "Departure date and time in the local time of the origin station, as `YYYY-MM-DDTHH:mm:ss` with no time zone.", "example": "2026-11-02T08:30:00" }, "arrivalDate": { "type": "string", "description": "Arrival date and time in the local time of the destination station, as `YYYY-MM-DDTHH:mm:ss` with no time zone.", "example": "2026-11-02T14:45:00" }, "duration": { "type": "string", "nullable": true, "description": "Duration of the leg, as `HH:mm`. `null` when not available.", "example": "06:15" }, "fare": { "type": "object", "properties": { "originalAmount": { "type": "number", "description": "Fare before discounts and fees, in cents.", "example": 18000 }, "discountAmount": { "type": "number", "description": "Discount applied to the fare, in cents.", "example": 1000 }, "feeAmount": { "type": "number", "description": "Fees added to the fare, in cents.", "example": 500 }, "amount": { "type": "number", "description": "Total charged for the fare, in cents: `originalAmount` - `discountAmount` + `feeAmount`.", "example": 17500 }, "currency": { "type": "string", "description": "Currency, as the ISO 4217 alphabetic code.", "example": "BRL" }, "cancellationPolicies": { "type": "object", "properties": { "refundable": { "type": "boolean", "description": "Whether cancelling gives any money back.", "example": true }, "immediateFine": { "type": "boolean", "description": "Whether a fine applies to a cancellation made right after the booking.", "example": false }, "penalties": { "type": "array", "items": { "type": "object", "properties": { "from": { "type": "string", "description": "First day (`YYYY-MM-DD`) on which this tier applies.", "example": "2026-10-25" }, "currency": { "type": "string", "description": "Currency, as the ISO 4217 alphabetic code.", "example": "BRL" }, "fineAmount": { "type": "number", "nullable": true, "description": "Fine charged for cancelling from `from` onward, in cents. `null` when the amount is not available.", "example": 15000 } }, "required": [ "from", "currency", "fineAmount" ], "description": "One tier of a cancellation penalty schedule." }, "description": "Penalty tiers, each in effect from its own date. Empty when no scheduled penalty applies." } }, "required": [ "refundable", "immediateFine", "penalties" ], "description": "Cancellation rules of the fare." } }, "required": [ "originalAmount", "discountAmount", "feeAmount", "amount", "currency", "cancellationPolicies" ], "description": "Fare of the segment." }, "company": { "type": "object", "properties": { "name": { "type": "string", "description": "Commercial name of the company.", "example": "Expresso Brasileiro" }, "logo": { "type": "string", "nullable": true, "description": "URL of the company's logo. `null` when there is none.", "example": "https://cdn.example.com/bus/expresso-brasileiro.png" } }, "required": [ "name", "logo" ], "description": "Operator running this leg." } }, "required": [ "seatNumber", "serviceClass", "origin", "destination", "departureDate", "arrivalDate", "duration", "fare", "company" ], "description": "One leg of the bus trip, with the seat booked on it." }, "description": "Segments of the trip, one per leg, each with its seat, fare and operator." }, "routeDirection": { "type": "string", "enum": [ "DEPARTURE", "RETURN" ], "description": "Whether this booking is the outbound trip (`DEPARTURE`) or the return trip (`RETURN`).", "example": "DEPARTURE" }, "boardingInfo": { "description": "Boarding pass and, per leg, platform and ticket codes. `null` until it is first collected, as the departure approaches.", "example": null, "type": "object", "properties": { "boardingPass": { "type": "string", "nullable": true, "description": "The boarding pass PDF, base64-encoded. `null` when not available yet.", "example": "JVBERi0xLjcK" }, "routes": { "type": "array", "items": { "type": "object", "properties": { "origin": { "type": "string", "description": "City the leg starts in.", "example": "São Paulo" }, "destination": { "type": "string", "description": "City the leg ends in.", "example": "Rio de Janeiro" }, "platform": { "type": "string", "nullable": true, "description": "Boarding platform at the origin station. `null` when not assigned or not applicable.", "example": "14" }, "departureDate": { "type": "string", "description": "Departure date and time in local time, as `YYYY-MM-DDTHH:mm:ss` with no time zone.", "example": "2026-11-02T08:30:00" }, "arrivalDate": { "type": "string", "description": "Arrival date and time in local time, as `YYYY-MM-DDTHH:mm:ss` with no time zone.", "example": "2026-11-02T14:45:00" }, "tickets": { "type": "array", "items": { "type": "object", "properties": { "passengerId": { "type": "string", "description": "ID of the passenger the ticket belongs to — one of the trip's `passengers[]`. Omitted only if the passenger could not be matched to the trip's passengers.", "example": "6710a3f2c9e77b0012a4d5e1" }, "locators": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "Kind of reference, such as `PNR` for an airline's booking code.", "example": "PNR" }, "code": { "type": "string", "description": "The reference itself, as the supplier issued it.", "example": "ABC123" } }, "required": [ "type", "code" ], "description": "A reference that identifies the booking with the supplier, such as an airline's booking code." }, "description": "Booking references of the ticket. Empty when none is available." }, "ticketCode": { "type": "string", "nullable": true, "description": "Code of the ticket. `null` when not available.", "example": "EB123456" }, "qrCode": { "type": "string", "nullable": true, "description": "The boarding QR code image, base64-encoded. `null` when not available.", "example": "iVBORw0KGgo=" }, "bpeNumber": { "type": "string", "nullable": true, "description": "Number of the electronic bus ticket (BP-e). `null` when not available.", "example": "35261112345678000190630010000123451000123456" } }, "required": [ "locators", "ticketCode", "qrCode", "bpeNumber" ], "description": "The boarding ticket of one passenger on one leg." }, "description": "Tickets of the leg, one per passenger." } }, "required": [ "origin", "destination", "platform", "departureDate", "arrivalDate", "tickets" ], "description": "The boarding details of one leg of the trip." }, "description": "Boarding details per leg. A connection has two legs; direct and one-stop trips have one." } }, "required": [ "boardingPass", "routes" ], "nullable": true } }, "required": [ "type", "origin", "destination", "departureDate", "arrivalDate", "company", "segments", "routeDirection", "boardingInfo" ], "description": "The booked bus trip of one passenger (by ID): stations, operator, the legs with their seats and fares, and boarding information. This is the shape of `productSnapshot` when the trip's `vertical` is `BUS`. Amounts are integers in cents.", "title": "Bus trip" }, { "type": "object", "properties": { "groupName": { "type": "string", "description": "Commercial group the vehicle belongs to, such as `ECONOMY` or `SUV`.", "example": "ECONOMY" }, "class": { "type": "string", "description": "Class of the vehicle within its group.", "example": "INTERMEDIATE" }, "name": { "type": "string", "description": "Name of the vehicle, as the rental company displays it.", "example": "Fiat Mobi" }, "sipp": { "type": "string", "description": "SIPP code that classifies the vehicle by size, doors, transmission and fuel.", "example": "ECMR" }, "rentalCompany": { "type": "object", "properties": { "code": { "type": "string", "description": "Code of the rental company.", "example": "LOC" }, "name": { "type": "string", "description": "Commercial name of the rental company.", "example": "Localiza" }, "logo": { "type": "string", "nullable": true, "description": "URL of the rental company's logo. `null` when the company has no registered logo.", "example": "https://cdn.example.com/rentals/localiza.svg" } }, "required": [ "code", "name", "logo" ], "description": "Rental company that holds the booking." }, "pickUpLocation": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the rental location.", "example": "Localiza Aeroporto Guarulhos (GRU)" }, "phoneNumbers": { "type": "array", "items": { "type": "string", "example": "551133337777" }, "description": "Contact phone numbers of the location, digits only. Empty when none is registered.\n\n---\n\nExample: `[\"551133337777\"]`" }, "shortAddress": { "type": "string", "nullable": true, "description": "Readable single-line address of the location. `null` when unknown.", "example": "Rod. Hélio Smidt, s/n, Guarulhos, SP, Brazil" }, "locality": { "type": "string", "nullable": true, "description": "City the location sits in. `null` when unknown.", "example": "Guarulhos" }, "administrativeArea": { "type": "string", "nullable": true, "description": "State, as its short code. `null` when unknown.", "example": "SP" } }, "required": [ "name", "phoneNumbers", "shortAddress", "locality", "administrativeArea" ], "description": "Where the vehicle is picked up." }, "dropOffLocation": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the rental location.", "example": "Localiza Aeroporto Guarulhos (GRU)" }, "phoneNumbers": { "type": "array", "items": { "type": "string", "example": "551133337777" }, "description": "Contact phone numbers of the location, digits only. Empty when none is registered.\n\n---\n\nExample: `[\"551133337777\"]`" }, "shortAddress": { "type": "string", "nullable": true, "description": "Readable single-line address of the location. `null` when unknown.", "example": "Rod. Hélio Smidt, s/n, Guarulhos, SP, Brazil" }, "locality": { "type": "string", "nullable": true, "description": "City the location sits in. `null` when unknown.", "example": "Guarulhos" }, "administrativeArea": { "type": "string", "nullable": true, "description": "State, as its short code. `null` when unknown.", "example": "SP" } }, "required": [ "name", "phoneNumbers", "shortAddress", "locality", "administrativeArea" ], "description": "Where the vehicle is dropped off." }, "pickUpDate": { "type": "string", "description": "Pick-up date and time in the local time of the pick-up location, as `YYYY-MM-DDTHH:mm:ss` with no time zone.", "example": "2026-11-02T10:00:00" }, "dropOffDate": { "type": "string", "description": "Drop-off date and time in the local time of the drop-off location, as `YYYY-MM-DDTHH:mm:ss` with no time zone.", "example": "2026-11-04T10:00:00" }, "rentals": { "type": "array", "items": { "type": "object", "properties": { "description": { "type": "string", "nullable": true, "description": "Readable description of the rental option. `null` when not provided.", "example": "Compact car, air conditioning, unlimited mileage" }, "fare": { "type": "object", "properties": { "originalAmount": { "type": "number", "description": "Fare before discounts and fees, in cents.", "example": 36000 }, "discountAmount": { "type": "number", "description": "Discount applied to the fare, in cents.", "example": 2000 }, "feeAmount": { "type": "number", "description": "Fees added to the fare, in cents.", "example": 0 }, "amount": { "type": "number", "description": "Total charged for the fare, in cents: `originalAmount` - `discountAmount` + `feeAmount`.", "example": 34000 }, "currency": { "type": "string", "description": "Currency, as the ISO 4217 alphabetic code.", "example": "BRL" }, "cancellationPolicies": { "type": "object", "properties": { "refundable": { "type": "boolean", "description": "Whether cancelling gives any money back.", "example": true }, "immediateFine": { "type": "boolean", "description": "Whether a fine applies to a cancellation made right after the booking.", "example": false }, "penalties": { "type": "array", "items": { "type": "object", "properties": { "from": { "type": "string", "nullable": true, "description": "First day (`YYYY-MM-DD`) on which this tier applies. `null` when the supplier gave no date.", "example": "2026-10-31" }, "currency": { "type": "string", "description": "Currency, as the ISO 4217 alphabetic code.", "example": "BRL" }, "fineAmount": { "type": "number", "nullable": true, "description": "Fine charged for cancelling from `from` onward, in cents. `null` when the amount is not available.", "example": 12000 } }, "required": [ "from", "currency", "fineAmount" ], "description": "One tier of the cancellation penalty schedule of a rental." }, "description": "Penalty tiers, each in effect from its own date. Empty when no scheduled penalty applies." } }, "required": [ "refundable", "immediateFine", "penalties" ], "description": "Cancellation rules of the fare." } }, "required": [ "originalAmount", "discountAmount", "feeAmount", "amount", "currency", "cancellationPolicies" ], "description": "Fare of the rental." }, "passengersId": { "type": "array", "items": { "type": "string", "example": "6710a3f2c9e77b0012a4d5e1" }, "description": "IDs of the passengers travelling on this rental — the trip's `passengers[]`. Empty when none was assigned.\n\n---\n\nExample: `[\"6710a3f2c9e77b0012a4d5e1\"]`" }, "locators": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "Kind of reference, such as `PNR` for an airline's booking code.", "example": "PNR" }, "code": { "type": "string", "description": "The reference itself, as the supplier issued it.", "example": "ABC123" } }, "required": [ "type", "code" ], "description": "A reference that identifies the booking with the supplier, such as an airline's booking code." }, "description": "Booking references of the rental with the rental company. Empty until the reservation is confirmed." } }, "required": [ "description", "fare", "passengersId", "locators" ], "description": "A booked rental." }, "description": "Rentals booked under this record." }, "locators": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "Kind of reference, such as `PNR` for an airline's booking code.", "example": "PNR" }, "code": { "type": "string", "description": "The reference itself, as the supplier issued it.", "example": "ABC123" } }, "required": [ "type", "code" ], "description": "A reference that identifies the booking with the supplier, such as an airline's booking code." }, "description": "Booking references of the reservation as a whole. Empty until the reservation is confirmed." } }, "required": [ "groupName", "class", "name", "sipp", "rentalCompany", "pickUpLocation", "dropOffLocation", "pickUpDate", "dropOffDate", "rentals", "locators" ], "description": "The booked vehicle rental: the vehicle, the rental company, the pick-up and drop-off places and dates, fares, passengers (by ID) and reservation locators. This is the shape of `productSnapshot` when the trip's `vertical` is `VEHICLE`. Amounts are integers in cents.", "title": "Vehicle trip" } ], "description": "The booked product: the itinerary, stay, ticket or rental as recorded by the travel provider — journeys and flights, the hotel and its rooms, the route and boarding information, the rental — with its fares, policies and booking locators. It does not repeat the trip's own fields (`state`, `status`, the amounts, the dates) and carries no identifier of the travel provider; passengers are referenced by their `id` in `passengers[]`. Its shape depends on `vertical`: a flight (`AIR`), a hotel stay (`HOTEL`), a bus ticket (`BUS`) or a vehicle rental (`VEHICLE`) — see the four schemas below. Omitted until the record is first fetched." }, "cancellation": { "type": "object", "properties": { "quoteId": { "type": "string", "description": "ID of the confirmed cancellation quote." }, "cancelType": { "type": "string", "enum": [ "CREDIT", "REFUND", "MANUAL_CANCEL", "VOID" ], "description": "Kind of cancellation: `VOID` for a trip not issued yet, `REFUND` or `CREDIT` for an issued one, `MANUAL_CANCEL` when the amounts are settled outside the system." }, "originalAmount": { "type": "number", "nullable": true, "description": "What the trip cost, in cents. Omitted when it couldn't be recorded; `null` for `MANUAL_CANCEL`." }, "remainingAmount": { "type": "number", "nullable": true, "description": "What is given back after the fine, in cents. Omitted when it couldn't be recorded; `null` for `MANUAL_CANCEL`." }, "fineAmount": { "type": "number", "nullable": true, "description": "Cancellation fine, in cents. Omitted when it couldn't be recorded; `null` for `MANUAL_CANCEL`." }, "currency": { "type": "string", "description": "Currency of the amounts, as the numeric ISO 4217 code (`986` is BRL)." }, "status": { "type": "string", "description": "Status of the quote when it was confirmed." }, "expiresAt": { "type": "string", "description": "When the quote would have expired.", "format": "date-time" }, "confirmedAt": { "type": "string", "description": "When the cancellation was confirmed.", "format": "date-time" }, "confirmedBy": { "type": "string", "description": "ID of the user who confirmed the cancellation. Omitted when a service did." } }, "required": [ "quoteId", "cancelType" ], "description": "The confirmed cancellation. Omitted until one is confirmed." }, "createdAt": { "type": "string", "description": "When the trip was created.", "example": "2026-10-01T13:45:12.000Z", "format": "date-time" }, "updatedAt": { "type": "string", "description": "When the trip last changed.", "example": "2026-10-01T13:46:03.000Z", "format": "date-time" } }, "required": [ "id", "realmId", "organizationId", "customFields", "vertical", "state", "status", "passengers" ], "description": "A trip: ONE booked product — a flight, a hotel stay, a bus ticket or a vehicle rental — for the organization's passengers, with its lifecycle. Booking several products means creating several trips." }, "examples": { "air-trip": { "summary": "Air trip", "value": { "id": "6711b4c0d8e1a30012b7c9f2", "realmId": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b", "organizationId": "c4bd3f21-dfbd-44e8-8055-68ba15bed410", "createdBy": "e3553bc1-5e20-4e17-b22a-a796fda0aa99", "customFields": { "cost-center": "CC-1020" }, "vertical": "AIR", "state": "RESERVED", "status": "RESERVED", "reservationExpiresAt": "2026-10-02T13:45:12.000Z", "originalAmount": 95000, "discountAmount": 3010, "feeAmount": 0, "totalAmount": 91990, "currency": "986", "passengers": [ { "id": "6710a3f2c9e77b0012a4d5e1", "userId": "e3553bc1-5e20-4e17-b22a-a796fda0aa99", "lead": true, "name": "Mariana Costa", "gender": "FEMALE", "birthDate": "1990-04-17" } ], "productSnapshot": { "journeys": [ { "id": "jour_V1StGXR8Z5jdHi6BmyT2k", "direction": "DEPARTURE", "origin": { "iata": "GRU", "name": "São Paulo/Guarulhos International Airport", "shortAddress": "Guarulhos, SP, Brazil", "locality": "Guarulhos", "administrativeArea": "SP", "phoneNumbers": [ "551133334444" ] }, "destination": { "iata": "SDU", "name": "Rio de Janeiro/Santos Dumont Airport", "shortAddress": "Rio de Janeiro, RJ, Brazil", "locality": "Rio de Janeiro", "administrativeArea": "RJ", "phoneNumbers": [ "552133339999" ] }, "departureDate": "2026-11-02T08:30:00", "arrivalDate": "2026-11-02T09:35:00", "duration": "01:05", "segments": [ { "airline": { "code": "LA", "name": "LATAM Airlines", "logo": "https://cdn.example.com/airlines/LA.png" }, "operation": { "code": "LA", "name": "LATAM Airlines", "logo": "https://cdn.example.com/airlines/LA.png" }, "origin": { "iata": "GRU", "name": "São Paulo/Guarulhos International Airport", "shortAddress": "Guarulhos, SP, Brazil", "locality": "Guarulhos", "administrativeArea": "SP", "phoneNumbers": [ "551133334444" ] }, "destination": { "iata": "SDU", "name": "Rio de Janeiro/Santos Dumont Airport", "shortAddress": "Rio de Janeiro, RJ, Brazil", "locality": "Rio de Janeiro", "administrativeArea": "RJ", "phoneNumbers": [ "552133339999" ] }, "flightNumber": "3101", "departureDate": "2026-11-02T08:30:00", "arrivalDate": "2026-11-02T09:35:00", "flightType": "REGULAR", "duration": "01:05", "equipment": "32Q", "cabin": "ECONOMY", "class": "Y", "fareBasis": "YOW", "flightInfo": null } ] } ], "tickets": [ { "passengerId": "6710a3f2c9e77b0012a4d5e1", "fareDescription": "GRU to SDU, LATAM Airlines, Economy", "ticketNumber": null, "fares": [ { "journeyId": "jour_V1StGXR8Z5jdHi6BmyT2k", "currency": "BRL", "originalAmount": 95000, "discountAmount": 3010, "feeAmount": 0, "amount": 91990, "cancellationPolicies": { "refundable": true, "immediateFine": false, "penalties": [ { "from": "2026-10-25", "currency": "BRL", "fineAmount": 15000 } ] }, "changePolicies": { "canChange": true, "immediateFine": false, "penalties": [ { "from": "2026-10-25", "currency": "BRL", "fineAmount": 8000 } ] } } ], "segments": [ { "flightNumber": "3101", "cabin": "ECONOMY", "class": "Y", "fareBasis": "YOW", "baggages": [ { "quantity": 1, "weight": 23, "type": "CHECKED" } ] } ] } ], "locators": [ { "type": "PNR", "code": "ABC123" } ], "flightInfoUpdatedAt": null }, "createdAt": "2026-10-01T13:45:12.000Z", "updatedAt": "2026-10-01T13:46:03.000Z" } }, "hotel-trip": { "summary": "Hotel trip", "value": { "id": "6711b4c0d8e1a30012b7c9f2", "realmId": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b", "organizationId": "c4bd3f21-dfbd-44e8-8055-68ba15bed410", "createdBy": "e3553bc1-5e20-4e17-b22a-a796fda0aa99", "customFields": { "cost-center": "CC-1020" }, "vertical": "HOTEL", "state": "RESERVED", "status": "RESERVED", "reservationExpiresAt": "2026-10-02T13:45:12.000Z", "originalAmount": 95000, "discountAmount": 3010, "feeAmount": 0, "totalAmount": 91990, "currency": "986", "passengers": [ { "id": "6710a3f2c9e77b0012a4d5e1", "userId": "e3553bc1-5e20-4e17-b22a-a796fda0aa99", "lead": true, "name": "Mariana Costa", "gender": "FEMALE", "birthDate": "1990-04-17" } ], "productSnapshot": { "hotel": { "name": "Hotel Paulista Plaza", "chain": { "brandName": "Ibis", "chainName": "Accor", "logo": "https://cdn.example.com/hotels/ibis.svg" }, "shortAddress": "Av. Paulista, 1500, São Paulo, SP, Brazil", "phoneNumbers": [ "551133335555" ], "locality": "São Paulo", "administrativeArea": "SP", "checkInTime": "14:00", "checkOutTime": "12:00" }, "checkIn": "2026-11-02", "checkOut": "2026-11-04", "rooms": [ { "name": "Standard Room, 1 Queen Bed", "fare": { "currency": "BRL", "originalAmount": 120000, "discountAmount": 8000, "feeAmount": 0, "amount": 112000, "boardType": "BREAKFAST", "cancellationPolicies": { "refundable": true, "immediateFine": false, "penalties": [ { "from": "2026-10-25", "currency": "BRL", "fineAmount": 15000 } ] } }, "passengersId": [ "6710a3f2c9e77b0012a4d5e1" ] } ], "locators": [ { "type": "PNR", "code": "ABC123" } ] }, "createdAt": "2026-10-01T13:45:12.000Z", "updatedAt": "2026-10-01T13:46:03.000Z" } }, "bus-trip": { "summary": "Bus trip", "value": { "id": "6711b4c0d8e1a30012b7c9f2", "realmId": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b", "organizationId": "c4bd3f21-dfbd-44e8-8055-68ba15bed410", "createdBy": "e3553bc1-5e20-4e17-b22a-a796fda0aa99", "customFields": { "cost-center": "CC-1020" }, "vertical": "BUS", "state": "RESERVED", "status": "RESERVED", "reservationExpiresAt": "2026-10-02T13:45:12.000Z", "originalAmount": 95000, "discountAmount": 3010, "feeAmount": 0, "totalAmount": 91990, "currency": "986", "passengers": [ { "id": "6710a3f2c9e77b0012a4d5e1", "userId": "e3553bc1-5e20-4e17-b22a-a796fda0aa99", "lead": true, "name": "Mariana Costa", "gender": "FEMALE", "birthDate": "1990-04-17" } ], "productSnapshot": { "type": "DIRECT", "origin": { "locality": "São Paulo", "administrativeArea": "SP", "name": "Terminal Rodoviário Tietê", "shortAddress": "Av. Cruzeiro do Sul, 1800, São Paulo, SP, Brazil", "phoneNumbers": [ "551133336666" ] }, "destination": { "locality": "Rio de Janeiro", "administrativeArea": "RJ", "name": "Rodoviária Novo Rio", "shortAddress": "Av. Francisco Bicalho, 1, Rio de Janeiro, RJ, Brazil", "phoneNumbers": [ "552133338888" ] }, "departureDate": "2026-11-02T08:30:00", "arrivalDate": "2026-11-02T14:45:00", "company": { "name": "Expresso Brasileiro", "logo": "https://cdn.example.com/bus/expresso-brasileiro.png" }, "passengerId": "6710a3f2c9e77b0012a4d5e1", "segments": [ { "seatNumber": 12, "serviceClass": "EXECUTIVE", "origin": { "locality": "São Paulo", "administrativeArea": "SP", "name": "Terminal Rodoviário Tietê", "shortAddress": "Av. Cruzeiro do Sul, 1800, São Paulo, SP, Brazil", "phoneNumbers": [ "551133336666" ] }, "destination": { "locality": "Rio de Janeiro", "administrativeArea": "RJ", "name": "Rodoviária Novo Rio", "shortAddress": "Av. Francisco Bicalho, 1, Rio de Janeiro, RJ, Brazil", "phoneNumbers": [ "552133338888" ] }, "departureDate": "2026-11-02T08:30:00", "arrivalDate": "2026-11-02T14:45:00", "duration": "06:15", "fare": { "originalAmount": 18000, "discountAmount": 1000, "feeAmount": 500, "amount": 17500, "currency": "BRL", "cancellationPolicies": { "refundable": true, "immediateFine": false, "penalties": [ { "from": "2026-10-25", "currency": "BRL", "fineAmount": 15000 } ] } }, "company": { "name": "Expresso Brasileiro", "logo": "https://cdn.example.com/bus/expresso-brasileiro.png" } } ], "routeDirection": "DEPARTURE", "boardingInfo": null }, "createdAt": "2026-10-01T13:45:12.000Z", "updatedAt": "2026-10-01T13:46:03.000Z" } }, "vehicle-trip": { "summary": "Vehicle trip", "value": { "id": "6711b4c0d8e1a30012b7c9f2", "realmId": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b", "organizationId": "c4bd3f21-dfbd-44e8-8055-68ba15bed410", "createdBy": "e3553bc1-5e20-4e17-b22a-a796fda0aa99", "customFields": { "cost-center": "CC-1020" }, "vertical": "VEHICLE", "state": "RESERVED", "status": "RESERVED", "reservationExpiresAt": "2026-10-02T13:45:12.000Z", "originalAmount": 95000, "discountAmount": 3010, "feeAmount": 0, "totalAmount": 91990, "currency": "986", "passengers": [ { "id": "6710a3f2c9e77b0012a4d5e1", "userId": "e3553bc1-5e20-4e17-b22a-a796fda0aa99", "lead": true, "name": "Mariana Costa", "gender": "FEMALE", "birthDate": "1990-04-17" } ], "productSnapshot": { "groupName": "ECONOMY", "class": "INTERMEDIATE", "name": "Fiat Mobi", "sipp": "ECMR", "rentalCompany": { "code": "LOC", "name": "Localiza", "logo": "https://cdn.example.com/rentals/localiza.svg" }, "pickUpLocation": { "name": "Localiza Aeroporto Guarulhos (GRU)", "phoneNumbers": [ "551133337777" ], "shortAddress": "Rod. Hélio Smidt, s/n, Guarulhos, SP, Brazil", "locality": "Guarulhos", "administrativeArea": "SP" }, "dropOffLocation": { "name": "Localiza Aeroporto Guarulhos (GRU)", "phoneNumbers": [ "551133337777" ], "shortAddress": "Rod. Hélio Smidt, s/n, Guarulhos, SP, Brazil", "locality": "Guarulhos", "administrativeArea": "SP" }, "pickUpDate": "2026-11-02T10:00:00", "dropOffDate": "2026-11-04T10:00:00", "rentals": [ { "description": "Compact car, air conditioning, unlimited mileage", "fare": { "originalAmount": 36000, "discountAmount": 2000, "feeAmount": 0, "amount": 34000, "currency": "BRL", "cancellationPolicies": { "refundable": true, "immediateFine": false, "penalties": [ { "from": "2026-10-31", "currency": "BRL", "fineAmount": 12000 } ] } }, "passengersId": [ "6710a3f2c9e77b0012a4d5e1" ], "locators": [ { "type": "PNR", "code": "ABC123" } ] } ], "locators": [ { "type": "PNR", "code": "ABC123" } ] }, "createdAt": "2026-10-01T13:45:12.000Z", "updatedAt": "2026-10-01T13:46:03.000Z" } } } } } }, "400": { "description": "`TRIP_NOT_RESERVED` — The trip's `status` is not `RESERVED`, so it can't be issued.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "TRIP_NOT_RESERVED" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "TRAVEL" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b", "code": "TRIP_NOT_RESERVED", "origin": "TRAVEL", "message": "Trip not reserved" } } } }, "404": { "description": "`TRIP_NOT_FOUND` — No trip with this ID is visible to you in the organization: it doesn't exist, belongs to another organization, or you are neither an organization admin nor a passenger on it.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "TRIP_NOT_FOUND" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "TRAVEL" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b", "code": "TRIP_NOT_FOUND", "origin": "TRAVEL", "message": "Trip not found" } } } }, "422": { "description": "`BAD_REQUEST` — A path parameter is not a valid ID; `fields` lists each one.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "BAD_REQUEST" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "TRAVEL" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." }, "fields": { "type": "array", "description": "One entry per invalid request field (validation errors only).", "items": { "type": "object", "properties": { "field": { "type": "string", "description": "Path of the invalid field, e.g. `label` or `values[0].value`.", "example": "label" }, "message": { "type": "string", "description": "Why the field was rejected.", "example": "label is required" }, "code": { "type": "string", "description": "`_` — e.g. `LABEL_REQUIRED`, `TYPE_ONE_OF`, `VALUES_VALUE_TYPE_ERROR`.", "example": "LABEL_REQUIRED" }, "values": { "type": "array", "items": { "type": "string" }, "description": "The accepted values, when the field is an enumeration." } }, "required": [ "field", "message", "code" ] } } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "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": "organizationId", "message": "Invalid UUID", "code": "ORGANIZATIONID_UUID" } ] } } } }, "503": { "description": "`PROVIDER_UNAVAILABLE` — The travel provider could not be reached; nothing was issued. Retry later.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "PROVIDER_UNAVAILABLE" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "TRAVEL" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b", "code": "PROVIDER_UNAVAILABLE", "origin": "TRAVEL", "message": "Travel provider temporarily unavailable, please retry." } } } } }, "x-p3-confidence": { "response": "generated:typed" } } }, "/realms/{realmId}/organizations/{organizationId}/trips/{tripId}/cancel": { "get": { "operationId": "getRealmsByRealmIdOrganizationsByOrganizationIdTripsByTripIdCancel", "summary": "List cancellation quotes", "tags": [ "Trips" ], "x-p3-sidebar-order": 8, "description": "Lists the ways to cancel a trip, each with what it would cost.", "x-mint": { "content": "Nothing is canceled by this request. When the trip can be canceled you get one quote per way — `VOID` for a trip not issued yet, `REFUND` and `MANUAL_CANCEL` for an issued one, depending on the product and its policy — each with the amounts, in cents, and the time until which it can be confirmed. When the policy doesn't allow it, `cancelable` is `false` and `quotes` is empty. Confirm one by sending its `id` to the cancel request. Visible to an organization admin and to the users the trip carries, like the trip itself." }, "parameters": [ { "name": "realmId", "in": "path", "required": true, "description": "ID of your realm.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b" }, { "name": "organizationId", "in": "path", "required": true, "description": "ID of the organization the trip belongs to.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410" }, { "name": "tripId", "in": "path", "required": true, "description": "ID of the trip (24 hexadecimal characters).", "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$" }, "example": "6711b4c0d8e1a30012b7c9f2" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "cancelable": { "type": "boolean", "description": "Whether the trip can be canceled. When `false`, `quotes` is empty.", "example": true }, "quotes": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the quote. Send it as `cancellationQuoteId` to confirm the cancellation.", "example": "cancel_quote_V1StGXR8Z5jdHi6BmyT2k" }, "cancelType": { "type": "string", "enum": [ "CREDIT", "REFUND", "MANUAL_CANCEL", "VOID" ], "description": "Kind of cancellation: `VOID` for a trip not issued yet, `REFUND` for an issued one, `CREDIT` for a credit-based refund, `MANUAL_CANCEL` when the final amounts are settled outside the system.", "example": "VOID" }, "originalAmount": { "type": "number", "description": "What the trip cost, in cents.", "example": 91990 }, "remainingAmount": { "type": "number", "nullable": true, "description": "What is given back after the fine, in cents. `null` for `MANUAL_CANCEL`.", "example": 91990 }, "fineAmount": { "type": "number", "nullable": true, "description": "Cancellation fine, in cents. `null` for `MANUAL_CANCEL`.", "example": 0 }, "currency": { "type": "string", "description": "Currency of the amounts (ISO 4217 alphabetic code).", "example": "BRL" }, "status": { "type": "string", "enum": [ "QUOTE", "CONFIRMED", "EXPIRED", "PROCESSED", "FAILED" ], "description": "Status of the quote: `QUOTE` while it awaits confirmation.", "example": "QUOTE" }, "expiresAt": { "type": "string", "description": "When the quote expires and can no longer be confirmed.", "example": "2026-10-01T15:00:00.000Z", "format": "date-time" }, "createdAt": { "type": "string", "description": "When the quote was created.", "example": "2026-10-01T14:00:00.000Z", "format": "date-time" }, "updatedAt": { "type": "string", "description": "When the quote last changed.", "example": "2026-10-01T14:00:00.000Z", "format": "date-time" } }, "required": [ "id", "cancelType", "originalAmount", "remainingAmount", "fineAmount", "currency", "status", "expiresAt", "createdAt", "updatedAt" ], "description": "A quote to cancel a trip. Confirm it before `expiresAt` by sending its `id`. Amounts are in cents. The currency is the alphabetic ISO 4217 code (`BRL`), unlike the numeric code (`986`) on trips." }, "description": "The active quotes: up to one `VOID` (trip not issued yet), one `REFUND` and one `MANUAL_CANCEL`, depending on the product and its policy. Confirm one before its `expiresAt`." } }, "required": [ "cancelable", "quotes" ], "description": "The ways to cancel a trip." } } } }, "400": { "description": "`TRIP_CANNOT_BE_CANCELLED` — The trip's status doesn't allow cancellation: it is already canceled, expired or was never reserved.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "TRIP_CANNOT_BE_CANCELLED" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "TRAVEL" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b", "code": "TRIP_CANNOT_BE_CANCELLED", "origin": "TRAVEL", "message": "Trip status does not allow cancellation" } } } }, "404": { "description": "`TRIP_NOT_FOUND` — No trip with this ID is visible to you in the organization: it doesn't exist, belongs to another organization, or you are neither an organization admin nor a passenger on it.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "TRIP_NOT_FOUND" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "TRAVEL" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b", "code": "TRIP_NOT_FOUND", "origin": "TRAVEL", "message": "Trip not found" } } } }, "422": { "description": "`BAD_REQUEST` — A path parameter is not a valid ID; `fields` lists each one.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "BAD_REQUEST" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "TRAVEL" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." }, "fields": { "type": "array", "description": "One entry per invalid request field (validation errors only).", "items": { "type": "object", "properties": { "field": { "type": "string", "description": "Path of the invalid field, e.g. `label` or `values[0].value`.", "example": "label" }, "message": { "type": "string", "description": "Why the field was rejected.", "example": "label is required" }, "code": { "type": "string", "description": "`_` — e.g. `LABEL_REQUIRED`, `TYPE_ONE_OF`, `VALUES_VALUE_TYPE_ERROR`.", "example": "LABEL_REQUIRED" }, "values": { "type": "array", "items": { "type": "string" }, "description": "The accepted values, when the field is an enumeration." } }, "required": [ "field", "message", "code" ] } } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "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": "organizationId", "message": "Invalid UUID", "code": "ORGANIZATIONID_UUID" } ] } } } }, "503": { "description": "`PROVIDER_UNAVAILABLE` — The travel provider could not be reached. Retry later.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "PROVIDER_UNAVAILABLE" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "TRAVEL" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b", "code": "PROVIDER_UNAVAILABLE", "origin": "TRAVEL", "message": "Travel provider temporarily unavailable, please retry." } } } } }, "x-p3-confidence": { "response": "generated:typed" } }, "post": { "operationId": "postRealmsByRealmIdOrganizationsByOrganizationIdTripsByTripIdCancel", "summary": "Cancel a trip", "tags": [ "Trips" ], "x-p3-sidebar-order": 9, "description": "Confirms a cancellation quote, canceling the trip.", "x-mint": { "content": "Send the `id` of one of the quotes listed for the trip, before it expires. The cancellation runs asynchronously: the answer is `202 Accepted` with the trip in `PROCESSING_CANCELLATION` and the confirmed quote in its `cancellation`. Read the trip, or its history, to see it become `CANCELED`. Set `sendToManualCancellationOnFail` to have a cancellation the travel provider rejects handled manually instead of failing. Visible to an organization admin and to the users the trip carries, like the trip itself." }, "parameters": [ { "name": "realmId", "in": "path", "required": true, "description": "ID of your realm.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b" }, { "name": "organizationId", "in": "path", "required": true, "description": "ID of the organization the trip belongs to.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410" }, { "name": "tripId", "in": "path", "required": true, "description": "ID of the trip to cancel (24 hexadecimal characters).", "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$" }, "example": "6711b4c0d8e1a30012b7c9f2" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "cancellationQuoteId": { "type": "string", "pattern": "^cancel_quote_[0-9A-Za-z]{21}$", "description": "The `id` of one of the quotes returned by the cancellation quotes request for this trip (prefix `cancel_quote_`). A quote can only be confirmed before it expires.", "example": "cancel_quote_V1StGXR8Z5jdHi6BmyT2k" }, "sendToManualCancellationOnFail": { "description": "When `true`, a cancellation the travel provider rejects is sent to manual cancellation instead of failing. Defaults to `false`.", "example": false, "type": "boolean" } }, "required": [ "cancellationQuoteId" ] } } } }, "responses": { "202": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the trip.", "example": "6711b4c0d8e1a30012b7c9f2" }, "realmId": { "type": "string", "description": "ID of the realm the trip belongs to.", "example": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b", "format": "uuid" }, "organizationId": { "type": "string", "description": "ID of the organization the trip belongs to.", "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410", "format": "uuid" }, "createdBy": { "type": "string", "description": "ID of the user who created the trip. Omitted when a service did.", "example": "e3553bc1-5e20-4e17-b22a-a796fda0aa99", "format": "uuid" }, "customFields": { "type": "object", "additionalProperties": {}, "description": "Values of the organization's trip custom fields, keyed by the custom field's `slug`. Empty when none were set.\n\n---\n\nExample: `{\"cost-center\":\"CC-1020\"}`", "example": { "cost-center": "CC-1020" } }, "vertical": { "type": "string", "enum": [ "AIR", "HOTEL", "BUS", "VEHICLE" ], "description": "Type of product booked. It tells which shape `productSnapshot` has.", "example": "AIR" }, "state": { "type": "string", "enum": [ "PENDING", "RESERVED", "ISSUED", "CANCELED" ], "description": "Where the booking is in its life: `PENDING` while the reservation is being made, `RESERVED` once held (until `reservationExpiresAt`), `ISSUED` once ticketed and `CANCELED`. It only moves forward.", "example": "RESERVED" }, "status": { "type": "string", "enum": [ "PROCESSING_RESERVATION", "RESERVATION_FAILED", "RESERVED", "PROCESSING_ISSUE", "ISSUED", "PROCESSING_CANCELLATION", "CANCELED", "AWAITING_MANUAL_CANCELLATION", "CANCELLATION_FAILED", "FAILED", "FAILED_BY_INCONSISTENT_DATA", "FAILED_BY_UNAVAILABLE_RESOURCE", "FAILED_BY_BUDGET_EXCEEDED", "EXPIRED", "BLOCKED", "UNKNOWN", "ISSUANCE_FAILED" ], "description": "Finer-grained status: it also reports work in progress (`PROCESSING_*`) and failures, and can change back and forth. Use `state` to decide what the booking is; use `status` to tell what is happening to it.", "example": "RESERVED" }, "reservationExpiresAt": { "type": "string", "nullable": true, "description": "Until when the reservation is held. Past it, a trip that was not issued expires. `null` or omitted when there is no hold.", "example": "2026-10-02T13:45:12.000Z", "format": "date-time" }, "issuedAt": { "type": "string", "nullable": true, "description": "When the trip was issued. `null` or omitted until it is.", "format": "date-time" }, "originalAmount": { "type": "number", "description": "Price before discounts, in cents. Omitted until the price is known.", "example": 95000 }, "discountAmount": { "type": "number", "description": "Discount applied, in cents. Omitted until the price is known.", "example": 3010 }, "feeAmount": { "type": "number", "description": "Fees added, in cents. Omitted until the price is known.", "example": 0 }, "totalAmount": { "type": "number", "description": "Amount to pay, in cents: `originalAmount` - `discountAmount` + `feeAmount`. Omitted until the price is known.", "example": 91990 }, "currency": { "type": "string", "description": "Currency of the amounts, as the numeric ISO 4217 code (`986` is BRL).", "example": "986" }, "passengers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the passenger, as returned by the passenger endpoints.", "example": "6710a3f2c9e77b0012a4d5e1" }, "userId": { "type": "string", "description": "ID of the organization user the passenger is linked to. Omitted for a passenger who is not a user. A user sees the trips they travel on.", "example": "e3553bc1-5e20-4e17-b22a-a796fda0aa99", "format": "uuid" }, "lead": { "type": "boolean", "description": "Whether this passenger is the one responsible for the reservation.", "example": true }, "name": { "type": "string", "description": "Full name, as it appears on the passenger's travel documents.", "example": "Mariana Costa" }, "gender": { "type": "string", "enum": [ "MALE", "FEMALE" ], "description": "Gender.", "example": "FEMALE" }, "birthDate": { "type": "string", "description": "Date of birth (`YYYY-MM-DD`).", "example": "1990-04-17" } }, "required": [ "id", "lead", "name", "gender", "birthDate" ], "description": "A passenger of a trip: who travels, as recorded when the trip was booked. The passenger endpoints serve the full profile." }, "description": "The passengers booked on the trip." }, "productSnapshot": { "anyOf": [ { "type": "object", "properties": { "journeys": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the journey, referenced by `tickets[].fares[].journeyId`.", "example": "jour_V1StGXR8Z5jdHi6BmyT2k" }, "direction": { "type": "string", "enum": [ "DEPARTURE", "RETURN" ], "description": "Whether this is the outbound leg (`DEPARTURE`) or the return leg (`RETURN`).", "example": "DEPARTURE" }, "origin": { "type": "object", "properties": { "iata": { "type": "string", "description": "IATA code of the airport, 3 letters.", "example": "GRU" }, "name": { "type": "string", "nullable": true, "description": "Official name of the airport. `null` when unknown.", "example": "São Paulo/Guarulhos International Airport" }, "shortAddress": { "type": "string", "nullable": true, "description": "Readable single-line address of the airport. `null` when unknown.", "example": "Guarulhos, SP, Brazil" }, "locality": { "type": "string", "nullable": true, "description": "City the airport sits in. `null` when unknown.", "example": "Guarulhos" }, "administrativeArea": { "type": "string", "nullable": true, "description": "State, as its short code. `null` when unknown.", "example": "SP" }, "phoneNumbers": { "type": "array", "items": { "type": "string", "example": "551133334444" }, "description": "Contact phone numbers of the airport, digits only. Empty when none is registered.\n\n---\n\nExample: `[\"551133334444\"]`" } }, "required": [ "iata", "name", "shortAddress", "locality", "administrativeArea", "phoneNumbers" ], "description": "Airport the journey starts at." }, "destination": { "type": "object", "properties": { "iata": { "type": "string", "description": "IATA code of the airport, 3 letters.", "example": "GRU" }, "name": { "type": "string", "nullable": true, "description": "Official name of the airport. `null` when unknown.", "example": "São Paulo/Guarulhos International Airport" }, "shortAddress": { "type": "string", "nullable": true, "description": "Readable single-line address of the airport. `null` when unknown.", "example": "Guarulhos, SP, Brazil" }, "locality": { "type": "string", "nullable": true, "description": "City the airport sits in. `null` when unknown.", "example": "Guarulhos" }, "administrativeArea": { "type": "string", "nullable": true, "description": "State, as its short code. `null` when unknown.", "example": "SP" }, "phoneNumbers": { "type": "array", "items": { "type": "string", "example": "551133334444" }, "description": "Contact phone numbers of the airport, digits only. Empty when none is registered.\n\n---\n\nExample: `[\"551133334444\"]`" } }, "required": [ "iata", "name", "shortAddress", "locality", "administrativeArea", "phoneNumbers" ], "description": "Airport the journey ends at.", "example": { "iata": "SDU", "name": "Rio de Janeiro/Santos Dumont Airport", "shortAddress": "Rio de Janeiro, RJ, Brazil", "locality": "Rio de Janeiro", "administrativeArea": "RJ", "phoneNumbers": [ "552133339999" ] } }, "departureDate": { "type": "string", "description": "Departure date and time in the local time of the origin airport, as `YYYY-MM-DDTHH:mm:ss` with no time zone.", "example": "2026-11-02T08:30:00" }, "arrivalDate": { "type": "string", "description": "Arrival date and time in the local time of the destination airport, as `YYYY-MM-DDTHH:mm:ss` with no time zone.", "example": "2026-11-02T09:35:00" }, "duration": { "type": "string", "description": "Total travel time of the journey, connections included, as `HH:mm`.", "example": "01:05" }, "segments": { "type": "array", "items": { "type": "object", "properties": { "airline": { "type": "object", "properties": { "code": { "type": "string", "description": "IATA code of the airline.", "example": "LA" }, "name": { "type": "string", "nullable": true, "description": "Commercial name of the airline. `null` when unknown.", "example": "LATAM Airlines" }, "logo": { "type": "string", "nullable": true, "description": "URL of the airline's logo. `null` when there is none.", "example": "https://cdn.example.com/airlines/LA.png" } }, "required": [ "code", "name", "logo" ], "description": "Airline that sells the flight." }, "operation": { "type": "object", "properties": { "code": { "type": "string", "description": "IATA code of the airline.", "example": "LA" }, "name": { "type": "string", "nullable": true, "description": "Commercial name of the airline. `null` when unknown.", "example": "LATAM Airlines" }, "logo": { "type": "string", "nullable": true, "description": "URL of the airline's logo. `null` when there is none.", "example": "https://cdn.example.com/airlines/LA.png" } }, "required": [ "code", "name", "logo" ], "description": "Airline that operates the flight. It differs from `airline` on codeshare flights." }, "origin": { "type": "object", "properties": { "iata": { "type": "string", "description": "IATA code of the airport, 3 letters.", "example": "GRU" }, "name": { "type": "string", "nullable": true, "description": "Official name of the airport. `null` when unknown.", "example": "São Paulo/Guarulhos International Airport" }, "shortAddress": { "type": "string", "nullable": true, "description": "Readable single-line address of the airport. `null` when unknown.", "example": "Guarulhos, SP, Brazil" }, "locality": { "type": "string", "nullable": true, "description": "City the airport sits in. `null` when unknown.", "example": "Guarulhos" }, "administrativeArea": { "type": "string", "nullable": true, "description": "State, as its short code. `null` when unknown.", "example": "SP" }, "phoneNumbers": { "type": "array", "items": { "type": "string", "example": "551133334444" }, "description": "Contact phone numbers of the airport, digits only. Empty when none is registered.\n\n---\n\nExample: `[\"551133334444\"]`" } }, "required": [ "iata", "name", "shortAddress", "locality", "administrativeArea", "phoneNumbers" ], "description": "Airport the flight leaves from." }, "destination": { "type": "object", "properties": { "iata": { "type": "string", "description": "IATA code of the airport, 3 letters.", "example": "GRU" }, "name": { "type": "string", "nullable": true, "description": "Official name of the airport. `null` when unknown.", "example": "São Paulo/Guarulhos International Airport" }, "shortAddress": { "type": "string", "nullable": true, "description": "Readable single-line address of the airport. `null` when unknown.", "example": "Guarulhos, SP, Brazil" }, "locality": { "type": "string", "nullable": true, "description": "City the airport sits in. `null` when unknown.", "example": "Guarulhos" }, "administrativeArea": { "type": "string", "nullable": true, "description": "State, as its short code. `null` when unknown.", "example": "SP" }, "phoneNumbers": { "type": "array", "items": { "type": "string", "example": "551133334444" }, "description": "Contact phone numbers of the airport, digits only. Empty when none is registered.\n\n---\n\nExample: `[\"551133334444\"]`" } }, "required": [ "iata", "name", "shortAddress", "locality", "administrativeArea", "phoneNumbers" ], "description": "Airport the flight arrives at.", "example": { "iata": "SDU", "name": "Rio de Janeiro/Santos Dumont Airport", "shortAddress": "Rio de Janeiro, RJ, Brazil", "locality": "Rio de Janeiro", "administrativeArea": "RJ", "phoneNumbers": [ "552133339999" ] } }, "flightNumber": { "type": "string", "description": "Number of the flight, without the airline's code.", "example": "3101" }, "departureDate": { "type": "string", "description": "Departure date and time in the local time of the departure airport, as `YYYY-MM-DDTHH:mm:ss` with no time zone.", "example": "2026-11-02T08:30:00" }, "arrivalDate": { "type": "string", "description": "Arrival date and time in the local time of the arrival airport, as `YYYY-MM-DDTHH:mm:ss` with no time zone.", "example": "2026-11-02T09:35:00" }, "flightType": { "type": "string", "enum": [ "CHARTER", "ALLOTMENT", "REGULAR" ], "description": "Kind of flight: `REGULAR`, `CHARTER` or `ALLOTMENT`.", "example": "REGULAR" }, "duration": { "type": "string", "description": "Duration of the flight, as `HH:mm`.", "example": "01:05" }, "equipment": { "type": "string", "nullable": true, "description": "Aircraft scheduled for the flight, as the airline identifies it. `null` when not informed.", "example": "32Q" }, "cabin": { "type": "string", "enum": [ "ECONOMY", "PREMIUM_ECONOMY", "BUSINESS", "FIRST_CLASS", "UNDEFINED" ], "description": "Cabin booked for the flight.", "example": "ECONOMY" }, "class": { "type": "string", "nullable": true, "description": "Booking class (RBD) priced for the flight. Each airline defines its own codes. `null` when the airline does not expose it.", "example": "Y" }, "fareBasis": { "type": "string", "nullable": true, "description": "Fare basis code priced for the flight. Each airline defines its own codes. `null` when the airline does not expose it.", "example": "YOW" }, "flightInfo": { "description": "Live information about the flight. `null` until it is first collected, as the departure approaches.", "example": null, "type": "object", "properties": { "state": { "type": "string", "nullable": true, "enum": [ "SCHEDULED", "OUT_GATE", "IN_AIR", "LANDED", "IN_GATE", "CANCELED", "PROPOSED", "UNKNOWN", null ], "description": "Operational state of the flight. `null` when there is no live status yet.", "example": "SCHEDULED" }, "updatedAt": { "type": "string", "nullable": true, "description": "When the live status was captured. `null` when there is no live status yet.", "example": "2026-11-01T18:00:00.000Z" }, "aircraft": { "description": "Aircraft operating the flight. `null` when not known yet.", "type": "object", "properties": { "registration": { "type": "string", "nullable": true, "description": "Tail registration of the aircraft. `null` when not known yet.", "example": "PR-XBA" }, "type": { "type": "string", "nullable": true, "description": "ICAO code of the aircraft type. `null` when not known yet.", "example": "A21N" } }, "required": [ "registration", "type" ], "nullable": true }, "departure": { "type": "object", "properties": { "terminal": { "type": "string", "nullable": true, "description": "Terminal at the airport. `null` when not reported yet.", "example": "2" }, "gate": { "type": "string", "nullable": true, "description": "Gate at the airport. `null` when not reported yet.", "example": "B12" }, "baggage": { "type": "string", "nullable": true, "description": "Baggage belt, reported for arrivals only. `null` for departures and when not reported yet.", "example": "04" }, "estimatedTime": { "type": "string", "nullable": true, "description": "Estimated time at the gate, in UTC (ISO 8601). `null` when not known yet.", "example": "2026-11-02T11:30:00.000Z" }, "actualTime": { "type": "string", "nullable": true, "description": "Actual time at the gate, in UTC (ISO 8601), reported once the flight operates. `null` before that.", "example": "2026-11-02T11:34:00.000Z" }, "timeliness": { "type": "string", "nullable": true, "description": "Punctuality of the flight, such as `OnTime`, `Early` or `Delayed`. `null` when not known.", "example": "OnTime" }, "delayMinutes": { "type": "number", "nullable": true, "description": "Delay in minutes; negative when the flight is ahead of schedule. `null` when not known.", "example": 4 } }, "required": [ "terminal", "gate", "baggage", "estimatedTime", "actualTime", "timeliness", "delayMinutes" ], "description": "Live status at the departure airport." }, "arrival": { "type": "object", "properties": { "terminal": { "type": "string", "nullable": true, "description": "Terminal at the airport. `null` when not reported yet.", "example": "2" }, "gate": { "type": "string", "nullable": true, "description": "Gate at the airport. `null` when not reported yet.", "example": "B12" }, "baggage": { "type": "string", "nullable": true, "description": "Baggage belt, reported for arrivals only. `null` for departures and when not reported yet.", "example": "04" }, "estimatedTime": { "type": "string", "nullable": true, "description": "Estimated time at the gate, in UTC (ISO 8601). `null` when not known yet.", "example": "2026-11-02T11:30:00.000Z" }, "actualTime": { "type": "string", "nullable": true, "description": "Actual time at the gate, in UTC (ISO 8601), reported once the flight operates. `null` before that.", "example": "2026-11-02T11:34:00.000Z" }, "timeliness": { "type": "string", "nullable": true, "description": "Punctuality of the flight, such as `OnTime`, `Early` or `Delayed`. `null` when not known.", "example": "OnTime" }, "delayMinutes": { "type": "number", "nullable": true, "description": "Delay in minutes; negative when the flight is ahead of schedule. `null` when not known.", "example": 4 } }, "required": [ "terminal", "gate", "baggage", "estimatedTime", "actualTime", "timeliness", "delayMinutes" ], "description": "Live status at the arrival airport." } }, "required": [ "state", "updatedAt", "aircraft", "departure", "arrival" ], "nullable": true } }, "required": [ "airline", "operation", "origin", "destination", "flightNumber", "departureDate", "arrivalDate", "flightType", "duration", "equipment", "cabin", "class", "fareBasis", "flightInfo" ], "description": "One flight of a journey. A journey with connections has several." }, "description": "Flights of the journey, in chronological order, connections included." } }, "required": [ "id", "direction", "origin", "destination", "departureDate", "arrivalDate", "duration", "segments" ], "description": "One leg of the itinerary: the whole way from an origin to a destination, connections included." }, "description": "Legs of the itinerary, in travel order: one for a one-way trip, two (outbound and return) for a round trip." }, "tickets": { "type": "array", "items": { "type": "object", "properties": { "passengerId": { "type": "string", "description": "ID of the passenger holding this ticket — one of the trip's `passengers[]`. Omitted only if the passenger could not be matched to the trip's passengers.", "example": "6710a3f2c9e77b0012a4d5e1" }, "fareDescription": { "type": "string", "description": "Readable description of the fare of the ticket.", "example": "GRU to SDU, LATAM Airlines, Economy" }, "ticketNumber": { "type": "string", "nullable": true, "description": "Number of the ticket, as the airline issued it. `null` until the ticket is issued.", "example": null }, "fares": { "type": "array", "items": { "type": "object", "properties": { "journeyId": { "type": "string", "nullable": true, "description": "ID of the journey this fare covers — a `journeys[].id`. `null` when the fare covers the whole itinerary.", "example": "jour_V1StGXR8Z5jdHi6BmyT2k" }, "currency": { "type": "string", "description": "Currency, as the ISO 4217 alphabetic code.", "example": "BRL" }, "originalAmount": { "type": "number", "description": "Fare before discounts and fees, in cents.", "example": 95000 }, "discountAmount": { "type": "number", "description": "Discount applied to the fare, in cents.", "example": 3010 }, "feeAmount": { "type": "number", "description": "Fees added to the fare, in cents.", "example": 0 }, "amount": { "type": "number", "description": "Total charged for the fare, in cents: `originalAmount` - `discountAmount` + `feeAmount`.", "example": 91990 }, "cancellationPolicies": { "type": "object", "properties": { "refundable": { "type": "boolean", "description": "Whether cancelling gives any money back.", "example": true }, "immediateFine": { "type": "boolean", "description": "Whether a fine applies to a cancellation made right after the booking.", "example": false }, "penalties": { "type": "array", "items": { "type": "object", "properties": { "from": { "type": "string", "description": "First day (`YYYY-MM-DD`) on which this tier applies.", "example": "2026-10-25" }, "currency": { "type": "string", "description": "Currency, as the ISO 4217 alphabetic code.", "example": "BRL" }, "fineAmount": { "type": "number", "nullable": true, "description": "Fine charged for cancelling from `from` onward, in cents. `null` when the amount is not available.", "example": 15000 } }, "required": [ "from", "currency", "fineAmount" ], "description": "One tier of a cancellation penalty schedule." }, "description": "Penalty tiers, each in effect from its own date. Empty when no scheduled penalty applies." } }, "required": [ "refundable", "immediateFine", "penalties" ], "description": "Cancellation rules of the fare." }, "changePolicies": { "type": "object", "properties": { "canChange": { "type": "boolean", "description": "Whether the fare allows the booking to be changed.", "example": true }, "immediateFine": { "type": "boolean", "description": "Whether a fine applies to a change made right after the booking.", "example": false }, "penalties": { "type": "array", "items": { "type": "object", "properties": { "from": { "type": "string", "description": "First day (`YYYY-MM-DD`) on which this tier applies.", "example": "2026-10-25" }, "currency": { "type": "string", "description": "Currency, as the ISO 4217 alphabetic code.", "example": "BRL" }, "fineAmount": { "type": "number", "nullable": true, "description": "Fine charged for changing the booking from `from` onward, in cents. `null` when the amount is not available.", "example": 8000 } }, "required": [ "from", "currency", "fineAmount" ], "description": "One tier of a change penalty schedule." }, "description": "Penalty tiers, each in effect from its own date. Empty when no scheduled penalty applies." } }, "required": [ "canChange", "immediateFine", "penalties" ], "description": "Change rules of the fare." } }, "required": [ "journeyId", "currency", "originalAmount", "discountAmount", "feeAmount", "amount", "cancellationPolicies", "changePolicies" ], "description": "The fare of a ticket for one journey, or for the whole itinerary. Amounts are integers in cents." }, "description": "Fares of the ticket: one per journey, or a single one for the whole itinerary." }, "segments": { "type": "array", "items": { "type": "object", "properties": { "flightNumber": { "type": "string", "description": "Number of the flight this ticket covers, without the airline's code. It matches the `flightNumber` of one of the journeys' `segments`.", "example": "3101" }, "cabin": { "type": "string", "enum": [ "ECONOMY", "PREMIUM_ECONOMY", "BUSINESS", "FIRST_CLASS", "UNDEFINED" ], "description": "Cabin of the ticket on this flight.", "example": "ECONOMY" }, "class": { "type": "string", "nullable": true, "description": "Booking class (RBD) of the ticket on this flight. Each airline defines its own codes. `null` when the airline does not expose it.", "example": "Y" }, "fareBasis": { "type": "string", "nullable": true, "description": "Fare basis code of the ticket on this flight. Each airline defines its own codes. `null` when the airline does not expose it.", "example": "YOW" }, "baggages": { "type": "array", "items": { "type": "object", "properties": { "quantity": { "type": "number", "description": "Number of pieces included in the allowance.", "example": 1 }, "weight": { "type": "number", "nullable": true, "description": "Weight allowed per piece, in kg. `null` when the airline sets no weight limit per piece.", "example": 23 }, "type": { "type": "string", "enum": [ "CHECKED", "CARRY_ON", "PERSONAL_ITEM" ], "description": "Kind of baggage: `CHECKED`, `CARRY_ON` or `PERSONAL_ITEM`.", "example": "CHECKED" } }, "required": [ "quantity", "weight", "type" ], "description": "A baggage allowance of a ticket on one flight." }, "description": "Baggage allowance of the ticket on this flight. Empty for an infant on an adult's lap." } }, "required": [ "flightNumber", "cabin", "class", "fareBasis", "baggages" ], "description": "What a ticket covers on one flight of the itinerary: the cabin, the fare codes and the baggage allowance." }, "description": "What the ticket covers on each flight of the itinerary." } }, "required": [ "fareDescription", "ticketNumber", "fares", "segments" ], "description": "The ticket of one passenger. It covers the whole itinerary, with a fare per journey or a single fare for all of it." }, "description": "Tickets of the booking, one per passenger, each covering the whole itinerary." }, "locators": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "Kind of reference, such as `PNR` for an airline's booking code.", "example": "PNR" }, "code": { "type": "string", "description": "The reference itself, as the supplier issued it.", "example": "ABC123" } }, "required": [ "type", "code" ], "description": "A reference that identifies the booking with the supplier, such as an airline's booking code." }, "description": "Booking references issued by the airlines. Empty until the reservation is confirmed." }, "flightInfoUpdatedAt": { "type": "string", "nullable": true, "description": "When the live flight information was last collected. `null` until it is first collected.", "example": null, "format": "date-time" } }, "required": [ "journeys", "tickets", "locators", "flightInfoUpdatedAt" ], "description": "The booked flight: itinerary, the ticket of each passenger (by ID) with its fares and baggage, and reservation locators. This is the shape of `productSnapshot` when the trip's `vertical` is `AIR`. Amounts are integers in cents.", "title": "Air trip" }, { "type": "object", "properties": { "hotel": { "type": "object", "properties": { "name": { "type": "string", "description": "Official name of the hotel.", "example": "Hotel Paulista Plaza" }, "chain": { "type": "object", "properties": { "brandName": { "type": "string", "nullable": true, "description": "Brand within the chain. `null` when not informed.", "example": "Ibis" }, "chainName": { "type": "string", "nullable": true, "description": "Name of the chain. `null` for an independent hotel.", "example": "Accor" }, "logo": { "type": "string", "nullable": true, "description": "URL of the chain's logo. `null` when the hotel has no chain with a registered logo.", "example": "https://cdn.example.com/hotels/ibis.svg" } }, "required": [ "brandName", "chainName", "logo" ], "description": "Chain and brand of the hotel." }, "shortAddress": { "type": "string", "nullable": true, "description": "Readable single-line address of the hotel. `null` when unknown.", "example": "Av. Paulista, 1500, São Paulo, SP, Brazil" }, "phoneNumbers": { "type": "array", "items": { "type": "string", "example": "551133335555" }, "description": "Contact phone numbers of the hotel, digits only. Empty when none is registered.\n\n---\n\nExample: `[\"551133335555\"]`" }, "locality": { "type": "string", "nullable": true, "description": "City the hotel sits in. `null` when unknown.", "example": "São Paulo" }, "administrativeArea": { "type": "string", "nullable": true, "description": "State, as its short code. `null` when unknown.", "example": "SP" }, "checkInTime": { "type": "string", "nullable": true, "description": "Time of day, in the hotel's local time (`HH:mm`), from which guests can check in. `null` when unknown.", "example": "14:00" }, "checkOutTime": { "type": "string", "nullable": true, "description": "Time of day, in the hotel's local time (`HH:mm`), by which guests must check out. `null` when unknown.", "example": "12:00" } }, "required": [ "name", "chain", "shortAddress", "phoneNumbers", "locality", "administrativeArea", "checkInTime", "checkOutTime" ], "description": "Hotel where the stay is booked." }, "checkIn": { "type": "string", "description": "Check-in date (`YYYY-MM-DD`).", "example": "2026-11-02" }, "checkOut": { "type": "string", "description": "Check-out date (`YYYY-MM-DD`).", "example": "2026-11-04" }, "rooms": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the room, as the hotel offers it.", "example": "Standard Room, 1 Queen Bed" }, "fare": { "type": "object", "properties": { "currency": { "type": "string", "description": "Currency, as the ISO 4217 alphabetic code.", "example": "BRL" }, "originalAmount": { "type": "number", "description": "Fare before discounts and fees, in cents.", "example": 120000 }, "discountAmount": { "type": "number", "description": "Discount applied to the fare, in cents.", "example": 8000 }, "feeAmount": { "type": "number", "description": "Fees added to the fare, in cents.", "example": 0 }, "amount": { "type": "number", "description": "Total charged for the fare, in cents: `originalAmount` - `discountAmount` + `feeAmount`.", "example": 112000 }, "boardType": { "type": "string", "enum": [ "ONLY_ROOM", "BREAKFAST", "HALF_BOARD", "FULL_BOARD", "ALL_INCLUSIVE" ], "description": "Meals included in the fare.", "example": "BREAKFAST" }, "cancellationPolicies": { "type": "object", "properties": { "refundable": { "type": "boolean", "description": "Whether cancelling gives any money back.", "example": true }, "immediateFine": { "type": "boolean", "description": "Whether a fine applies to a cancellation made right after the booking.", "example": false }, "penalties": { "type": "array", "items": { "type": "object", "properties": { "from": { "type": "string", "description": "First day (`YYYY-MM-DD`) on which this tier applies.", "example": "2026-10-25" }, "currency": { "type": "string", "description": "Currency, as the ISO 4217 alphabetic code.", "example": "BRL" }, "fineAmount": { "type": "number", "nullable": true, "description": "Fine charged for cancelling from `from` onward, in cents. `null` when the amount is not available.", "example": 15000 } }, "required": [ "from", "currency", "fineAmount" ], "description": "One tier of a cancellation penalty schedule." }, "description": "Penalty tiers, each in effect from its own date. Empty when no scheduled penalty applies." } }, "required": [ "refundable", "immediateFine", "penalties" ], "description": "Cancellation rules of the fare." } }, "required": [ "currency", "originalAmount", "discountAmount", "feeAmount", "amount", "boardType", "cancellationPolicies" ], "description": "Fare of the room." }, "passengersId": { "type": "array", "items": { "type": "string", "example": "6710a3f2c9e77b0012a4d5e1" }, "description": "IDs of the passengers staying in this room — the trip's `passengers[]`.\n\n---\n\nExample: `[\"6710a3f2c9e77b0012a4d5e1\"]`" } }, "required": [ "name", "fare", "passengersId" ], "description": "A booked room." }, "description": "Rooms booked for the stay." }, "locators": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "Kind of reference, such as `PNR` for an airline's booking code.", "example": "PNR" }, "code": { "type": "string", "description": "The reference itself, as the supplier issued it.", "example": "ABC123" } }, "required": [ "type", "code" ], "description": "A reference that identifies the booking with the supplier, such as an airline's booking code." }, "description": "Booking references issued by the hotel. Empty until the reservation is confirmed." } }, "required": [ "hotel", "checkIn", "checkOut", "rooms", "locators" ], "description": "The booked hotel stay: the hotel, the dates, the rooms with their fares and guests (by ID), and the reservation locators. This is the shape of `productSnapshot` when the trip's `vertical` is `HOTEL`. Amounts are integers in cents.", "title": "Hotel trip" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "DIRECT", "CONNECTION", "ONE_STOP" ], "description": "Kind of trip: `DIRECT`, `CONNECTION` or `ONE_STOP`.", "example": "DIRECT" }, "origin": { "type": "object", "properties": { "locality": { "type": "string", "description": "City the station sits in.", "example": "São Paulo" }, "administrativeArea": { "type": "string", "description": "State, as its short code.", "example": "SP" }, "name": { "type": "string", "nullable": true, "description": "Official name of the station. `null` when unknown.", "example": "Terminal Rodoviário Tietê" }, "shortAddress": { "type": "string", "nullable": true, "description": "Readable single-line address of the station. `null` when unknown.", "example": "Av. Cruzeiro do Sul, 1800, São Paulo, SP, Brazil" }, "phoneNumbers": { "type": "array", "items": { "type": "string", "example": "551133336666" }, "description": "Contact phone numbers of the station, digits only. Empty when none is registered.\n\n---\n\nExample: `[\"551133336666\"]`" } }, "required": [ "locality", "administrativeArea", "name", "shortAddress", "phoneNumbers" ], "description": "Station the trip starts at." }, "destination": { "type": "object", "properties": { "locality": { "type": "string", "description": "City the station sits in.", "example": "São Paulo" }, "administrativeArea": { "type": "string", "description": "State, as its short code.", "example": "SP" }, "name": { "type": "string", "nullable": true, "description": "Official name of the station. `null` when unknown.", "example": "Terminal Rodoviário Tietê" }, "shortAddress": { "type": "string", "nullable": true, "description": "Readable single-line address of the station. `null` when unknown.", "example": "Av. Cruzeiro do Sul, 1800, São Paulo, SP, Brazil" }, "phoneNumbers": { "type": "array", "items": { "type": "string", "example": "551133336666" }, "description": "Contact phone numbers of the station, digits only. Empty when none is registered.\n\n---\n\nExample: `[\"551133336666\"]`" } }, "required": [ "locality", "administrativeArea", "name", "shortAddress", "phoneNumbers" ], "description": "Station the trip ends at.", "example": { "locality": "Rio de Janeiro", "administrativeArea": "RJ", "name": "Rodoviária Novo Rio", "shortAddress": "Av. Francisco Bicalho, 1, Rio de Janeiro, RJ, Brazil", "phoneNumbers": [ "552133338888" ] } }, "departureDate": { "type": "string", "description": "Departure date and time in the local time of the origin station, as `YYYY-MM-DDTHH:mm:ss` with no time zone.", "example": "2026-11-02T08:30:00" }, "arrivalDate": { "type": "string", "description": "Arrival date and time in the local time of the destination station, as `YYYY-MM-DDTHH:mm:ss` with no time zone.", "example": "2026-11-02T14:45:00" }, "company": { "type": "object", "properties": { "name": { "type": "string", "description": "Commercial name of the company.", "example": "Expresso Brasileiro" }, "logo": { "type": "string", "nullable": true, "description": "URL of the company's logo. `null` when there is none.", "example": "https://cdn.example.com/bus/expresso-brasileiro.png" } }, "required": [ "name", "logo" ], "description": "Company that operates the trip." }, "passengerId": { "type": "string", "description": "ID of the passenger travelling on this ticket — one of the trip's `passengers[]`. Omitted only if the passenger could not be matched to the trip's passengers.", "example": "6710a3f2c9e77b0012a4d5e1" }, "segments": { "type": "array", "items": { "type": "object", "properties": { "seatNumber": { "type": "number", "description": "Seat reserved on the segment.", "example": 12 }, "serviceClass": { "type": "string", "enum": [ "SLEEPER_BED", "BED", "SEMI_BED", "EXECUTIVE", "CONVENTIONAL", "UNDEFINED" ], "description": "Class of service booked for the segment.", "example": "EXECUTIVE" }, "origin": { "type": "object", "properties": { "locality": { "type": "string", "description": "City the station sits in.", "example": "São Paulo" }, "administrativeArea": { "type": "string", "description": "State, as its short code.", "example": "SP" }, "name": { "type": "string", "nullable": true, "description": "Official name of the station. `null` when unknown.", "example": "Terminal Rodoviário Tietê" }, "shortAddress": { "type": "string", "nullable": true, "description": "Readable single-line address of the station. `null` when unknown.", "example": "Av. Cruzeiro do Sul, 1800, São Paulo, SP, Brazil" }, "phoneNumbers": { "type": "array", "items": { "type": "string", "example": "551133336666" }, "description": "Contact phone numbers of the station, digits only. Empty when none is registered.\n\n---\n\nExample: `[\"551133336666\"]`" } }, "required": [ "locality", "administrativeArea", "name", "shortAddress", "phoneNumbers" ], "description": "Station the segment leaves from." }, "destination": { "type": "object", "properties": { "locality": { "type": "string", "description": "City the station sits in.", "example": "São Paulo" }, "administrativeArea": { "type": "string", "description": "State, as its short code.", "example": "SP" }, "name": { "type": "string", "nullable": true, "description": "Official name of the station. `null` when unknown.", "example": "Terminal Rodoviário Tietê" }, "shortAddress": { "type": "string", "nullable": true, "description": "Readable single-line address of the station. `null` when unknown.", "example": "Av. Cruzeiro do Sul, 1800, São Paulo, SP, Brazil" }, "phoneNumbers": { "type": "array", "items": { "type": "string", "example": "551133336666" }, "description": "Contact phone numbers of the station, digits only. Empty when none is registered.\n\n---\n\nExample: `[\"551133336666\"]`" } }, "required": [ "locality", "administrativeArea", "name", "shortAddress", "phoneNumbers" ], "description": "Station the segment arrives at.", "example": { "locality": "Rio de Janeiro", "administrativeArea": "RJ", "name": "Rodoviária Novo Rio", "shortAddress": "Av. Francisco Bicalho, 1, Rio de Janeiro, RJ, Brazil", "phoneNumbers": [ "552133338888" ] } }, "departureDate": { "type": "string", "description": "Departure date and time in the local time of the origin station, as `YYYY-MM-DDTHH:mm:ss` with no time zone.", "example": "2026-11-02T08:30:00" }, "arrivalDate": { "type": "string", "description": "Arrival date and time in the local time of the destination station, as `YYYY-MM-DDTHH:mm:ss` with no time zone.", "example": "2026-11-02T14:45:00" }, "duration": { "type": "string", "nullable": true, "description": "Duration of the leg, as `HH:mm`. `null` when not available.", "example": "06:15" }, "fare": { "type": "object", "properties": { "originalAmount": { "type": "number", "description": "Fare before discounts and fees, in cents.", "example": 18000 }, "discountAmount": { "type": "number", "description": "Discount applied to the fare, in cents.", "example": 1000 }, "feeAmount": { "type": "number", "description": "Fees added to the fare, in cents.", "example": 500 }, "amount": { "type": "number", "description": "Total charged for the fare, in cents: `originalAmount` - `discountAmount` + `feeAmount`.", "example": 17500 }, "currency": { "type": "string", "description": "Currency, as the ISO 4217 alphabetic code.", "example": "BRL" }, "cancellationPolicies": { "type": "object", "properties": { "refundable": { "type": "boolean", "description": "Whether cancelling gives any money back.", "example": true }, "immediateFine": { "type": "boolean", "description": "Whether a fine applies to a cancellation made right after the booking.", "example": false }, "penalties": { "type": "array", "items": { "type": "object", "properties": { "from": { "type": "string", "description": "First day (`YYYY-MM-DD`) on which this tier applies.", "example": "2026-10-25" }, "currency": { "type": "string", "description": "Currency, as the ISO 4217 alphabetic code.", "example": "BRL" }, "fineAmount": { "type": "number", "nullable": true, "description": "Fine charged for cancelling from `from` onward, in cents. `null` when the amount is not available.", "example": 15000 } }, "required": [ "from", "currency", "fineAmount" ], "description": "One tier of a cancellation penalty schedule." }, "description": "Penalty tiers, each in effect from its own date. Empty when no scheduled penalty applies." } }, "required": [ "refundable", "immediateFine", "penalties" ], "description": "Cancellation rules of the fare." } }, "required": [ "originalAmount", "discountAmount", "feeAmount", "amount", "currency", "cancellationPolicies" ], "description": "Fare of the segment." }, "company": { "type": "object", "properties": { "name": { "type": "string", "description": "Commercial name of the company.", "example": "Expresso Brasileiro" }, "logo": { "type": "string", "nullable": true, "description": "URL of the company's logo. `null` when there is none.", "example": "https://cdn.example.com/bus/expresso-brasileiro.png" } }, "required": [ "name", "logo" ], "description": "Operator running this leg." } }, "required": [ "seatNumber", "serviceClass", "origin", "destination", "departureDate", "arrivalDate", "duration", "fare", "company" ], "description": "One leg of the bus trip, with the seat booked on it." }, "description": "Segments of the trip, one per leg, each with its seat, fare and operator." }, "routeDirection": { "type": "string", "enum": [ "DEPARTURE", "RETURN" ], "description": "Whether this booking is the outbound trip (`DEPARTURE`) or the return trip (`RETURN`).", "example": "DEPARTURE" }, "boardingInfo": { "description": "Boarding pass and, per leg, platform and ticket codes. `null` until it is first collected, as the departure approaches.", "example": null, "type": "object", "properties": { "boardingPass": { "type": "string", "nullable": true, "description": "The boarding pass PDF, base64-encoded. `null` when not available yet.", "example": "JVBERi0xLjcK" }, "routes": { "type": "array", "items": { "type": "object", "properties": { "origin": { "type": "string", "description": "City the leg starts in.", "example": "São Paulo" }, "destination": { "type": "string", "description": "City the leg ends in.", "example": "Rio de Janeiro" }, "platform": { "type": "string", "nullable": true, "description": "Boarding platform at the origin station. `null` when not assigned or not applicable.", "example": "14" }, "departureDate": { "type": "string", "description": "Departure date and time in local time, as `YYYY-MM-DDTHH:mm:ss` with no time zone.", "example": "2026-11-02T08:30:00" }, "arrivalDate": { "type": "string", "description": "Arrival date and time in local time, as `YYYY-MM-DDTHH:mm:ss` with no time zone.", "example": "2026-11-02T14:45:00" }, "tickets": { "type": "array", "items": { "type": "object", "properties": { "passengerId": { "type": "string", "description": "ID of the passenger the ticket belongs to — one of the trip's `passengers[]`. Omitted only if the passenger could not be matched to the trip's passengers.", "example": "6710a3f2c9e77b0012a4d5e1" }, "locators": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "Kind of reference, such as `PNR` for an airline's booking code.", "example": "PNR" }, "code": { "type": "string", "description": "The reference itself, as the supplier issued it.", "example": "ABC123" } }, "required": [ "type", "code" ], "description": "A reference that identifies the booking with the supplier, such as an airline's booking code." }, "description": "Booking references of the ticket. Empty when none is available." }, "ticketCode": { "type": "string", "nullable": true, "description": "Code of the ticket. `null` when not available.", "example": "EB123456" }, "qrCode": { "type": "string", "nullable": true, "description": "The boarding QR code image, base64-encoded. `null` when not available.", "example": "iVBORw0KGgo=" }, "bpeNumber": { "type": "string", "nullable": true, "description": "Number of the electronic bus ticket (BP-e). `null` when not available.", "example": "35261112345678000190630010000123451000123456" } }, "required": [ "locators", "ticketCode", "qrCode", "bpeNumber" ], "description": "The boarding ticket of one passenger on one leg." }, "description": "Tickets of the leg, one per passenger." } }, "required": [ "origin", "destination", "platform", "departureDate", "arrivalDate", "tickets" ], "description": "The boarding details of one leg of the trip." }, "description": "Boarding details per leg. A connection has two legs; direct and one-stop trips have one." } }, "required": [ "boardingPass", "routes" ], "nullable": true } }, "required": [ "type", "origin", "destination", "departureDate", "arrivalDate", "company", "segments", "routeDirection", "boardingInfo" ], "description": "The booked bus trip of one passenger (by ID): stations, operator, the legs with their seats and fares, and boarding information. This is the shape of `productSnapshot` when the trip's `vertical` is `BUS`. Amounts are integers in cents.", "title": "Bus trip" }, { "type": "object", "properties": { "groupName": { "type": "string", "description": "Commercial group the vehicle belongs to, such as `ECONOMY` or `SUV`.", "example": "ECONOMY" }, "class": { "type": "string", "description": "Class of the vehicle within its group.", "example": "INTERMEDIATE" }, "name": { "type": "string", "description": "Name of the vehicle, as the rental company displays it.", "example": "Fiat Mobi" }, "sipp": { "type": "string", "description": "SIPP code that classifies the vehicle by size, doors, transmission and fuel.", "example": "ECMR" }, "rentalCompany": { "type": "object", "properties": { "code": { "type": "string", "description": "Code of the rental company.", "example": "LOC" }, "name": { "type": "string", "description": "Commercial name of the rental company.", "example": "Localiza" }, "logo": { "type": "string", "nullable": true, "description": "URL of the rental company's logo. `null` when the company has no registered logo.", "example": "https://cdn.example.com/rentals/localiza.svg" } }, "required": [ "code", "name", "logo" ], "description": "Rental company that holds the booking." }, "pickUpLocation": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the rental location.", "example": "Localiza Aeroporto Guarulhos (GRU)" }, "phoneNumbers": { "type": "array", "items": { "type": "string", "example": "551133337777" }, "description": "Contact phone numbers of the location, digits only. Empty when none is registered.\n\n---\n\nExample: `[\"551133337777\"]`" }, "shortAddress": { "type": "string", "nullable": true, "description": "Readable single-line address of the location. `null` when unknown.", "example": "Rod. Hélio Smidt, s/n, Guarulhos, SP, Brazil" }, "locality": { "type": "string", "nullable": true, "description": "City the location sits in. `null` when unknown.", "example": "Guarulhos" }, "administrativeArea": { "type": "string", "nullable": true, "description": "State, as its short code. `null` when unknown.", "example": "SP" } }, "required": [ "name", "phoneNumbers", "shortAddress", "locality", "administrativeArea" ], "description": "Where the vehicle is picked up." }, "dropOffLocation": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the rental location.", "example": "Localiza Aeroporto Guarulhos (GRU)" }, "phoneNumbers": { "type": "array", "items": { "type": "string", "example": "551133337777" }, "description": "Contact phone numbers of the location, digits only. Empty when none is registered.\n\n---\n\nExample: `[\"551133337777\"]`" }, "shortAddress": { "type": "string", "nullable": true, "description": "Readable single-line address of the location. `null` when unknown.", "example": "Rod. Hélio Smidt, s/n, Guarulhos, SP, Brazil" }, "locality": { "type": "string", "nullable": true, "description": "City the location sits in. `null` when unknown.", "example": "Guarulhos" }, "administrativeArea": { "type": "string", "nullable": true, "description": "State, as its short code. `null` when unknown.", "example": "SP" } }, "required": [ "name", "phoneNumbers", "shortAddress", "locality", "administrativeArea" ], "description": "Where the vehicle is dropped off." }, "pickUpDate": { "type": "string", "description": "Pick-up date and time in the local time of the pick-up location, as `YYYY-MM-DDTHH:mm:ss` with no time zone.", "example": "2026-11-02T10:00:00" }, "dropOffDate": { "type": "string", "description": "Drop-off date and time in the local time of the drop-off location, as `YYYY-MM-DDTHH:mm:ss` with no time zone.", "example": "2026-11-04T10:00:00" }, "rentals": { "type": "array", "items": { "type": "object", "properties": { "description": { "type": "string", "nullable": true, "description": "Readable description of the rental option. `null` when not provided.", "example": "Compact car, air conditioning, unlimited mileage" }, "fare": { "type": "object", "properties": { "originalAmount": { "type": "number", "description": "Fare before discounts and fees, in cents.", "example": 36000 }, "discountAmount": { "type": "number", "description": "Discount applied to the fare, in cents.", "example": 2000 }, "feeAmount": { "type": "number", "description": "Fees added to the fare, in cents.", "example": 0 }, "amount": { "type": "number", "description": "Total charged for the fare, in cents: `originalAmount` - `discountAmount` + `feeAmount`.", "example": 34000 }, "currency": { "type": "string", "description": "Currency, as the ISO 4217 alphabetic code.", "example": "BRL" }, "cancellationPolicies": { "type": "object", "properties": { "refundable": { "type": "boolean", "description": "Whether cancelling gives any money back.", "example": true }, "immediateFine": { "type": "boolean", "description": "Whether a fine applies to a cancellation made right after the booking.", "example": false }, "penalties": { "type": "array", "items": { "type": "object", "properties": { "from": { "type": "string", "nullable": true, "description": "First day (`YYYY-MM-DD`) on which this tier applies. `null` when the supplier gave no date.", "example": "2026-10-31" }, "currency": { "type": "string", "description": "Currency, as the ISO 4217 alphabetic code.", "example": "BRL" }, "fineAmount": { "type": "number", "nullable": true, "description": "Fine charged for cancelling from `from` onward, in cents. `null` when the amount is not available.", "example": 12000 } }, "required": [ "from", "currency", "fineAmount" ], "description": "One tier of the cancellation penalty schedule of a rental." }, "description": "Penalty tiers, each in effect from its own date. Empty when no scheduled penalty applies." } }, "required": [ "refundable", "immediateFine", "penalties" ], "description": "Cancellation rules of the fare." } }, "required": [ "originalAmount", "discountAmount", "feeAmount", "amount", "currency", "cancellationPolicies" ], "description": "Fare of the rental." }, "passengersId": { "type": "array", "items": { "type": "string", "example": "6710a3f2c9e77b0012a4d5e1" }, "description": "IDs of the passengers travelling on this rental — the trip's `passengers[]`. Empty when none was assigned.\n\n---\n\nExample: `[\"6710a3f2c9e77b0012a4d5e1\"]`" }, "locators": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "Kind of reference, such as `PNR` for an airline's booking code.", "example": "PNR" }, "code": { "type": "string", "description": "The reference itself, as the supplier issued it.", "example": "ABC123" } }, "required": [ "type", "code" ], "description": "A reference that identifies the booking with the supplier, such as an airline's booking code." }, "description": "Booking references of the rental with the rental company. Empty until the reservation is confirmed." } }, "required": [ "description", "fare", "passengersId", "locators" ], "description": "A booked rental." }, "description": "Rentals booked under this record." }, "locators": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "Kind of reference, such as `PNR` for an airline's booking code.", "example": "PNR" }, "code": { "type": "string", "description": "The reference itself, as the supplier issued it.", "example": "ABC123" } }, "required": [ "type", "code" ], "description": "A reference that identifies the booking with the supplier, such as an airline's booking code." }, "description": "Booking references of the reservation as a whole. Empty until the reservation is confirmed." } }, "required": [ "groupName", "class", "name", "sipp", "rentalCompany", "pickUpLocation", "dropOffLocation", "pickUpDate", "dropOffDate", "rentals", "locators" ], "description": "The booked vehicle rental: the vehicle, the rental company, the pick-up and drop-off places and dates, fares, passengers (by ID) and reservation locators. This is the shape of `productSnapshot` when the trip's `vertical` is `VEHICLE`. Amounts are integers in cents.", "title": "Vehicle trip" } ], "description": "The booked product: the itinerary, stay, ticket or rental as recorded by the travel provider — journeys and flights, the hotel and its rooms, the route and boarding information, the rental — with its fares, policies and booking locators. It does not repeat the trip's own fields (`state`, `status`, the amounts, the dates) and carries no identifier of the travel provider; passengers are referenced by their `id` in `passengers[]`. Its shape depends on `vertical`: a flight (`AIR`), a hotel stay (`HOTEL`), a bus ticket (`BUS`) or a vehicle rental (`VEHICLE`) — see the four schemas below. Omitted until the record is first fetched." }, "cancellation": { "type": "object", "properties": { "quoteId": { "type": "string", "description": "ID of the confirmed cancellation quote." }, "cancelType": { "type": "string", "enum": [ "CREDIT", "REFUND", "MANUAL_CANCEL", "VOID" ], "description": "Kind of cancellation: `VOID` for a trip not issued yet, `REFUND` or `CREDIT` for an issued one, `MANUAL_CANCEL` when the amounts are settled outside the system." }, "originalAmount": { "type": "number", "nullable": true, "description": "What the trip cost, in cents. Omitted when it couldn't be recorded; `null` for `MANUAL_CANCEL`." }, "remainingAmount": { "type": "number", "nullable": true, "description": "What is given back after the fine, in cents. Omitted when it couldn't be recorded; `null` for `MANUAL_CANCEL`." }, "fineAmount": { "type": "number", "nullable": true, "description": "Cancellation fine, in cents. Omitted when it couldn't be recorded; `null` for `MANUAL_CANCEL`." }, "currency": { "type": "string", "description": "Currency of the amounts, as the numeric ISO 4217 code (`986` is BRL)." }, "status": { "type": "string", "description": "Status of the quote when it was confirmed." }, "expiresAt": { "type": "string", "description": "When the quote would have expired.", "format": "date-time" }, "confirmedAt": { "type": "string", "description": "When the cancellation was confirmed.", "format": "date-time" }, "confirmedBy": { "type": "string", "description": "ID of the user who confirmed the cancellation. Omitted when a service did." } }, "required": [ "quoteId", "cancelType" ], "description": "The confirmed cancellation. Omitted until one is confirmed." }, "createdAt": { "type": "string", "description": "When the trip was created.", "example": "2026-10-01T13:45:12.000Z", "format": "date-time" }, "updatedAt": { "type": "string", "description": "When the trip last changed.", "example": "2026-10-01T13:46:03.000Z", "format": "date-time" } }, "required": [ "id", "realmId", "organizationId", "customFields", "vertical", "state", "status", "passengers" ], "description": "A trip: ONE booked product — a flight, a hotel stay, a bus ticket or a vehicle rental — for the organization's passengers, with its lifecycle. Booking several products means creating several trips." }, "examples": { "air-trip": { "summary": "Air trip", "value": { "id": "6711b4c0d8e1a30012b7c9f2", "realmId": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b", "organizationId": "c4bd3f21-dfbd-44e8-8055-68ba15bed410", "createdBy": "e3553bc1-5e20-4e17-b22a-a796fda0aa99", "customFields": { "cost-center": "CC-1020" }, "vertical": "AIR", "state": "RESERVED", "status": "RESERVED", "reservationExpiresAt": "2026-10-02T13:45:12.000Z", "originalAmount": 95000, "discountAmount": 3010, "feeAmount": 0, "totalAmount": 91990, "currency": "986", "passengers": [ { "id": "6710a3f2c9e77b0012a4d5e1", "userId": "e3553bc1-5e20-4e17-b22a-a796fda0aa99", "lead": true, "name": "Mariana Costa", "gender": "FEMALE", "birthDate": "1990-04-17" } ], "productSnapshot": { "journeys": [ { "id": "jour_V1StGXR8Z5jdHi6BmyT2k", "direction": "DEPARTURE", "origin": { "iata": "GRU", "name": "São Paulo/Guarulhos International Airport", "shortAddress": "Guarulhos, SP, Brazil", "locality": "Guarulhos", "administrativeArea": "SP", "phoneNumbers": [ "551133334444" ] }, "destination": { "iata": "SDU", "name": "Rio de Janeiro/Santos Dumont Airport", "shortAddress": "Rio de Janeiro, RJ, Brazil", "locality": "Rio de Janeiro", "administrativeArea": "RJ", "phoneNumbers": [ "552133339999" ] }, "departureDate": "2026-11-02T08:30:00", "arrivalDate": "2026-11-02T09:35:00", "duration": "01:05", "segments": [ { "airline": { "code": "LA", "name": "LATAM Airlines", "logo": "https://cdn.example.com/airlines/LA.png" }, "operation": { "code": "LA", "name": "LATAM Airlines", "logo": "https://cdn.example.com/airlines/LA.png" }, "origin": { "iata": "GRU", "name": "São Paulo/Guarulhos International Airport", "shortAddress": "Guarulhos, SP, Brazil", "locality": "Guarulhos", "administrativeArea": "SP", "phoneNumbers": [ "551133334444" ] }, "destination": { "iata": "SDU", "name": "Rio de Janeiro/Santos Dumont Airport", "shortAddress": "Rio de Janeiro, RJ, Brazil", "locality": "Rio de Janeiro", "administrativeArea": "RJ", "phoneNumbers": [ "552133339999" ] }, "flightNumber": "3101", "departureDate": "2026-11-02T08:30:00", "arrivalDate": "2026-11-02T09:35:00", "flightType": "REGULAR", "duration": "01:05", "equipment": "32Q", "cabin": "ECONOMY", "class": "Y", "fareBasis": "YOW", "flightInfo": null } ] } ], "tickets": [ { "passengerId": "6710a3f2c9e77b0012a4d5e1", "fareDescription": "GRU to SDU, LATAM Airlines, Economy", "ticketNumber": null, "fares": [ { "journeyId": "jour_V1StGXR8Z5jdHi6BmyT2k", "currency": "BRL", "originalAmount": 95000, "discountAmount": 3010, "feeAmount": 0, "amount": 91990, "cancellationPolicies": { "refundable": true, "immediateFine": false, "penalties": [ { "from": "2026-10-25", "currency": "BRL", "fineAmount": 15000 } ] }, "changePolicies": { "canChange": true, "immediateFine": false, "penalties": [ { "from": "2026-10-25", "currency": "BRL", "fineAmount": 8000 } ] } } ], "segments": [ { "flightNumber": "3101", "cabin": "ECONOMY", "class": "Y", "fareBasis": "YOW", "baggages": [ { "quantity": 1, "weight": 23, "type": "CHECKED" } ] } ] } ], "locators": [ { "type": "PNR", "code": "ABC123" } ], "flightInfoUpdatedAt": null }, "createdAt": "2026-10-01T13:45:12.000Z", "updatedAt": "2026-10-01T13:46:03.000Z" } }, "hotel-trip": { "summary": "Hotel trip", "value": { "id": "6711b4c0d8e1a30012b7c9f2", "realmId": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b", "organizationId": "c4bd3f21-dfbd-44e8-8055-68ba15bed410", "createdBy": "e3553bc1-5e20-4e17-b22a-a796fda0aa99", "customFields": { "cost-center": "CC-1020" }, "vertical": "HOTEL", "state": "RESERVED", "status": "RESERVED", "reservationExpiresAt": "2026-10-02T13:45:12.000Z", "originalAmount": 95000, "discountAmount": 3010, "feeAmount": 0, "totalAmount": 91990, "currency": "986", "passengers": [ { "id": "6710a3f2c9e77b0012a4d5e1", "userId": "e3553bc1-5e20-4e17-b22a-a796fda0aa99", "lead": true, "name": "Mariana Costa", "gender": "FEMALE", "birthDate": "1990-04-17" } ], "productSnapshot": { "hotel": { "name": "Hotel Paulista Plaza", "chain": { "brandName": "Ibis", "chainName": "Accor", "logo": "https://cdn.example.com/hotels/ibis.svg" }, "shortAddress": "Av. Paulista, 1500, São Paulo, SP, Brazil", "phoneNumbers": [ "551133335555" ], "locality": "São Paulo", "administrativeArea": "SP", "checkInTime": "14:00", "checkOutTime": "12:00" }, "checkIn": "2026-11-02", "checkOut": "2026-11-04", "rooms": [ { "name": "Standard Room, 1 Queen Bed", "fare": { "currency": "BRL", "originalAmount": 120000, "discountAmount": 8000, "feeAmount": 0, "amount": 112000, "boardType": "BREAKFAST", "cancellationPolicies": { "refundable": true, "immediateFine": false, "penalties": [ { "from": "2026-10-25", "currency": "BRL", "fineAmount": 15000 } ] } }, "passengersId": [ "6710a3f2c9e77b0012a4d5e1" ] } ], "locators": [ { "type": "PNR", "code": "ABC123" } ] }, "createdAt": "2026-10-01T13:45:12.000Z", "updatedAt": "2026-10-01T13:46:03.000Z" } }, "bus-trip": { "summary": "Bus trip", "value": { "id": "6711b4c0d8e1a30012b7c9f2", "realmId": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b", "organizationId": "c4bd3f21-dfbd-44e8-8055-68ba15bed410", "createdBy": "e3553bc1-5e20-4e17-b22a-a796fda0aa99", "customFields": { "cost-center": "CC-1020" }, "vertical": "BUS", "state": "RESERVED", "status": "RESERVED", "reservationExpiresAt": "2026-10-02T13:45:12.000Z", "originalAmount": 95000, "discountAmount": 3010, "feeAmount": 0, "totalAmount": 91990, "currency": "986", "passengers": [ { "id": "6710a3f2c9e77b0012a4d5e1", "userId": "e3553bc1-5e20-4e17-b22a-a796fda0aa99", "lead": true, "name": "Mariana Costa", "gender": "FEMALE", "birthDate": "1990-04-17" } ], "productSnapshot": { "type": "DIRECT", "origin": { "locality": "São Paulo", "administrativeArea": "SP", "name": "Terminal Rodoviário Tietê", "shortAddress": "Av. Cruzeiro do Sul, 1800, São Paulo, SP, Brazil", "phoneNumbers": [ "551133336666" ] }, "destination": { "locality": "Rio de Janeiro", "administrativeArea": "RJ", "name": "Rodoviária Novo Rio", "shortAddress": "Av. Francisco Bicalho, 1, Rio de Janeiro, RJ, Brazil", "phoneNumbers": [ "552133338888" ] }, "departureDate": "2026-11-02T08:30:00", "arrivalDate": "2026-11-02T14:45:00", "company": { "name": "Expresso Brasileiro", "logo": "https://cdn.example.com/bus/expresso-brasileiro.png" }, "passengerId": "6710a3f2c9e77b0012a4d5e1", "segments": [ { "seatNumber": 12, "serviceClass": "EXECUTIVE", "origin": { "locality": "São Paulo", "administrativeArea": "SP", "name": "Terminal Rodoviário Tietê", "shortAddress": "Av. Cruzeiro do Sul, 1800, São Paulo, SP, Brazil", "phoneNumbers": [ "551133336666" ] }, "destination": { "locality": "Rio de Janeiro", "administrativeArea": "RJ", "name": "Rodoviária Novo Rio", "shortAddress": "Av. Francisco Bicalho, 1, Rio de Janeiro, RJ, Brazil", "phoneNumbers": [ "552133338888" ] }, "departureDate": "2026-11-02T08:30:00", "arrivalDate": "2026-11-02T14:45:00", "duration": "06:15", "fare": { "originalAmount": 18000, "discountAmount": 1000, "feeAmount": 500, "amount": 17500, "currency": "BRL", "cancellationPolicies": { "refundable": true, "immediateFine": false, "penalties": [ { "from": "2026-10-25", "currency": "BRL", "fineAmount": 15000 } ] } }, "company": { "name": "Expresso Brasileiro", "logo": "https://cdn.example.com/bus/expresso-brasileiro.png" } } ], "routeDirection": "DEPARTURE", "boardingInfo": null }, "createdAt": "2026-10-01T13:45:12.000Z", "updatedAt": "2026-10-01T13:46:03.000Z" } }, "vehicle-trip": { "summary": "Vehicle trip", "value": { "id": "6711b4c0d8e1a30012b7c9f2", "realmId": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b", "organizationId": "c4bd3f21-dfbd-44e8-8055-68ba15bed410", "createdBy": "e3553bc1-5e20-4e17-b22a-a796fda0aa99", "customFields": { "cost-center": "CC-1020" }, "vertical": "VEHICLE", "state": "RESERVED", "status": "RESERVED", "reservationExpiresAt": "2026-10-02T13:45:12.000Z", "originalAmount": 95000, "discountAmount": 3010, "feeAmount": 0, "totalAmount": 91990, "currency": "986", "passengers": [ { "id": "6710a3f2c9e77b0012a4d5e1", "userId": "e3553bc1-5e20-4e17-b22a-a796fda0aa99", "lead": true, "name": "Mariana Costa", "gender": "FEMALE", "birthDate": "1990-04-17" } ], "productSnapshot": { "groupName": "ECONOMY", "class": "INTERMEDIATE", "name": "Fiat Mobi", "sipp": "ECMR", "rentalCompany": { "code": "LOC", "name": "Localiza", "logo": "https://cdn.example.com/rentals/localiza.svg" }, "pickUpLocation": { "name": "Localiza Aeroporto Guarulhos (GRU)", "phoneNumbers": [ "551133337777" ], "shortAddress": "Rod. Hélio Smidt, s/n, Guarulhos, SP, Brazil", "locality": "Guarulhos", "administrativeArea": "SP" }, "dropOffLocation": { "name": "Localiza Aeroporto Guarulhos (GRU)", "phoneNumbers": [ "551133337777" ], "shortAddress": "Rod. Hélio Smidt, s/n, Guarulhos, SP, Brazil", "locality": "Guarulhos", "administrativeArea": "SP" }, "pickUpDate": "2026-11-02T10:00:00", "dropOffDate": "2026-11-04T10:00:00", "rentals": [ { "description": "Compact car, air conditioning, unlimited mileage", "fare": { "originalAmount": 36000, "discountAmount": 2000, "feeAmount": 0, "amount": 34000, "currency": "BRL", "cancellationPolicies": { "refundable": true, "immediateFine": false, "penalties": [ { "from": "2026-10-31", "currency": "BRL", "fineAmount": 12000 } ] } }, "passengersId": [ "6710a3f2c9e77b0012a4d5e1" ], "locators": [ { "type": "PNR", "code": "ABC123" } ] } ], "locators": [ { "type": "PNR", "code": "ABC123" } ] }, "createdAt": "2026-10-01T13:45:12.000Z", "updatedAt": "2026-10-01T13:46:03.000Z" } } } } } }, "400": { "description": "`CANCELLATION_QUOTE_CANNOT_BE_CONFIRMED` — The quote was already confirmed or processed.\n\n`CANCELLATION_QUOTE_EXPIRED` — The quote passed its `expiresAt`; list the quotes again for a new one.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "CANCELLATION_QUOTE_CANNOT_BE_CONFIRMED", "CANCELLATION_QUOTE_EXPIRED" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "TRAVEL" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b", "code": "CANCELLATION_QUOTE_CANNOT_BE_CONFIRMED", "origin": "TRAVEL", "message": "Cancellation quote status does not allow confirmation" } } } }, "404": { "description": "`TRIP_NOT_FOUND` — No trip with this ID is visible to you in the organization: it doesn't exist, belongs to another organization, or you are neither an organization admin nor a passenger on it.\n\n`CANCELLATION_QUOTE_NOT_FOUND` — The quote doesn't exist for this trip.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "TRIP_NOT_FOUND", "CANCELLATION_QUOTE_NOT_FOUND" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "TRAVEL" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b", "code": "TRIP_NOT_FOUND", "origin": "TRAVEL", "message": "Trip not found" } } } }, "422": { "description": "`BAD_REQUEST` — A path parameter is not a valid ID or the body failed validation; `fields` lists each offending field.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "BAD_REQUEST" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "TRAVEL" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." }, "fields": { "type": "array", "description": "One entry per invalid request field (validation errors only).", "items": { "type": "object", "properties": { "field": { "type": "string", "description": "Path of the invalid field, e.g. `label` or `values[0].value`.", "example": "label" }, "message": { "type": "string", "description": "Why the field was rejected.", "example": "label is required" }, "code": { "type": "string", "description": "`_` — e.g. `LABEL_REQUIRED`, `TYPE_ONE_OF`, `VALUES_VALUE_TYPE_ERROR`.", "example": "LABEL_REQUIRED" }, "values": { "type": "array", "items": { "type": "string" }, "description": "The accepted values, when the field is an enumeration." } }, "required": [ "field", "message", "code" ] } } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "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": "cancellationQuoteId", "message": "Invalid input: expected string, received undefined", "code": "CANCELLATIONQUOTEID_REQUIRED" } ] } } } }, "503": { "description": "`PROVIDER_UNAVAILABLE` — The travel provider could not be reached; nothing was canceled. Retry later.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "PROVIDER_UNAVAILABLE" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "TRAVEL" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b", "code": "PROVIDER_UNAVAILABLE", "origin": "TRAVEL", "message": "Travel provider temporarily unavailable, please retry." } } } } }, "x-p3-confidence": { "response": "generated:typed", "request": "generated:typed" } } }, "/realms/{realmId}/organizations/{organizationId}/air/locations": { "get": { "operationId": "getRealmsByRealmIdOrganizationsByOrganizationIdAirLocations", "summary": "Search airports", "tags": [ "Air search" ], "x-p3-sidebar-order": 1, "description": "Searches airports for an air search.", "x-mint": { "content": "Use it to fill the origin and destination pickers before you create an air search, then send the airport's `id` — or its IATA code — as `origin` or `destination`. Matches come most relevant first, and an empty `results` means nothing matched. An error the travel provider reports about the request is returned with its own status, `code` and `message`." }, "parameters": [ { "name": "realmId", "in": "path", "required": true, "description": "ID of your realm.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b" }, { "name": "organizationId", "in": "path", "required": true, "description": "ID of your organization.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410" }, { "name": "query", "in": "query", "required": true, "description": "Text to search airports for: part of the airport or city name, a slug or an address (city, region, country), case-insensitive. The IATA code works too.", "schema": { "type": "string", "minLength": 1 }, "example": "Sao Paulo" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the airport. Use it, or its IATA code, as `origin` / `destination` of an air search.", "example": "airpt_Kd3Hq9RwTz5Lx2NvBm8Ys" }, "iata": { "type": "string", "description": "IATA code, 3 letters.", "example": "GRU" }, "icao": { "type": "string", "nullable": true, "description": "ICAO code, 4 letters. `null` when the airport has none.", "example": "SBGR" }, "faa": { "type": "string", "nullable": true, "description": "FAA code (mostly US airports). `null` when the airport has none." }, "name": { "type": "string", "description": "Official name of the airport.", "example": "São Paulo/Guarulhos International Airport" }, "slug": { "type": "string", "description": "Readable unique identifier of the airport.", "example": "sao-paulo-guarulhos-international" }, "address": { "type": "object", "properties": { "shortAddress": { "type": "string", "nullable": true, "description": "The address in a single line. `null` when unknown.", "example": "Guarulhos, SP, Brazil" }, "adressLines": { "type": "array", "items": { "type": "string", "example": "Rod. Hélio Smidt, s/n" }, "description": "The address in postal lines. Empty when unknown. The field name is spelled `adressLines`.\n\n---\n\nExample: `[\"Rod. Hélio Smidt, s/n\"]`" }, "locality": { "type": "string", "nullable": true, "description": "City. `null` when unknown.", "example": "Guarulhos" }, "administrativeArea": { "type": "string", "nullable": true, "description": "State or province code. `null` when unknown.", "example": "SP" }, "administrativeAreaName": { "type": "string", "nullable": true, "description": "State or province name. `null` when unknown.", "example": "São Paulo" }, "postalCode": { "type": "string", "nullable": true, "description": "Postal code. `null` when unknown.", "example": "07190-100" }, "country": { "type": "string", "description": "Country (ISO 3166-1 alpha-2).", "example": "BR" }, "timezone": { "type": "string", "description": "IANA time zone of the place, or `Unknown`.", "example": "America/Sao_Paulo" }, "coordinates": { "description": "Position of the place. `null` when unknown.", "type": "object", "properties": { "lat": { "type": "number", "description": "Latitude, in decimal degrees.", "example": -23.4356 }, "lng": { "type": "number", "description": "Longitude, in decimal degrees.", "example": -46.4731 } }, "required": [ "lat", "lng" ], "nullable": true }, "localityId": { "type": "string", "nullable": true, "description": "ID of the locality the bus station belongs to. Bus stations only; `null` when the station is not grouped under a locality." } }, "required": [ "shortAddress", "adressLines", "locality", "administrativeArea", "administrativeAreaName", "postalCode", "country", "timezone", "coordinates" ], "description": "Address and position of the airport." }, "status": { "type": "string", "enum": [ "ACTIVE", "INACTIVE" ], "description": "`ACTIVE` or `INACTIVE`. Only active airports can be searched.", "example": "ACTIVE" } }, "required": [ "id", "iata", "icao", "faa", "name", "slug", "address", "status" ], "description": "An airport (`air` locations)." }, "description": "Matching airports, most relevant first. Empty when nothing matches." } }, "required": [ "results" ], "description": "The airports matching an air location search." } } } }, "422": { "description": "`BAD_REQUEST` — A path parameter is not a valid ID, or `query` is missing or blank; `fields` lists each one.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "BAD_REQUEST" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "TRAVEL" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." }, "fields": { "type": "array", "description": "One entry per invalid request field (validation errors only).", "items": { "type": "object", "properties": { "field": { "type": "string", "description": "Path of the invalid field, e.g. `label` or `values[0].value`.", "example": "label" }, "message": { "type": "string", "description": "Why the field was rejected.", "example": "label is required" }, "code": { "type": "string", "description": "`_` — e.g. `LABEL_REQUIRED`, `TYPE_ONE_OF`, `VALUES_VALUE_TYPE_ERROR`.", "example": "LABEL_REQUIRED" }, "values": { "type": "array", "items": { "type": "string" }, "description": "The accepted values, when the field is an enumeration." } }, "required": [ "field", "message", "code" ] } } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "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": "query", "message": "Invalid input: expected string, received undefined", "code": "QUERY_REQUIRED" } ] } } } }, "503": { "description": "`PROVIDER_UNAVAILABLE` — The travel provider could not be reached. Retry later.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "PROVIDER_UNAVAILABLE" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "TRAVEL" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b", "code": "PROVIDER_UNAVAILABLE", "origin": "TRAVEL", "message": "Travel provider temporarily unavailable, please retry." } } } } }, "x-p3-confidence": { "response": "generated:typed", "parameters": "generated:typed" } } }, "/realms/{realmId}/organizations/{organizationId}/air/searches": { "post": { "operationId": "postRealmsByRealmIdOrganizationsByOrganizationIdAirSearches", "summary": "Create an air search", "tags": [ "Air search" ], "x-p3-sidebar-order": 2, "description": "Starts a search for flights, one way or round trip.", "x-mint": { "content": "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 flight 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.\n\nFind `origin` and `destination` with the locations endpoint. To book a result, open the item for its fares, then create a trip with the item's `id` as `searchItemId` and the chosen fare's `id` as `fareId`.\n\nAn error the travel provider reports about the request — an unknown airport, say — is returned with its own status, `code` and `message`." }, "parameters": [ { "name": "realmId", "in": "path", "required": true, "description": "ID of your realm.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b" }, { "name": "organizationId", "in": "path", "required": true, "description": "ID of your organization.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "departureDate": { "type": "string", "minLength": 1, "description": "Outbound flight date (`YYYY-MM-DD`). Today or later.", "example": "2026-11-02" }, "returnDate": { "description": "Return flight date (`YYYY-MM-DD`), on or after `departureDate`. Omit it for a one-way trip.", "example": "2026-11-05", "type": "string", "minLength": 1 }, "origin": { "type": "string", "minLength": 1, "description": "Origin airport: its 3-letter IATA code or its `id` from the locations endpoint. Must differ from `destination`.", "example": "GRU" }, "destination": { "type": "string", "minLength": 1, "description": "Destination airport: its 3-letter IATA code or its `id` from the locations endpoint. Must differ from `origin`.", "example": "GIG" }, "passengers": { "minItems": 1, "type": "array", "items": { "type": "string", "enum": [ "ADULT", "CHILD", "INFANT", "SENIOR" ], "example": "ADULT" }, "description": "Who is traveling, one entry per traveler, at least one: `ADULT`, `CHILD`, `INFANT` or `SENIOR`.\n\n---\n\nExample: `[\"ADULT\"]`" }, "cabin": { "description": "Cabin to search: `ECONOMY`, `PREMIUM_ECONOMY`, `BUSINESS`, `FIRST_CLASS` or `UNDEFINED`. Defaults to `ECONOMY`.", "example": "ECONOMY", "type": "string", "minLength": 1 } }, "required": [ "departureDate", "origin", "destination", "passengers" ] } } } }, "responses": { "202": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the search. The same search parameters, within the time the search lasts, return the same ID.", "example": "srch_V1StGXR8Z5jdHi6BmyT2k" }, "searchParams": { "type": "object", "properties": { "departureDate": { "type": "string", "description": "Outbound date, as sent.", "example": "2026-11-02" }, "returnDate": { "type": "string", "description": "Return date, as sent. Absent for a one-way trip.", "example": "2026-11-05" }, "origin": { "type": "string", "description": "Origin airport, as sent.", "example": "GRU" }, "destination": { "type": "string", "description": "Destination airport, as sent.", "example": "GIG" }, "passengers": { "type": "array", "items": { "type": "string", "enum": [ "ADULT", "CHILD", "INFANT", "SENIOR" ], "example": "ADULT" }, "description": "Travelers, as sent.\n\n---\n\nExample: `[\"ADULT\"]`" }, "cabin": { "type": "string", "enum": [ "ECONOMY", "PREMIUM_ECONOMY", "BUSINESS", "FIRST_CLASS", "UNDEFINED" ], "description": "Cabin searched; `ECONOMY` when the request had none.", "example": "ECONOMY" } }, "required": [ "departureDate", "origin", "destination", "passengers", "cabin" ], "description": "What the search was made for." }, "type": { "type": "string", "enum": [ "AIR" ], "description": "Always `AIR`.", "example": "AIR" }, "status": { "type": "string", "enum": [ "PROCESSING", "FAILED", "COMPLETED" ], "description": "`PROCESSING` right after creation. It becomes `COMPLETED` or `FAILED` on its own: poll the search.", "example": "PROCESSING" }, "warning": { "description": "How the search went across the suppliers. `null` while it is processing.", "type": "object", "properties": { "code": { "type": "string", "enum": [ "ALL_FAILED", "PARTIAL_SUCCESS", "ALL_SUCCESS" ], "description": "`ALL_SUCCESS`: every supplier answered. `PARTIAL_SUCCESS`: some suppliers failed, so the results may be incomplete. `ALL_FAILED`: no supplier answered.", "example": "ALL_SUCCESS" }, "message": { "type": "string", "description": "Human-readable explanation.", "example": "All suppliers answered." } }, "required": [ "code", "message" ], "nullable": true }, "ttl": { "type": "number", "description": "Seconds until the search expires.", "example": 900 }, "facets": { "description": "Facets to build filters from (price ranges, airlines). `null` until the search completes.", "type": "object", "additionalProperties": {}, "nullable": true }, "createdAt": { "type": "string", "description": "When the search was created.", "example": "2026-10-19T15:00:00.000Z", "format": "date-time" } }, "required": [ "id", "searchParams", "type", "status", "warning", "ttl", "facets", "createdAt" ], "description": "A search just created for flights. Results come later: poll the search." } } } }, "422": { "description": "`BAD_REQUEST` — A path parameter is not a valid ID or the body failed validation; `fields` lists each offending field.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "BAD_REQUEST" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "TRAVEL" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." }, "fields": { "type": "array", "description": "One entry per invalid request field (validation errors only).", "items": { "type": "object", "properties": { "field": { "type": "string", "description": "Path of the invalid field, e.g. `label` or `values[0].value`.", "example": "label" }, "message": { "type": "string", "description": "Why the field was rejected.", "example": "label is required" }, "code": { "type": "string", "description": "`_` — e.g. `LABEL_REQUIRED`, `TYPE_ONE_OF`, `VALUES_VALUE_TYPE_ERROR`.", "example": "LABEL_REQUIRED" }, "values": { "type": "array", "items": { "type": "string" }, "description": "The accepted values, when the field is an enumeration." } }, "required": [ "field", "message", "code" ] } } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "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": "departureDate", "message": "Invalid input: expected string, received undefined", "code": "DEPARTUREDATE_REQUIRED" } ] } } } }, "503": { "description": "`PROVIDER_UNAVAILABLE` — The travel provider could not be reached; no search was created. Retry later.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "PROVIDER_UNAVAILABLE" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "TRAVEL" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b", "code": "PROVIDER_UNAVAILABLE", "origin": "TRAVEL", "message": "Travel provider temporarily unavailable, please retry." } } } } }, "x-p3-confidence": { "response": "generated:typed", "request": "generated:typed" } } }, "/realms/{realmId}/organizations/{organizationId}/air/searches/{searchId}": { "get": { "operationId": "getRealmsByRealmIdOrganizationsByOrganizationIdAirSearchesBySearchId", "summary": "Get an air search and its results", "tags": [ "Air search" ], "x-p3-sidebar-order": 3, "description": "Returns an air search and, once it has finished, one page of its flights.", "x-mint": { "content": "Searches are asynchronous: while `status` is `PROCESSING` only the search itself comes back, so poll until it is `COMPLETED`, then read `items`. A `FAILED` search has no results. A air search expires after its `ttl` (15 minutes) and then answers `404 SEARCH_NOT_FOUND`. Only the organization that created a search can read it.\n\nResults come in pages. Sort them with `order` and `orderBy`, narrow them with `minAmount`, `maxAmount`, `airline`, `airlineCode` and `cabin`, then walk the pages with `limit` and the `next` cursor each response returns (`null` on the last page). A filter that takes several values accepts them repeated or comma-separated (`?airline=LA&airline=G3` or `?airline=LA,G3`). Amounts are integers in cents: `98700` is R$ 987,00.\n\nEach item is a summary with its cheapest fare. To book one, open it with the air search item endpoint for everything a trip needs, and create the trip with the item's `id` as `searchItemId`. To compare flights by airline and price first, read the same results grouped into cards with the aggregate endpoint. An error the travel provider reports about the request — a filter value it does not accept, say — is returned with its own status, `code` and `message`." }, "parameters": [ { "name": "realmId", "in": "path", "required": true, "description": "ID of your realm.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b" }, { "name": "organizationId", "in": "path", "required": true, "description": "ID of your organization.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410" }, { "name": "searchId", "in": "path", "required": true, "description": "ID of the air search, as returned when it was created.", "schema": { "type": "string", "pattern": "^srch_[0-9A-Za-z]{21}$" }, "example": "srch_V1StGXR8Z5jdHi6BmyT2k" }, { "name": "order", "in": "query", "required": false, "description": "Sort direction applied to `orderBy`: `ASC` lists the cheapest results first, `DESC` the most expensive first.", "schema": { "type": "string", "enum": [ "ASC", "DESC" ] }, "example": "ASC" }, { "name": "orderBy", "in": "query", "required": false, "description": "Field to sort the results by. Currently only `amount` is supported.", "schema": { "type": "string", "minLength": 1 }, "example": "amount" }, { "name": "next", "in": "query", "required": false, "description": "Cursor returned as `next` by the previous page. Omit for the first page.", "schema": { "type": "string", "minLength": 1 }, "example": "eyJwIjoyfQ==" }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of items per page, from 1 to 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "example": 20 }, { "name": "minAmount", "in": "query", "required": false, "description": "Only results costing at least this amount, in the same unit as the `amount` of the results (cents).", "schema": { "type": "number", "minimum": 0 }, "example": 20000 }, { "name": "maxAmount", "in": "query", "required": false, "description": "Only results costing at most this amount, in the same unit as the `amount` of the results (cents).", "schema": { "type": "number", "minimum": 0 }, "example": 100000 }, { "name": "airline", "in": "query", "required": false, "description": "Only flights sold by these airlines, by name (case-insensitive).\n\n---\n\nExample (comma-separated list): `?airline=LATAM,Gol`", "schema": { "type": "array", "items": { "type": "string" } }, "style": "form", "explode": false }, { "name": "airlineCode", "in": "query", "required": false, "description": "Only flights sold by these airlines, by IATA code (case-insensitive).\n\n---\n\nExample (comma-separated list): `?airlineCode=LA,G3`", "schema": { "type": "array", "items": { "type": "string" } }, "style": "form", "explode": false }, { "name": "cabin", "in": "query", "required": false, "description": "Only flights with a fare in these cabins: `ECONOMY`, `PREMIUM_ECONOMY`, `BUSINESS`, `FIRST_CLASS` or `UNDEFINED`. A flight is kept when at least one of its fares has a segment in one of them.\n\n---\n\nExample (comma-separated list): `?cabin=ECONOMY,BUSINESS`", "schema": { "type": "array", "items": { "type": "string" } }, "style": "form", "explode": false } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the search.", "example": "srch_V1StGXR8Z5jdHi6BmyT2k" }, "status": { "type": "string", "enum": [ "PROCESSING", "FAILED", "COMPLETED" ], "description": "`PROCESSING` while the suppliers answer, then `COMPLETED` or `FAILED`. Only `COMPLETED` carries `items`.", "example": "COMPLETED" }, "warning": { "description": "How the search went across the suppliers. `null` while it is processing.", "type": "object", "properties": { "code": { "type": "string", "enum": [ "ALL_FAILED", "PARTIAL_SUCCESS", "ALL_SUCCESS" ], "description": "`ALL_SUCCESS`: every supplier answered. `PARTIAL_SUCCESS`: some suppliers failed, so the results may be incomplete. `ALL_FAILED`: no supplier answered.", "example": "ALL_SUCCESS" }, "message": { "type": "string", "description": "Human-readable explanation.", "example": "All suppliers answered." } }, "required": [ "code", "message" ], "nullable": true }, "createdAt": { "type": "string", "description": "When the search was created.", "example": "2026-10-19T15:00:00.000Z", "format": "date-time" }, "next": { "type": "string", "nullable": true, "description": "Cursor for the next page. `null` on the last page. Present only once the search is `COMPLETED`.", "example": "eyJwIjoyfQ==" }, "totalCount": { "type": "number", "description": "Number of results that match the filters, across every page. Present only once the search is `COMPLETED`.", "example": 1 }, "searchParams": { "type": "object", "properties": { "departureDate": { "type": "string", "description": "Outbound date, as sent.", "example": "2026-11-02" }, "returnDate": { "type": "string", "description": "Return date, as sent. Absent for a one-way trip.", "example": "2026-11-05" }, "origin": { "type": "string", "description": "Origin airport, as sent.", "example": "GRU" }, "destination": { "type": "string", "description": "Destination airport, as sent.", "example": "GIG" }, "passengers": { "type": "array", "items": { "type": "string", "enum": [ "ADULT", "CHILD", "INFANT", "SENIOR" ], "example": "ADULT" }, "description": "Travelers, as sent.\n\n---\n\nExample: `[\"ADULT\"]`" }, "cabin": { "type": "string", "enum": [ "ECONOMY", "PREMIUM_ECONOMY", "BUSINESS", "FIRST_CLASS", "UNDEFINED" ], "description": "Cabin searched; `ECONOMY` when the request had none.", "example": "ECONOMY" } }, "required": [ "departureDate", "origin", "destination", "passengers", "cabin" ], "description": "What the search was made for, as sent." }, "type": { "type": "string", "enum": [ "AIR" ], "description": "Always `AIR`.", "example": "AIR" }, "ttl": { "type": "number", "description": "Seconds until the search expires (a flight search lasts 15 minutes).", "example": 640 }, "facets": { "description": "Facets to build filters from (price ranges, airlines). `null` until the search completes.", "type": "object", "additionalProperties": {}, "nullable": true }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the item. Send it as `searchItemId` when you create a trip, and use it to load the item.", "example": "srch_item_V1StGXR8Z5jdHi6BmyT2k" }, "searchId": { "type": "string", "description": "ID of the search the item belongs to.", "example": "srch_V1StGXR8Z5jdHi6BmyT2k" }, "occupants": { "type": "number", "description": "Number of travelers the search was made for.", "example": 1 }, "airline": { "type": "object", "properties": { "code": { "type": "string", "description": "IATA code of the airline.", "example": "LA" }, "name": { "type": "string", "nullable": true, "description": "Commercial name. `null` when unknown.", "example": "LATAM Airlines" }, "logo": { "type": "string", "nullable": true, "description": "URL of the airline's logo. `null` when unknown.", "example": "https://example.com/logos/la.svg" } }, "required": [ "code", "name", "logo" ], "description": "Airline that sells the itinerary." }, "journeys": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the journey. The same journey has the same ID in every item of the search.", "example": "jour_Ac9Ld4MsTe6Vn1WqXr8Hu" }, "direction": { "type": "string", "enum": [ "DEPARTURE", "RETURN" ], "description": "`DEPARTURE` for the outbound, `RETURN` for the way back.", "example": "DEPARTURE" }, "origin": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the airport.", "example": "airpt_Kd3Hq9RwTz5Lx2NvBm8Ys" }, "iata": { "type": "string", "description": "IATA code, 3 letters.", "example": "GRU" }, "slug": { "type": "string", "description": "Readable unique identifier of the airport.", "example": "sao-paulo-guarulhos-international" }, "name": { "type": "string", "description": "Official name of the airport.", "example": "São Paulo/Guarulhos International Airport" }, "shortAddress": { "type": "string", "nullable": true, "description": "The address in a single line. `null` when unknown.", "example": "Guarulhos, SP, Brazil" }, "locality": { "type": "string", "nullable": true, "description": "City. `null` when unknown.", "example": "Guarulhos" }, "administrativeArea": { "type": "string", "nullable": true, "description": "State or province code. `null` when unknown.", "example": "SP" }, "phoneNumbers": { "type": "array", "items": { "type": "string", "example": "+551133334444" }, "description": "Contact phone numbers. Empty when none is registered.\n\n---\n\nExample: `[\"+551133334444\"]`" }, "coordinates": { "description": "Position of the airport. `null` when unknown.", "type": "object", "properties": { "lat": { "type": "number", "description": "Latitude, in decimal degrees.", "example": -23.4356 }, "lng": { "type": "number", "description": "Longitude, in decimal degrees.", "example": -46.4731 } }, "required": [ "lat", "lng" ], "nullable": true } }, "required": [ "id", "iata", "slug", "name", "shortAddress", "locality", "administrativeArea", "phoneNumbers", "coordinates" ], "description": "Departure airport of the journey." }, "destination": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the airport.", "example": "airpt_Kd3Hq9RwTz5Lx2NvBm8Ys" }, "iata": { "type": "string", "description": "IATA code, 3 letters.", "example": "GRU" }, "slug": { "type": "string", "description": "Readable unique identifier of the airport.", "example": "sao-paulo-guarulhos-international" }, "name": { "type": "string", "description": "Official name of the airport.", "example": "São Paulo/Guarulhos International Airport" }, "shortAddress": { "type": "string", "nullable": true, "description": "The address in a single line. `null` when unknown.", "example": "Guarulhos, SP, Brazil" }, "locality": { "type": "string", "nullable": true, "description": "City. `null` when unknown.", "example": "Guarulhos" }, "administrativeArea": { "type": "string", "nullable": true, "description": "State or province code. `null` when unknown.", "example": "SP" }, "phoneNumbers": { "type": "array", "items": { "type": "string", "example": "+551133334444" }, "description": "Contact phone numbers. Empty when none is registered.\n\n---\n\nExample: `[\"+551133334444\"]`" }, "coordinates": { "description": "Position of the airport. `null` when unknown.", "type": "object", "properties": { "lat": { "type": "number", "description": "Latitude, in decimal degrees.", "example": -23.4356 }, "lng": { "type": "number", "description": "Longitude, in decimal degrees.", "example": -46.4731 } }, "required": [ "lat", "lng" ], "nullable": true } }, "required": [ "id", "iata", "slug", "name", "shortAddress", "locality", "administrativeArea", "phoneNumbers", "coordinates" ], "description": "Arrival airport of the journey." }, "departureDate": { "type": "string", "description": "Departure, in the local time of the departure airport (`YYYY-MM-DDTHH:mm:ss`, no time-zone offset).", "example": "2026-11-02T08:30:00" }, "arrivalDate": { "type": "string", "description": "Arrival, in the local time of the arrival airport (`YYYY-MM-DDTHH:mm:ss`, no time-zone offset).", "example": "2026-11-02T09:35:00" }, "duration": { "type": "string", "description": "Total travel time, connections included, `HH:mm`.", "example": "01:05" }, "segments": { "type": "array", "items": { "type": "object", "properties": { "airline": { "type": "object", "properties": { "code": { "type": "string", "description": "IATA code of the airline.", "example": "LA" }, "name": { "type": "string", "nullable": true, "description": "Commercial name. `null` when unknown.", "example": "LATAM Airlines" }, "logo": { "type": "string", "nullable": true, "description": "URL of the airline's logo. `null` when unknown.", "example": "https://example.com/logos/la.svg" } }, "required": [ "code", "name", "logo" ], "description": "Airline that sells the seat." }, "operation": { "type": "object", "properties": { "code": { "type": "string", "description": "IATA code of the airline.", "example": "LA" }, "name": { "type": "string", "nullable": true, "description": "Commercial name. `null` when unknown.", "example": "LATAM Airlines" }, "logo": { "type": "string", "nullable": true, "description": "URL of the airline's logo. `null` when unknown.", "example": "https://example.com/logos/la.svg" } }, "required": [ "code", "name", "logo" ], "description": "Airline that operates the flight. It differs from `airline` on codeshares." }, "origin": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the airport.", "example": "airpt_Kd3Hq9RwTz5Lx2NvBm8Ys" }, "iata": { "type": "string", "description": "IATA code, 3 letters.", "example": "GRU" }, "slug": { "type": "string", "description": "Readable unique identifier of the airport.", "example": "sao-paulo-guarulhos-international" }, "name": { "type": "string", "description": "Official name of the airport.", "example": "São Paulo/Guarulhos International Airport" }, "shortAddress": { "type": "string", "nullable": true, "description": "The address in a single line. `null` when unknown.", "example": "Guarulhos, SP, Brazil" }, "locality": { "type": "string", "nullable": true, "description": "City. `null` when unknown.", "example": "Guarulhos" }, "administrativeArea": { "type": "string", "nullable": true, "description": "State or province code. `null` when unknown.", "example": "SP" }, "phoneNumbers": { "type": "array", "items": { "type": "string", "example": "+551133334444" }, "description": "Contact phone numbers. Empty when none is registered.\n\n---\n\nExample: `[\"+551133334444\"]`" }, "coordinates": { "description": "Position of the airport. `null` when unknown.", "type": "object", "properties": { "lat": { "type": "number", "description": "Latitude, in decimal degrees.", "example": -23.4356 }, "lng": { "type": "number", "description": "Longitude, in decimal degrees.", "example": -46.4731 } }, "required": [ "lat", "lng" ], "nullable": true } }, "required": [ "id", "iata", "slug", "name", "shortAddress", "locality", "administrativeArea", "phoneNumbers", "coordinates" ], "description": "Departure airport." }, "destination": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the airport.", "example": "airpt_Kd3Hq9RwTz5Lx2NvBm8Ys" }, "iata": { "type": "string", "description": "IATA code, 3 letters.", "example": "GRU" }, "slug": { "type": "string", "description": "Readable unique identifier of the airport.", "example": "sao-paulo-guarulhos-international" }, "name": { "type": "string", "description": "Official name of the airport.", "example": "São Paulo/Guarulhos International Airport" }, "shortAddress": { "type": "string", "nullable": true, "description": "The address in a single line. `null` when unknown.", "example": "Guarulhos, SP, Brazil" }, "locality": { "type": "string", "nullable": true, "description": "City. `null` when unknown.", "example": "Guarulhos" }, "administrativeArea": { "type": "string", "nullable": true, "description": "State or province code. `null` when unknown.", "example": "SP" }, "phoneNumbers": { "type": "array", "items": { "type": "string", "example": "+551133334444" }, "description": "Contact phone numbers. Empty when none is registered.\n\n---\n\nExample: `[\"+551133334444\"]`" }, "coordinates": { "description": "Position of the airport. `null` when unknown.", "type": "object", "properties": { "lat": { "type": "number", "description": "Latitude, in decimal degrees.", "example": -23.4356 }, "lng": { "type": "number", "description": "Longitude, in decimal degrees.", "example": -46.4731 } }, "required": [ "lat", "lng" ], "nullable": true } }, "required": [ "id", "iata", "slug", "name", "shortAddress", "locality", "administrativeArea", "phoneNumbers", "coordinates" ], "description": "Arrival airport." }, "flightNumber": { "type": "string", "description": "Flight number, without the airline code.", "example": "3300" }, "departureDate": { "type": "string", "description": "Departure, in the local time of the departure airport (`YYYY-MM-DDTHH:mm:ss`, no time-zone offset).", "example": "2026-11-02T08:30:00" }, "arrivalDate": { "type": "string", "description": "Arrival, in the local time of the arrival airport (`YYYY-MM-DDTHH:mm:ss`, no time-zone offset).", "example": "2026-11-02T09:35:00" }, "flightType": { "type": "string", "enum": [ "CHARTER", "ALLOTMENT", "REGULAR" ], "description": "`REGULAR`, `CHARTER` or `ALLOTMENT`.", "example": "REGULAR" }, "duration": { "type": "string", "description": "Flight time, `HH:mm`.", "example": "01:05" }, "equipment": { "type": "string", "nullable": true, "description": "Aircraft scheduled for the flight, as the airline identifies it. `null` when not informed.", "example": "32Q" } }, "required": [ "airline", "operation", "origin", "destination", "flightNumber", "departureDate", "arrivalDate", "flightType", "duration", "equipment" ], "description": "One flight of a journey." }, "description": "The flights of the journey, in order. One for a direct journey, more with connections." } }, "required": [ "id", "direction", "origin", "destination", "departureDate", "arrivalDate", "duration", "segments" ], "description": "One way of a flight: the outbound or the return, with its connections." }, "description": "The journeys, in travel order: the outbound first and, for a round trip, the return." }, "cheapestFare": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the fare. Send it as `fareId` when you create a trip with this item.", "example": "fare_Jh2Xv8NcQd5Wp1RkTy7Ab" }, "description": { "type": "string", "description": "Name of the fare.", "example": "LIGHT" }, "fare": { "type": "object", "properties": { "currency": { "type": "string", "description": "Currency of the amounts (ISO 4217).", "example": "BRL" }, "originalAmount": { "type": "number", "description": "Price before discounts and fees, in cents.", "example": 105000 }, "discountAmount": { "type": "number", "description": "Discount applied to the original amount, in cents.", "example": 10000 }, "feeAmount": { "type": "number", "description": "Fees added to the fare, in cents.", "example": 3700 }, "amount": { "type": "number", "description": "Total charged: `originalAmount - discountAmount + feeAmount`, in cents (`98700` is R$ 987,00).", "example": 98700 }, "cancellationPolicies": { "type": "object", "properties": { "refundable": { "type": "boolean", "description": "Whether the fare allows any refund at all.", "example": true }, "immediateFine": { "type": "boolean", "description": "Whether a fine is charged for cancelling right after booking.", "example": false }, "penalties": { "type": "array", "items": { "type": "object", "properties": { "from": { "type": "string", "description": "Date (`YYYY-MM-DD`) from which this tier applies.", "example": "2026-10-30" }, "currency": { "type": "string", "description": "Currency of the penalty (ISO 4217).", "example": "BRL" }, "fineAmount": { "type": "number", "description": "Penalty charged when cancelling or changing from `from` onward, in cents.", "example": 15000 } }, "required": [ "from", "currency", "fineAmount" ], "description": "One tier of a cancellation or change penalty schedule." }, "description": "Penalty schedule, in effect from each tier's date. Empty or omitted when no scheduled penalty applies." } }, "required": [ "refundable", "immediateFine" ], "description": "Cancellation rules of the fare. Only in the item detail, not in the search results." }, "changePolicies": { "type": "object", "properties": { "canChange": { "type": "boolean", "description": "Whether the fare allows the booking to be changed.", "example": true }, "immediateFine": { "type": "boolean", "description": "Whether a fine is charged for changing right after booking.", "example": false }, "penalties": { "type": "array", "items": { "type": "object", "properties": { "from": { "type": "string", "description": "Date (`YYYY-MM-DD`) from which this tier applies.", "example": "2026-10-30" }, "currency": { "type": "string", "description": "Currency of the penalty (ISO 4217).", "example": "BRL" }, "fineAmount": { "type": "number", "description": "Penalty charged when cancelling or changing from `from` onward, in cents.", "example": 15000 } }, "required": [ "from", "currency", "fineAmount" ], "description": "One tier of a cancellation or change penalty schedule." }, "description": "Penalty schedule, in effect from each tier's date. Empty when none applies." } }, "required": [ "canChange", "immediateFine", "penalties" ], "description": "Change rules of the fare. Only in the item detail, not in the search results." } }, "required": [ "currency", "originalAmount", "discountAmount", "feeAmount", "amount" ], "description": "Price of the fare." }, "segments": { "type": "array", "items": { "type": "object", "properties": { "flightNumber": { "type": "string", "description": "Flight number this applies to; it matches a segment of the item's journeys.", "example": "3300" }, "cabin": { "type": "string", "enum": [ "ECONOMY", "PREMIUM_ECONOMY", "BUSINESS", "FIRST_CLASS", "UNDEFINED" ], "description": "Cabin on this flight: `ECONOMY`, `PREMIUM_ECONOMY`, `BUSINESS`, `FIRST_CLASS` or `UNDEFINED`.", "example": "ECONOMY" }, "class": { "type": "string", "nullable": true, "description": "Booking class (RBD). Each airline defines its own codes. `null` when the airline doesn't expose it.", "example": "Y" }, "fareBasis": { "type": "string", "nullable": true, "description": "Fare basis code. Each airline defines its own codes. `null` when the airline doesn't expose it.", "example": "YLIGHT" }, "baggages": { "type": "array", "items": { "type": "object", "properties": { "quantity": { "type": "number", "description": "Number of pieces included.", "example": 1 }, "weight": { "type": "number", "nullable": true, "description": "Weight allowed per piece, in kg. `null` when the airline sets no per-piece weight.", "example": 10 }, "type": { "type": "string", "enum": [ "CHECKED", "CARRY_ON", "PERSONAL_ITEM" ], "description": "`CHECKED`, `CARRY_ON` or `PERSONAL_ITEM`.", "example": "CARRY_ON" } }, "required": [ "quantity", "weight", "type" ], "description": "Baggage included in a fare, for one flight." }, "description": "Baggage included on this flight." } }, "required": [ "flightNumber", "cabin", "class", "fareBasis", "baggages" ], "description": "What a fare gives on one flight: cabin, booking class and baggage." }, "description": "Cabin and baggage per flight." } }, "required": [ "id", "description", "fare", "segments" ], "description": "The cheapest fare of the item. Absent when the item has no fare." } }, "required": [ "id", "searchId", "occupants", "airline", "journeys" ], "description": "A flight in the search results: the journeys of one itinerary and its cheapest fare. Load the item for every fare." }, "description": "The flights of this page, filtered and sorted by the query parameters. Present only once the search is `COMPLETED`." } }, "required": [ "createdAt", "facets", "id", "searchParams", "status", "ttl", "type", "warning" ], "description": "An air search with, once it is `COMPLETED`, one page of its flights." } } } }, "404": { "description": "`SEARCH_NOT_FOUND` — The search doesn't exist, has expired, was created by another organization or is not an air search.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "SEARCH_NOT_FOUND" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "TRAVEL" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b", "code": "SEARCH_NOT_FOUND", "origin": "TRAVEL", "message": "Search not found" } } } }, "422": { "description": "`BAD_REQUEST` — A path parameter is not a valid ID or a query parameter is invalid; `fields` lists each one.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "BAD_REQUEST" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "TRAVEL" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." }, "fields": { "type": "array", "description": "One entry per invalid request field (validation errors only).", "items": { "type": "object", "properties": { "field": { "type": "string", "description": "Path of the invalid field, e.g. `label` or `values[0].value`.", "example": "label" }, "message": { "type": "string", "description": "Why the field was rejected.", "example": "label is required" }, "code": { "type": "string", "description": "`_` — e.g. `LABEL_REQUIRED`, `TYPE_ONE_OF`, `VALUES_VALUE_TYPE_ERROR`.", "example": "LABEL_REQUIRED" }, "values": { "type": "array", "items": { "type": "string" }, "description": "The accepted values, when the field is an enumeration." } }, "required": [ "field", "message", "code" ] } } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "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": "order", "message": "Invalid option: expected one of \"ASC\"|\"DESC\"", "code": "ORDER_ONE_OF" } ] } } } }, "503": { "description": "`PROVIDER_UNAVAILABLE` — The travel provider could not be reached. Retry later.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "PROVIDER_UNAVAILABLE" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "TRAVEL" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b", "code": "PROVIDER_UNAVAILABLE", "origin": "TRAVEL", "message": "Travel provider temporarily unavailable, please retry." } } } } }, "x-p3-confidence": { "response": "generated:typed", "parameters": "generated:typed" } } }, "/realms/{realmId}/organizations/{organizationId}/air/searches/{searchId}/aggregate": { "get": { "operationId": "getRealmsByRealmIdOrganizationsByOrganizationIdAirSearchesBySearchIdAggregate", "summary": "Get an air search grouped by airline and price", "tags": [ "Air search" ], "x-p3-sidebar-order": 4, "description": "Returns the results of an air search grouped into cards by airline and price.", "x-mint": { "content": "Built for a price-first list: a card gathers the flights that share the same airline, the same cheapest fare and the same return options, and lists each distinct outbound and return journey once instead of repeating it for every combination. The traveler picks the airline and fare first and then only picks times. Every outbound of a card combines with every return of it, and two cards can share an airline and a price while offering different times.\n\nTo get the search item of a chosen combination, read the card's `searchItems`, or intersect the `searchItemIds` of the two journeys chosen. Create a trip with that item's `id` as `searchItemId` and the card's cheapest fare `id` as `fareId`, or open the item for its other fares.\n\nIt works on air searches only and takes the same pagination, sort and air filters as the search results — `order`, `orderBy`, `limit`, `next`, `minAmount`, `maxAmount`, `airline`, `airlineCode` and `cabin` — except that `next` and `totalCount` count cards, not items. A filter that takes several values accepts them repeated (`?airline=LA&airline=G3`) or comma-separated (`?airline=LA,G3`). While `status` is `PROCESSING` only the search itself comes back: poll until it is `COMPLETED`. Amounts are integers in cents: `98700` is R$ 987,00. An error the travel provider reports about the request — a filter value it does not accept, say — is returned with its own status, `code` and `message`." }, "parameters": [ { "name": "realmId", "in": "path", "required": true, "description": "ID of your realm.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b" }, { "name": "organizationId", "in": "path", "required": true, "description": "ID of your organization.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410" }, { "name": "searchId", "in": "path", "required": true, "description": "ID of the air search, as returned when it was created.", "schema": { "type": "string", "pattern": "^srch_[0-9A-Za-z]{21}$" }, "example": "srch_V1StGXR8Z5jdHi6BmyT2k" }, { "name": "order", "in": "query", "required": false, "description": "Sort direction applied to `orderBy`: `ASC` lists the cheapest cards first, `DESC` the most expensive first.", "schema": { "type": "string", "enum": [ "ASC", "DESC" ] }, "example": "ASC" }, { "name": "orderBy", "in": "query", "required": false, "description": "Field to sort the cards by. Currently only `amount` is supported.", "schema": { "type": "string", "minLength": 1 }, "example": "amount" }, { "name": "next", "in": "query", "required": false, "description": "Cursor returned as `next` by the previous page. Omit for the first page.", "schema": { "type": "string", "minLength": 1 }, "example": "eyJwIjoyfQ==" }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of cards per page, from 1 to 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "example": 20 }, { "name": "minAmount", "in": "query", "required": false, "description": "Only cards costing at least this amount, in the same unit as the `amount` of the fares (cents).", "schema": { "type": "number", "minimum": 0 }, "example": 20000 }, { "name": "maxAmount", "in": "query", "required": false, "description": "Only cards costing at most this amount, in the same unit as the `amount` of the fares (cents).", "schema": { "type": "number", "minimum": 0 }, "example": 100000 }, { "name": "airline", "in": "query", "required": false, "description": "Only flights sold by these airlines, by name (case-insensitive).\n\n---\n\nExample (comma-separated list): `?airline=LATAM,Gol`", "schema": { "type": "array", "items": { "type": "string" } }, "style": "form", "explode": false }, { "name": "airlineCode", "in": "query", "required": false, "description": "Only flights sold by these airlines, by IATA code (case-insensitive).\n\n---\n\nExample (comma-separated list): `?airlineCode=LA,G3`", "schema": { "type": "array", "items": { "type": "string" } }, "style": "form", "explode": false }, { "name": "cabin", "in": "query", "required": false, "description": "Only flights with a fare in these cabins: `ECONOMY`, `PREMIUM_ECONOMY`, `BUSINESS`, `FIRST_CLASS` or `UNDEFINED`. A flight is kept when at least one of its fares has a segment in one of them.\n\n---\n\nExample (comma-separated list): `?cabin=ECONOMY,BUSINESS`", "schema": { "type": "array", "items": { "type": "string" } }, "style": "form", "explode": false } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the search.", "example": "srch_V1StGXR8Z5jdHi6BmyT2k" }, "searchParams": { "type": "object", "properties": { "departureDate": { "type": "string", "description": "Outbound date, as sent.", "example": "2026-11-02" }, "returnDate": { "type": "string", "description": "Return date, as sent. Absent for a one-way trip.", "example": "2026-11-05" }, "origin": { "type": "string", "description": "Origin airport, as sent.", "example": "GRU" }, "destination": { "type": "string", "description": "Destination airport, as sent.", "example": "GIG" }, "passengers": { "type": "array", "items": { "type": "string", "enum": [ "ADULT", "CHILD", "INFANT", "SENIOR" ], "example": "ADULT" }, "description": "Travelers, as sent.\n\n---\n\nExample: `[\"ADULT\"]`" }, "cabin": { "type": "string", "enum": [ "ECONOMY", "PREMIUM_ECONOMY", "BUSINESS", "FIRST_CLASS", "UNDEFINED" ], "description": "Cabin searched; `ECONOMY` when the request had none.", "example": "ECONOMY" } }, "required": [ "departureDate", "origin", "destination", "passengers", "cabin" ], "description": "What the search was made for." }, "type": { "type": "string", "enum": [ "AIR" ], "description": "Always `AIR`.", "example": "AIR" }, "status": { "type": "string", "enum": [ "PROCESSING", "FAILED", "COMPLETED" ], "description": "`PROCESSING`, `COMPLETED` or `FAILED`. Only `COMPLETED` carries cards.", "example": "COMPLETED" }, "warning": { "description": "How the search went across the suppliers. `null` while it is processing.", "type": "object", "properties": { "code": { "type": "string", "enum": [ "ALL_FAILED", "PARTIAL_SUCCESS", "ALL_SUCCESS" ], "description": "`ALL_SUCCESS`: every supplier answered. `PARTIAL_SUCCESS`: some suppliers failed, so the results may be incomplete. `ALL_FAILED`: no supplier answered.", "example": "ALL_SUCCESS" }, "message": { "type": "string", "description": "Human-readable explanation.", "example": "All suppliers answered." } }, "required": [ "code", "message" ], "nullable": true }, "ttl": { "type": "number", "description": "Seconds until the search expires.", "example": 640 }, "facets": { "description": "Facets to build filters from (price ranges, airlines). `null` until the search completes.", "type": "object", "additionalProperties": {}, "nullable": true }, "createdAt": { "type": "string", "description": "When the search was created.", "example": "2026-10-19T15:00:00.000Z", "format": "date-time" }, "items": { "type": "array", "items": { "type": "object", "properties": { "airline": { "type": "object", "properties": { "code": { "type": "string", "description": "IATA code of the airline.", "example": "LA" }, "name": { "type": "string", "nullable": true, "description": "Commercial name. `null` when unknown.", "example": "LATAM Airlines" }, "logo": { "type": "string", "nullable": true, "description": "URL of the airline's logo. `null` when unknown.", "example": "https://example.com/logos/la.svg" } }, "required": [ "code", "name", "logo" ], "description": "Airline shared by every combination of the card." }, "occupants": { "type": "number", "description": "Number of travelers the search was made for.", "example": 1 }, "cheapestFare": { "description": "Cheapest fare shared by the card. `null` when its items have no fare.", "type": "object", "properties": { "id": { "type": "string", "description": "ID of the fare. Send it as `fareId` when you create a trip with one of the card's items.", "example": "fare_Jh2Xv8NcQd5Wp1RkTy7Ab" }, "description": { "type": "string", "description": "Name of the fare.", "example": "LIGHT" }, "fare": { "type": "object", "properties": { "currency": { "type": "string", "description": "Currency of the amounts (ISO 4217).", "example": "BRL" }, "originalAmount": { "type": "number", "description": "Price before discounts and fees, in cents.", "example": 105000 }, "discountAmount": { "type": "number", "description": "Discount applied to the original amount, in cents.", "example": 10000 }, "feeAmount": { "type": "number", "description": "Fees added to the fare, in cents.", "example": 3700 }, "amount": { "type": "number", "description": "Total charged: `originalAmount - discountAmount + feeAmount`, in cents (`98700` is R$ 987,00).", "example": 98700 }, "cancellationPolicies": { "type": "object", "properties": { "refundable": { "type": "boolean", "description": "Whether the fare allows any refund at all.", "example": true }, "immediateFine": { "type": "boolean", "description": "Whether a fine is charged for cancelling right after booking.", "example": false }, "penalties": { "type": "array", "items": { "type": "object", "properties": { "from": { "type": "string", "description": "Date (`YYYY-MM-DD`) from which this tier applies.", "example": "2026-10-30" }, "currency": { "type": "string", "description": "Currency of the penalty (ISO 4217).", "example": "BRL" }, "fineAmount": { "type": "number", "description": "Penalty charged when cancelling or changing from `from` onward, in cents.", "example": 15000 } }, "required": [ "from", "currency", "fineAmount" ], "description": "One tier of a cancellation or change penalty schedule." }, "description": "Penalty schedule, in effect from each tier's date. Empty or omitted when no scheduled penalty applies." } }, "required": [ "refundable", "immediateFine" ], "description": "Cancellation rules of the fare. Only in the item detail, not in the search results." }, "changePolicies": { "type": "object", "properties": { "canChange": { "type": "boolean", "description": "Whether the fare allows the booking to be changed.", "example": true }, "immediateFine": { "type": "boolean", "description": "Whether a fine is charged for changing right after booking.", "example": false }, "penalties": { "type": "array", "items": { "type": "object", "properties": { "from": { "type": "string", "description": "Date (`YYYY-MM-DD`) from which this tier applies.", "example": "2026-10-30" }, "currency": { "type": "string", "description": "Currency of the penalty (ISO 4217).", "example": "BRL" }, "fineAmount": { "type": "number", "description": "Penalty charged when cancelling or changing from `from` onward, in cents.", "example": 15000 } }, "required": [ "from", "currency", "fineAmount" ], "description": "One tier of a cancellation or change penalty schedule." }, "description": "Penalty schedule, in effect from each tier's date. Empty when none applies." } }, "required": [ "canChange", "immediateFine", "penalties" ], "description": "Change rules of the fare. Only in the item detail, not in the search results." } }, "required": [ "currency", "originalAmount", "discountAmount", "feeAmount", "amount" ], "description": "Price of the fare." } }, "required": [ "id", "description", "fare" ], "nullable": true }, "journeys": { "type": "array", "items": { "type": "object", "properties": { "direction": { "type": "string", "enum": [ "DEPARTURE", "RETURN" ], "description": "`DEPARTURE` for outbound options, `RETURN` for the way back.", "example": "DEPARTURE" }, "options": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the journey; the same journey has the same ID in every item.", "example": "jour_Ac9Ld4MsTe6Vn1WqXr8Hu" }, "searchItemIds": { "type": "array", "items": { "type": "string", "example": "srch_item_V1StGXR8Z5jdHi6BmyT2k" }, "description": "IDs of the search items this journey appears in. The items that contain both an outbound and a return option are the ones that pair them.\n\n---\n\nExample: `[\"srch_item_V1StGXR8Z5jdHi6BmyT2k\"]`" }, "origin": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the airport.", "example": "airpt_Kd3Hq9RwTz5Lx2NvBm8Ys" }, "iata": { "type": "string", "description": "IATA code, 3 letters.", "example": "GRU" }, "slug": { "type": "string", "description": "Readable unique identifier of the airport.", "example": "sao-paulo-guarulhos-international" }, "name": { "type": "string", "description": "Official name of the airport.", "example": "São Paulo/Guarulhos International Airport" }, "shortAddress": { "type": "string", "nullable": true, "description": "The address in a single line. `null` when unknown.", "example": "Guarulhos, SP, Brazil" }, "locality": { "type": "string", "nullable": true, "description": "City. `null` when unknown.", "example": "Guarulhos" }, "administrativeArea": { "type": "string", "nullable": true, "description": "State or province code. `null` when unknown.", "example": "SP" }, "phoneNumbers": { "type": "array", "items": { "type": "string", "example": "+551133334444" }, "description": "Contact phone numbers. Empty when none is registered.\n\n---\n\nExample: `[\"+551133334444\"]`" }, "coordinates": { "description": "Position of the airport. `null` when unknown.", "type": "object", "properties": { "lat": { "type": "number", "description": "Latitude, in decimal degrees.", "example": -23.4356 }, "lng": { "type": "number", "description": "Longitude, in decimal degrees.", "example": -46.4731 } }, "required": [ "lat", "lng" ], "nullable": true } }, "required": [ "id", "iata", "slug", "name", "shortAddress", "locality", "administrativeArea", "phoneNumbers", "coordinates" ], "description": "Departure airport of the journey." }, "destination": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the airport.", "example": "airpt_Kd3Hq9RwTz5Lx2NvBm8Ys" }, "iata": { "type": "string", "description": "IATA code, 3 letters.", "example": "GRU" }, "slug": { "type": "string", "description": "Readable unique identifier of the airport.", "example": "sao-paulo-guarulhos-international" }, "name": { "type": "string", "description": "Official name of the airport.", "example": "São Paulo/Guarulhos International Airport" }, "shortAddress": { "type": "string", "nullable": true, "description": "The address in a single line. `null` when unknown.", "example": "Guarulhos, SP, Brazil" }, "locality": { "type": "string", "nullable": true, "description": "City. `null` when unknown.", "example": "Guarulhos" }, "administrativeArea": { "type": "string", "nullable": true, "description": "State or province code. `null` when unknown.", "example": "SP" }, "phoneNumbers": { "type": "array", "items": { "type": "string", "example": "+551133334444" }, "description": "Contact phone numbers. Empty when none is registered.\n\n---\n\nExample: `[\"+551133334444\"]`" }, "coordinates": { "description": "Position of the airport. `null` when unknown.", "type": "object", "properties": { "lat": { "type": "number", "description": "Latitude, in decimal degrees.", "example": -23.4356 }, "lng": { "type": "number", "description": "Longitude, in decimal degrees.", "example": -46.4731 } }, "required": [ "lat", "lng" ], "nullable": true } }, "required": [ "id", "iata", "slug", "name", "shortAddress", "locality", "administrativeArea", "phoneNumbers", "coordinates" ], "description": "Arrival airport of the journey." }, "departureDate": { "type": "string", "description": "Departure, in the local time of the departure airport (`YYYY-MM-DDTHH:mm:ss`, no time-zone offset).", "example": "2026-11-02T08:30:00" }, "arrivalDate": { "type": "string", "description": "Arrival, in the local time of the arrival airport (`YYYY-MM-DDTHH:mm:ss`, no time-zone offset).", "example": "2026-11-02T09:35:00" }, "duration": { "type": "string", "description": "Total travel time, connections included, `HH:mm`.", "example": "01:05" }, "segments": { "type": "array", "items": { "type": "object", "properties": { "airline": { "type": "object", "properties": { "code": { "type": "string", "description": "IATA code of the airline.", "example": "LA" }, "name": { "type": "string", "nullable": true, "description": "Commercial name. `null` when unknown.", "example": "LATAM Airlines" }, "logo": { "type": "string", "nullable": true, "description": "URL of the airline's logo. `null` when unknown.", "example": "https://example.com/logos/la.svg" } }, "required": [ "code", "name", "logo" ], "description": "Airline that sells the seat." }, "operation": { "type": "object", "properties": { "code": { "type": "string", "description": "IATA code of the airline.", "example": "LA" }, "name": { "type": "string", "nullable": true, "description": "Commercial name. `null` when unknown.", "example": "LATAM Airlines" }, "logo": { "type": "string", "nullable": true, "description": "URL of the airline's logo. `null` when unknown.", "example": "https://example.com/logos/la.svg" } }, "required": [ "code", "name", "logo" ], "description": "Airline that operates the flight. It differs from `airline` on codeshares." }, "origin": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the airport.", "example": "airpt_Kd3Hq9RwTz5Lx2NvBm8Ys" }, "iata": { "type": "string", "description": "IATA code, 3 letters.", "example": "GRU" }, "slug": { "type": "string", "description": "Readable unique identifier of the airport.", "example": "sao-paulo-guarulhos-international" }, "name": { "type": "string", "description": "Official name of the airport.", "example": "São Paulo/Guarulhos International Airport" }, "shortAddress": { "type": "string", "nullable": true, "description": "The address in a single line. `null` when unknown.", "example": "Guarulhos, SP, Brazil" }, "locality": { "type": "string", "nullable": true, "description": "City. `null` when unknown.", "example": "Guarulhos" }, "administrativeArea": { "type": "string", "nullable": true, "description": "State or province code. `null` when unknown.", "example": "SP" }, "phoneNumbers": { "type": "array", "items": { "type": "string", "example": "+551133334444" }, "description": "Contact phone numbers. Empty when none is registered.\n\n---\n\nExample: `[\"+551133334444\"]`" }, "coordinates": { "description": "Position of the airport. `null` when unknown.", "type": "object", "properties": { "lat": { "type": "number", "description": "Latitude, in decimal degrees.", "example": -23.4356 }, "lng": { "type": "number", "description": "Longitude, in decimal degrees.", "example": -46.4731 } }, "required": [ "lat", "lng" ], "nullable": true } }, "required": [ "id", "iata", "slug", "name", "shortAddress", "locality", "administrativeArea", "phoneNumbers", "coordinates" ], "description": "Departure airport." }, "destination": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the airport.", "example": "airpt_Kd3Hq9RwTz5Lx2NvBm8Ys" }, "iata": { "type": "string", "description": "IATA code, 3 letters.", "example": "GRU" }, "slug": { "type": "string", "description": "Readable unique identifier of the airport.", "example": "sao-paulo-guarulhos-international" }, "name": { "type": "string", "description": "Official name of the airport.", "example": "São Paulo/Guarulhos International Airport" }, "shortAddress": { "type": "string", "nullable": true, "description": "The address in a single line. `null` when unknown.", "example": "Guarulhos, SP, Brazil" }, "locality": { "type": "string", "nullable": true, "description": "City. `null` when unknown.", "example": "Guarulhos" }, "administrativeArea": { "type": "string", "nullable": true, "description": "State or province code. `null` when unknown.", "example": "SP" }, "phoneNumbers": { "type": "array", "items": { "type": "string", "example": "+551133334444" }, "description": "Contact phone numbers. Empty when none is registered.\n\n---\n\nExample: `[\"+551133334444\"]`" }, "coordinates": { "description": "Position of the airport. `null` when unknown.", "type": "object", "properties": { "lat": { "type": "number", "description": "Latitude, in decimal degrees.", "example": -23.4356 }, "lng": { "type": "number", "description": "Longitude, in decimal degrees.", "example": -46.4731 } }, "required": [ "lat", "lng" ], "nullable": true } }, "required": [ "id", "iata", "slug", "name", "shortAddress", "locality", "administrativeArea", "phoneNumbers", "coordinates" ], "description": "Arrival airport." }, "flightNumber": { "type": "string", "description": "Flight number, without the airline code.", "example": "3300" }, "departureDate": { "type": "string", "description": "Departure, in the local time of the departure airport (`YYYY-MM-DDTHH:mm:ss`, no time-zone offset).", "example": "2026-11-02T08:30:00" }, "arrivalDate": { "type": "string", "description": "Arrival, in the local time of the arrival airport (`YYYY-MM-DDTHH:mm:ss`, no time-zone offset).", "example": "2026-11-02T09:35:00" }, "flightType": { "type": "string", "enum": [ "CHARTER", "ALLOTMENT", "REGULAR" ], "description": "`REGULAR`, `CHARTER` or `ALLOTMENT`.", "example": "REGULAR" }, "duration": { "type": "string", "description": "Flight time, `HH:mm`.", "example": "01:05" }, "equipment": { "type": "string", "nullable": true, "description": "Aircraft scheduled for the flight, as the airline identifies it. `null` when not informed.", "example": "32Q" } }, "required": [ "airline", "operation", "origin", "destination", "flightNumber", "departureDate", "arrivalDate", "flightType", "duration", "equipment" ], "description": "One flight of a journey." }, "description": "The flights of the journey, in order." } }, "required": [ "id", "searchItemIds", "origin", "destination", "departureDate", "arrivalDate", "duration", "segments" ], "description": "One journey option of an air card." }, "description": "The distinct journeys available in this direction. Each appears once." } }, "required": [ "direction", "options" ], "description": "The journey options of an air card in one direction." }, "description": "The journey options by direction: one group for a one-way search, two (outbound first) for a round trip." }, "searchItems": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the search item. Send it as `searchItemId` when you create a trip.", "example": "srch_item_V1StGXR8Z5jdHi6BmyT2k" }, "journeyIds": { "type": "array", "items": { "type": "string", "example": "jour_Ac9Ld4MsTe6Vn1WqXr8Hu" }, "description": "IDs of the journeys of the item, in travel order: the outbound first and, for a round trip, the return.\n\n---\n\nExample: `[\"jour_Ac9Ld4MsTe6Vn1WqXr8Hu\",\"jour_Bd3Nf7PtUg2Xk5YrZs9Jw\"]`" } }, "required": [ "id", "journeyIds" ], "description": "A combination a card offers: the search item and the journeys it is made of." }, "description": "The combinations the card offers, as an item ID with its journeys." } }, "required": [ "airline", "occupants", "cheapestFare", "journeys", "searchItems" ], "description": "A card: the items that share the same airline, the same cheapest fare and the same return options, with each distinct journey listed once. Every outbound of a card combines with every return of it." }, "description": "The cards of this page. Present only once the search is `COMPLETED`." }, "next": { "type": "string", "nullable": true, "description": "Cursor for the next page of cards. `null` on the last page. Present only once the search is `COMPLETED`.", "example": "eyJwIjoyfQ==" }, "totalCount": { "type": "number", "description": "Number of cards that match the filters, not of items. Present only once the search is `COMPLETED`.", "example": 1 } }, "required": [ "id", "searchParams", "type", "status", "warning", "ttl", "facets", "createdAt" ], "description": "The results of an air search grouped by airline and price." } } } }, "404": { "description": "`SEARCH_NOT_FOUND` — The search doesn't exist, has expired, was created by another organization or is not an air search.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "SEARCH_NOT_FOUND" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "TRAVEL" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b", "code": "SEARCH_NOT_FOUND", "origin": "TRAVEL", "message": "Search not found" } } } }, "422": { "description": "`BAD_REQUEST` — A path parameter is not a valid ID or a query parameter is invalid; `fields` lists each one.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "BAD_REQUEST" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "TRAVEL" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." }, "fields": { "type": "array", "description": "One entry per invalid request field (validation errors only).", "items": { "type": "object", "properties": { "field": { "type": "string", "description": "Path of the invalid field, e.g. `label` or `values[0].value`.", "example": "label" }, "message": { "type": "string", "description": "Why the field was rejected.", "example": "label is required" }, "code": { "type": "string", "description": "`_` — e.g. `LABEL_REQUIRED`, `TYPE_ONE_OF`, `VALUES_VALUE_TYPE_ERROR`.", "example": "LABEL_REQUIRED" }, "values": { "type": "array", "items": { "type": "string" }, "description": "The accepted values, when the field is an enumeration." } }, "required": [ "field", "message", "code" ] } } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "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": "order", "message": "Invalid option: expected one of \"ASC\"|\"DESC\"", "code": "ORDER_ONE_OF" } ] } } } }, "503": { "description": "`PROVIDER_UNAVAILABLE` — The travel provider could not be reached. Retry later.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "PROVIDER_UNAVAILABLE" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "TRAVEL" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b", "code": "PROVIDER_UNAVAILABLE", "origin": "TRAVEL", "message": "Travel provider temporarily unavailable, please retry." } } } } }, "x-p3-confidence": { "response": "generated:typed", "parameters": "generated:typed" } } }, "/realms/{realmId}/organizations/{organizationId}/air/searches/{searchId}/items/{itemId}": { "get": { "operationId": "getRealmsByRealmIdOrganizationsByOrganizationIdAirSearchesBySearchIdItemsByItemId", "summary": "Get an air search item", "tags": [ "Air search" ], "x-p3-sidebar-order": 5, "description": "Returns the full detail of one flight of an air search: its journeys and every fare option.", "x-mint": { "content": "Open a flight of the search results to see what the list only summarizes: the `journeys` and every fare option, each with its cabin and baggage per flight. To book it, create a trip with the item's `id` as `searchItemId` and the chosen `fareOptions` entry's `id` as `fareId`. Amounts are integers in cents: `98700` is R$ 987,00. The item lives as long as its search (see `ttl`). An error the travel provider reports about the request is returned with its own status, `code` and `message`." }, "parameters": [ { "name": "realmId", "in": "path", "required": true, "description": "ID of your realm.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b" }, { "name": "organizationId", "in": "path", "required": true, "description": "ID of your organization.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410" }, { "name": "searchId", "in": "path", "required": true, "description": "ID of the search, as returned when it was created.", "schema": { "type": "string", "pattern": "^srch_[0-9A-Za-z]{21}$" }, "example": "srch_V1StGXR8Z5jdHi6BmyT2k" }, { "name": "itemId", "in": "path", "required": true, "description": "ID of the item to load, as listed in the `items` of the search results.", "schema": { "type": "string", "pattern": "^srch_item_[0-9A-Za-z]{21}$" }, "example": "srch_item_V1StGXR8Z5jdHi6BmyT2k" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the item. Send it as `searchItemId` when you create a trip.", "example": "srch_item_V1StGXR8Z5jdHi6BmyT2k" }, "searchId": { "type": "string", "description": "ID of the search the item belongs to.", "example": "srch_V1StGXR8Z5jdHi6BmyT2k" }, "occupants": { "type": "number", "description": "Number of travelers the search was made for.", "example": 1 }, "airline": { "type": "object", "properties": { "code": { "type": "string", "description": "IATA code of the airline.", "example": "LA" }, "name": { "type": "string", "nullable": true, "description": "Commercial name. `null` when unknown.", "example": "LATAM Airlines" }, "logo": { "type": "string", "nullable": true, "description": "URL of the airline's logo. `null` when unknown.", "example": "https://example.com/logos/la.svg" } }, "required": [ "code", "name", "logo" ], "description": "Airline that sells the itinerary." }, "journeys": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the journey. The same journey has the same ID in every item of the search.", "example": "jour_Ac9Ld4MsTe6Vn1WqXr8Hu" }, "direction": { "type": "string", "enum": [ "DEPARTURE", "RETURN" ], "description": "`DEPARTURE` for the outbound, `RETURN` for the way back.", "example": "DEPARTURE" }, "origin": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the airport.", "example": "airpt_Kd3Hq9RwTz5Lx2NvBm8Ys" }, "iata": { "type": "string", "description": "IATA code, 3 letters.", "example": "GRU" }, "slug": { "type": "string", "description": "Readable unique identifier of the airport.", "example": "sao-paulo-guarulhos-international" }, "name": { "type": "string", "description": "Official name of the airport.", "example": "São Paulo/Guarulhos International Airport" }, "shortAddress": { "type": "string", "nullable": true, "description": "The address in a single line. `null` when unknown.", "example": "Guarulhos, SP, Brazil" }, "locality": { "type": "string", "nullable": true, "description": "City. `null` when unknown.", "example": "Guarulhos" }, "administrativeArea": { "type": "string", "nullable": true, "description": "State or province code. `null` when unknown.", "example": "SP" }, "phoneNumbers": { "type": "array", "items": { "type": "string", "example": "+551133334444" }, "description": "Contact phone numbers. Empty when none is registered.\n\n---\n\nExample: `[\"+551133334444\"]`" }, "coordinates": { "description": "Position of the airport. `null` when unknown.", "type": "object", "properties": { "lat": { "type": "number", "description": "Latitude, in decimal degrees.", "example": -23.4356 }, "lng": { "type": "number", "description": "Longitude, in decimal degrees.", "example": -46.4731 } }, "required": [ "lat", "lng" ], "nullable": true } }, "required": [ "id", "iata", "slug", "name", "shortAddress", "locality", "administrativeArea", "phoneNumbers", "coordinates" ], "description": "Departure airport of the journey." }, "destination": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the airport.", "example": "airpt_Kd3Hq9RwTz5Lx2NvBm8Ys" }, "iata": { "type": "string", "description": "IATA code, 3 letters.", "example": "GRU" }, "slug": { "type": "string", "description": "Readable unique identifier of the airport.", "example": "sao-paulo-guarulhos-international" }, "name": { "type": "string", "description": "Official name of the airport.", "example": "São Paulo/Guarulhos International Airport" }, "shortAddress": { "type": "string", "nullable": true, "description": "The address in a single line. `null` when unknown.", "example": "Guarulhos, SP, Brazil" }, "locality": { "type": "string", "nullable": true, "description": "City. `null` when unknown.", "example": "Guarulhos" }, "administrativeArea": { "type": "string", "nullable": true, "description": "State or province code. `null` when unknown.", "example": "SP" }, "phoneNumbers": { "type": "array", "items": { "type": "string", "example": "+551133334444" }, "description": "Contact phone numbers. Empty when none is registered.\n\n---\n\nExample: `[\"+551133334444\"]`" }, "coordinates": { "description": "Position of the airport. `null` when unknown.", "type": "object", "properties": { "lat": { "type": "number", "description": "Latitude, in decimal degrees.", "example": -23.4356 }, "lng": { "type": "number", "description": "Longitude, in decimal degrees.", "example": -46.4731 } }, "required": [ "lat", "lng" ], "nullable": true } }, "required": [ "id", "iata", "slug", "name", "shortAddress", "locality", "administrativeArea", "phoneNumbers", "coordinates" ], "description": "Arrival airport of the journey." }, "departureDate": { "type": "string", "description": "Departure, in the local time of the departure airport (`YYYY-MM-DDTHH:mm:ss`, no time-zone offset).", "example": "2026-11-02T08:30:00" }, "arrivalDate": { "type": "string", "description": "Arrival, in the local time of the arrival airport (`YYYY-MM-DDTHH:mm:ss`, no time-zone offset).", "example": "2026-11-02T09:35:00" }, "duration": { "type": "string", "description": "Total travel time, connections included, `HH:mm`.", "example": "01:05" }, "segments": { "type": "array", "items": { "type": "object", "properties": { "airline": { "type": "object", "properties": { "code": { "type": "string", "description": "IATA code of the airline.", "example": "LA" }, "name": { "type": "string", "nullable": true, "description": "Commercial name. `null` when unknown.", "example": "LATAM Airlines" }, "logo": { "type": "string", "nullable": true, "description": "URL of the airline's logo. `null` when unknown.", "example": "https://example.com/logos/la.svg" } }, "required": [ "code", "name", "logo" ], "description": "Airline that sells the seat." }, "operation": { "type": "object", "properties": { "code": { "type": "string", "description": "IATA code of the airline.", "example": "LA" }, "name": { "type": "string", "nullable": true, "description": "Commercial name. `null` when unknown.", "example": "LATAM Airlines" }, "logo": { "type": "string", "nullable": true, "description": "URL of the airline's logo. `null` when unknown.", "example": "https://example.com/logos/la.svg" } }, "required": [ "code", "name", "logo" ], "description": "Airline that operates the flight. It differs from `airline` on codeshares." }, "origin": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the airport.", "example": "airpt_Kd3Hq9RwTz5Lx2NvBm8Ys" }, "iata": { "type": "string", "description": "IATA code, 3 letters.", "example": "GRU" }, "slug": { "type": "string", "description": "Readable unique identifier of the airport.", "example": "sao-paulo-guarulhos-international" }, "name": { "type": "string", "description": "Official name of the airport.", "example": "São Paulo/Guarulhos International Airport" }, "shortAddress": { "type": "string", "nullable": true, "description": "The address in a single line. `null` when unknown.", "example": "Guarulhos, SP, Brazil" }, "locality": { "type": "string", "nullable": true, "description": "City. `null` when unknown.", "example": "Guarulhos" }, "administrativeArea": { "type": "string", "nullable": true, "description": "State or province code. `null` when unknown.", "example": "SP" }, "phoneNumbers": { "type": "array", "items": { "type": "string", "example": "+551133334444" }, "description": "Contact phone numbers. Empty when none is registered.\n\n---\n\nExample: `[\"+551133334444\"]`" }, "coordinates": { "description": "Position of the airport. `null` when unknown.", "type": "object", "properties": { "lat": { "type": "number", "description": "Latitude, in decimal degrees.", "example": -23.4356 }, "lng": { "type": "number", "description": "Longitude, in decimal degrees.", "example": -46.4731 } }, "required": [ "lat", "lng" ], "nullable": true } }, "required": [ "id", "iata", "slug", "name", "shortAddress", "locality", "administrativeArea", "phoneNumbers", "coordinates" ], "description": "Departure airport." }, "destination": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the airport.", "example": "airpt_Kd3Hq9RwTz5Lx2NvBm8Ys" }, "iata": { "type": "string", "description": "IATA code, 3 letters.", "example": "GRU" }, "slug": { "type": "string", "description": "Readable unique identifier of the airport.", "example": "sao-paulo-guarulhos-international" }, "name": { "type": "string", "description": "Official name of the airport.", "example": "São Paulo/Guarulhos International Airport" }, "shortAddress": { "type": "string", "nullable": true, "description": "The address in a single line. `null` when unknown.", "example": "Guarulhos, SP, Brazil" }, "locality": { "type": "string", "nullable": true, "description": "City. `null` when unknown.", "example": "Guarulhos" }, "administrativeArea": { "type": "string", "nullable": true, "description": "State or province code. `null` when unknown.", "example": "SP" }, "phoneNumbers": { "type": "array", "items": { "type": "string", "example": "+551133334444" }, "description": "Contact phone numbers. Empty when none is registered.\n\n---\n\nExample: `[\"+551133334444\"]`" }, "coordinates": { "description": "Position of the airport. `null` when unknown.", "type": "object", "properties": { "lat": { "type": "number", "description": "Latitude, in decimal degrees.", "example": -23.4356 }, "lng": { "type": "number", "description": "Longitude, in decimal degrees.", "example": -46.4731 } }, "required": [ "lat", "lng" ], "nullable": true } }, "required": [ "id", "iata", "slug", "name", "shortAddress", "locality", "administrativeArea", "phoneNumbers", "coordinates" ], "description": "Arrival airport." }, "flightNumber": { "type": "string", "description": "Flight number, without the airline code.", "example": "3300" }, "departureDate": { "type": "string", "description": "Departure, in the local time of the departure airport (`YYYY-MM-DDTHH:mm:ss`, no time-zone offset).", "example": "2026-11-02T08:30:00" }, "arrivalDate": { "type": "string", "description": "Arrival, in the local time of the arrival airport (`YYYY-MM-DDTHH:mm:ss`, no time-zone offset).", "example": "2026-11-02T09:35:00" }, "flightType": { "type": "string", "enum": [ "CHARTER", "ALLOTMENT", "REGULAR" ], "description": "`REGULAR`, `CHARTER` or `ALLOTMENT`.", "example": "REGULAR" }, "duration": { "type": "string", "description": "Flight time, `HH:mm`.", "example": "01:05" }, "equipment": { "type": "string", "nullable": true, "description": "Aircraft scheduled for the flight, as the airline identifies it. `null` when not informed.", "example": "32Q" } }, "required": [ "airline", "operation", "origin", "destination", "flightNumber", "departureDate", "arrivalDate", "flightType", "duration", "equipment" ], "description": "One flight of a journey." }, "description": "The flights of the journey, in order. One for a direct journey, more with connections." } }, "required": [ "id", "direction", "origin", "destination", "departureDate", "arrivalDate", "duration", "segments" ], "description": "One way of a flight: the outbound or the return, with its connections." }, "description": "The journeys, in travel order: the outbound first and, for a round trip, the return." }, "fareOptions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the fare. Send it as `fareId` when you create a trip with this item.", "example": "fare_Jh2Xv8NcQd5Wp1RkTy7Ab" }, "description": { "type": "string", "description": "Name of the fare.", "example": "LIGHT" }, "fare": { "type": "object", "properties": { "currency": { "type": "string", "description": "Currency of the amounts (ISO 4217).", "example": "BRL" }, "originalAmount": { "type": "number", "description": "Price before discounts and fees, in cents.", "example": 105000 }, "discountAmount": { "type": "number", "description": "Discount applied to the original amount, in cents.", "example": 10000 }, "feeAmount": { "type": "number", "description": "Fees added to the fare, in cents.", "example": 3700 }, "amount": { "type": "number", "description": "Total charged: `originalAmount - discountAmount + feeAmount`, in cents (`98700` is R$ 987,00).", "example": 98700 }, "cancellationPolicies": { "type": "object", "properties": { "refundable": { "type": "boolean", "description": "Whether the fare allows any refund at all.", "example": true }, "immediateFine": { "type": "boolean", "description": "Whether a fine is charged for cancelling right after booking.", "example": false }, "penalties": { "type": "array", "items": { "type": "object", "properties": { "from": { "type": "string", "description": "Date (`YYYY-MM-DD`) from which this tier applies.", "example": "2026-10-30" }, "currency": { "type": "string", "description": "Currency of the penalty (ISO 4217).", "example": "BRL" }, "fineAmount": { "type": "number", "description": "Penalty charged when cancelling or changing from `from` onward, in cents.", "example": 15000 } }, "required": [ "from", "currency", "fineAmount" ], "description": "One tier of a cancellation or change penalty schedule." }, "description": "Penalty schedule, in effect from each tier's date. Empty or omitted when no scheduled penalty applies." } }, "required": [ "refundable", "immediateFine" ], "description": "Cancellation rules of the fare. Only in the item detail, not in the search results." }, "changePolicies": { "type": "object", "properties": { "canChange": { "type": "boolean", "description": "Whether the fare allows the booking to be changed.", "example": true }, "immediateFine": { "type": "boolean", "description": "Whether a fine is charged for changing right after booking.", "example": false }, "penalties": { "type": "array", "items": { "type": "object", "properties": { "from": { "type": "string", "description": "Date (`YYYY-MM-DD`) from which this tier applies.", "example": "2026-10-30" }, "currency": { "type": "string", "description": "Currency of the penalty (ISO 4217).", "example": "BRL" }, "fineAmount": { "type": "number", "description": "Penalty charged when cancelling or changing from `from` onward, in cents.", "example": 15000 } }, "required": [ "from", "currency", "fineAmount" ], "description": "One tier of a cancellation or change penalty schedule." }, "description": "Penalty schedule, in effect from each tier's date. Empty when none applies." } }, "required": [ "canChange", "immediateFine", "penalties" ], "description": "Change rules of the fare. Only in the item detail, not in the search results." } }, "required": [ "currency", "originalAmount", "discountAmount", "feeAmount", "amount" ], "description": "Price of the fare." }, "segments": { "type": "array", "items": { "type": "object", "properties": { "flightNumber": { "type": "string", "description": "Flight number this applies to; it matches a segment of the item's journeys.", "example": "3300" }, "cabin": { "type": "string", "enum": [ "ECONOMY", "PREMIUM_ECONOMY", "BUSINESS", "FIRST_CLASS", "UNDEFINED" ], "description": "Cabin on this flight: `ECONOMY`, `PREMIUM_ECONOMY`, `BUSINESS`, `FIRST_CLASS` or `UNDEFINED`.", "example": "ECONOMY" }, "class": { "type": "string", "nullable": true, "description": "Booking class (RBD). Each airline defines its own codes. `null` when the airline doesn't expose it.", "example": "Y" }, "fareBasis": { "type": "string", "nullable": true, "description": "Fare basis code. Each airline defines its own codes. `null` when the airline doesn't expose it.", "example": "YLIGHT" }, "baggages": { "type": "array", "items": { "type": "object", "properties": { "quantity": { "type": "number", "description": "Number of pieces included.", "example": 1 }, "weight": { "type": "number", "nullable": true, "description": "Weight allowed per piece, in kg. `null` when the airline sets no per-piece weight.", "example": 10 }, "type": { "type": "string", "enum": [ "CHECKED", "CARRY_ON", "PERSONAL_ITEM" ], "description": "`CHECKED`, `CARRY_ON` or `PERSONAL_ITEM`.", "example": "CARRY_ON" } }, "required": [ "quantity", "weight", "type" ], "description": "Baggage included in a fare, for one flight." }, "description": "Baggage included on this flight." } }, "required": [ "flightNumber", "cabin", "class", "fareBasis", "baggages" ], "description": "What a fare gives on one flight: cabin, booking class and baggage." }, "description": "Cabin and baggage per flight." } }, "required": [ "id", "description", "fare", "segments" ], "description": "One fare of an air item: a price with its cabin and baggage rules." }, "description": "Every fare option of the flight, each with its price, rules, cabin and baggage per flight, and ID — send the chosen one's `id` as `fareId` when you create a trip." } }, "required": [ "id", "searchId", "occupants", "airline", "journeys", "fareOptions" ], "description": "The detail of one flight of an air search: its journeys and every fare option." } } } }, "404": { "description": "`SEARCH_NOT_FOUND` — The search doesn't exist, has expired, was created by another organization or is not an air search.\n\n`AIR_SEARCH_ITEM_NOT_FOUND` — The air search has no item with this ID, or it expired.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "SEARCH_NOT_FOUND", "AIR_SEARCH_ITEM_NOT_FOUND" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "TRAVEL" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b", "code": "SEARCH_NOT_FOUND", "origin": "TRAVEL", "message": "Search not found" } } } }, "422": { "description": "`BAD_REQUEST` — A path parameter is not a valid ID; `fields` lists each one.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "BAD_REQUEST" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "TRAVEL" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." }, "fields": { "type": "array", "description": "One entry per invalid request field (validation errors only).", "items": { "type": "object", "properties": { "field": { "type": "string", "description": "Path of the invalid field, e.g. `label` or `values[0].value`.", "example": "label" }, "message": { "type": "string", "description": "Why the field was rejected.", "example": "label is required" }, "code": { "type": "string", "description": "`_` — e.g. `LABEL_REQUIRED`, `TYPE_ONE_OF`, `VALUES_VALUE_TYPE_ERROR`.", "example": "LABEL_REQUIRED" }, "values": { "type": "array", "items": { "type": "string" }, "description": "The accepted values, when the field is an enumeration." } }, "required": [ "field", "message", "code" ] } } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "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": "organizationId", "message": "Invalid UUID", "code": "ORGANIZATIONID_UUID" } ] } } } }, "503": { "description": "`PROVIDER_UNAVAILABLE` — The travel provider could not be reached. Retry later.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "PROVIDER_UNAVAILABLE" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "TRAVEL" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b", "code": "PROVIDER_UNAVAILABLE", "origin": "TRAVEL", "message": "Travel provider temporarily unavailable, please retry." } } } } }, "x-p3-confidence": { "response": "generated:typed" } } }, "/realms/{realmId}/organizations/{organizationId}/hotel/locations": { "get": { "operationId": "getRealmsByRealmIdOrganizationsByOrganizationIdHotelLocations", "summary": "Search hotel destinations", "tags": [ "Hotel search" ], "x-p3-sidebar-order": 1, "description": "Searches destinations for a hotel search.", "x-mint": { "content": "Use it to fill the destination picker before you create a hotel search, then send the place's `id` — or its `slug` — as `destinationId`. Matches come most relevant first, and an empty `results` means nothing matched. An error the travel provider reports about the request is returned with its own status, `code` and `message`." }, "parameters": [ { "name": "realmId", "in": "path", "required": true, "description": "ID of your realm.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b" }, { "name": "organizationId", "in": "path", "required": true, "description": "ID of your organization.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410" }, { "name": "query", "in": "query", "required": true, "description": "Text to search destinations for: part of a city, region or place name, a slug or an address, case-insensitive.", "schema": { "type": "string", "minLength": 1 }, "example": "Sao Paulo" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the place. Use it, or its `slug`, as `destinationId` of a hotel search or as a pick-up or drop-off place of a vehicle search.", "example": "lctn_Mr4Bn7YcQd1Ks9TeVw2Xh" }, "slug": { "type": "string", "description": "Readable unique identifier of the place.", "example": "sao-paulo-sp" }, "name": { "type": "string", "description": "Display name.", "example": "São Paulo" }, "region": { "type": "string", "description": "Region the place belongs to.", "example": "Brasil" }, "address": { "type": "object", "properties": { "shortAddress": { "type": "string", "nullable": true, "description": "The address in a single line. `null` when unknown.", "example": "Guarulhos, SP, Brazil" }, "adressLines": { "type": "array", "items": { "type": "string", "example": "Rod. Hélio Smidt, s/n" }, "description": "The address in postal lines. Empty when unknown. The field name is spelled `adressLines`.\n\n---\n\nExample: `[\"Rod. Hélio Smidt, s/n\"]`" }, "locality": { "type": "string", "nullable": true, "description": "City. `null` when unknown.", "example": "Guarulhos" }, "administrativeArea": { "type": "string", "nullable": true, "description": "State or province code. `null` when unknown.", "example": "SP" }, "administrativeAreaName": { "type": "string", "nullable": true, "description": "State or province name. `null` when unknown.", "example": "São Paulo" }, "postalCode": { "type": "string", "nullable": true, "description": "Postal code. `null` when unknown.", "example": "07190-100" }, "country": { "type": "string", "description": "Country (ISO 3166-1 alpha-2).", "example": "BR" }, "timezone": { "type": "string", "description": "IANA time zone of the place, or `Unknown`.", "example": "America/Sao_Paulo" }, "coordinates": { "description": "Position of the place. `null` when unknown.", "type": "object", "properties": { "lat": { "type": "number", "description": "Latitude, in decimal degrees.", "example": -23.4356 }, "lng": { "type": "number", "description": "Longitude, in decimal degrees.", "example": -46.4731 } }, "required": [ "lat", "lng" ], "nullable": true }, "localityId": { "type": "string", "nullable": true, "description": "ID of the locality the bus station belongs to. Bus stations only; `null` when the station is not grouped under a locality." } }, "required": [ "shortAddress", "adressLines", "locality", "administrativeArea", "administrativeAreaName", "postalCode", "country", "timezone", "coordinates" ], "description": "Address and position of the place." }, "type": { "type": "string", "enum": [ "AIRPORT", "LOCALITY", "LOCALITY_AND_SURROUNDINGS", "GENERIC_PLACE" ], "description": "What the place is: `AIRPORT`, `LOCALITY`, `LOCALITY_AND_SURROUNDINGS` or `GENERIC_PLACE`.", "example": "LOCALITY" } }, "required": [ "id", "slug", "name", "region", "address", "type" ], "description": "A destination or pick-up place (`hotel` and `vehicle` locations)." }, "description": "Matching destinations, most relevant first. Empty when nothing matches." } }, "required": [ "results" ], "description": "The destinations matching a hotel location search." } } } }, "422": { "description": "`BAD_REQUEST` — A path parameter is not a valid ID, or `query` is missing or blank; `fields` lists each one.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "BAD_REQUEST" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "TRAVEL" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." }, "fields": { "type": "array", "description": "One entry per invalid request field (validation errors only).", "items": { "type": "object", "properties": { "field": { "type": "string", "description": "Path of the invalid field, e.g. `label` or `values[0].value`.", "example": "label" }, "message": { "type": "string", "description": "Why the field was rejected.", "example": "label is required" }, "code": { "type": "string", "description": "`_` — e.g. `LABEL_REQUIRED`, `TYPE_ONE_OF`, `VALUES_VALUE_TYPE_ERROR`.", "example": "LABEL_REQUIRED" }, "values": { "type": "array", "items": { "type": "string" }, "description": "The accepted values, when the field is an enumeration." } }, "required": [ "field", "message", "code" ] } } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "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": "query", "message": "Invalid input: expected string, received undefined", "code": "QUERY_REQUIRED" } ] } } } }, "503": { "description": "`PROVIDER_UNAVAILABLE` — The travel provider could not be reached. Retry later.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "PROVIDER_UNAVAILABLE" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "TRAVEL" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b", "code": "PROVIDER_UNAVAILABLE", "origin": "TRAVEL", "message": "Travel provider temporarily unavailable, please retry." } } } } }, "x-p3-confidence": { "response": "generated:typed", "parameters": "generated:typed" } } }, "/realms/{realmId}/organizations/{organizationId}/hotel/searches": { "post": { "operationId": "postRealmsByRealmIdOrganizationsByOrganizationIdHotelSearches", "summary": "Create a hotel search", "tags": [ "Hotel search" ], "x-p3-sidebar-order": 2, "description": "Starts a search for hotels in a destination, for given dates and rooms.", "x-mint": { "content": "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 hotel search lasts 30 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.\n\nFind `destinationId` with the locations endpoint. To book a result, open the item for its rooms, then create a trip with the item's `id` as `searchItemId` and the chosen rooms' `id` as `roomId`.\n\nAn error the travel provider reports about the request — an unknown destination, say — is returned with its own status, `code` and `message`." }, "parameters": [ { "name": "realmId", "in": "path", "required": true, "description": "ID of your realm.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b" }, { "name": "organizationId", "in": "path", "required": true, "description": "ID of your organization.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "checkInDate": { "type": "string", "minLength": 1, "description": "Check-in date (`YYYY-MM-DD`). Today or later, and before `checkOutDate`.", "example": "2026-11-02" }, "checkOutDate": { "type": "string", "minLength": 1, "description": "Check-out date (`YYYY-MM-DD`), after `checkInDate`.", "example": "2026-11-05" }, "destinationId": { "type": "string", "minLength": 1, "description": "Destination: the `id` or the `slug` of a place returned by the locations endpoint.", "example": "sao-paulo-sp" }, "rooms": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "adults": { "type": "integer", "minimum": 1, "description": "Number of adults staying in the room, at least 1.", "example": 2 }, "children": { "description": "Number of children staying in the room. Omit it when there are none.", "example": 1, "type": "integer", "minimum": 0 } }, "required": [ "adults" ] }, "description": "The rooms to search for, with who stays in each. At least one." } }, "required": [ "checkInDate", "checkOutDate", "destinationId", "rooms" ] } } } }, "responses": { "202": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the search. The same search parameters, within the time the search lasts, return the same ID.", "example": "srch_Qm8Zt3LwXc1Ry7NvB0kHd" }, "searchParams": { "type": "object", "properties": { "checkInDate": { "type": "string", "description": "Check-in date, as sent.", "example": "2026-11-02" }, "checkOutDate": { "type": "string", "description": "Check-out date, as sent.", "example": "2026-11-05" }, "destinationId": { "type": "string", "description": "Destination, as sent.", "example": "sao-paulo-sp" }, "rooms": { "type": "array", "items": { "type": "object", "properties": { "adults": { "type": "number", "description": "Number of adults staying in the room.", "example": 2 }, "children": { "type": "number", "description": "Number of children staying in the room. Omitted when there are none.", "example": 1 } }, "required": [ "adults" ], "description": "The occupancy of one room of a hotel search." }, "description": "Rooms, as sent." } }, "required": [ "checkInDate", "checkOutDate", "destinationId", "rooms" ], "description": "What the search was made for." }, "type": { "type": "string", "enum": [ "HOTEL" ], "description": "Always `HOTEL`.", "example": "HOTEL" }, "status": { "type": "string", "enum": [ "PROCESSING", "FAILED", "COMPLETED" ], "description": "`PROCESSING` right after creation. It becomes `COMPLETED` or `FAILED` on its own: poll the search.", "example": "PROCESSING" }, "warning": { "description": "How the search went across the suppliers. `null` while it is processing.", "type": "object", "properties": { "code": { "type": "string", "enum": [ "ALL_FAILED", "PARTIAL_SUCCESS", "ALL_SUCCESS" ], "description": "`ALL_SUCCESS`: every supplier answered. `PARTIAL_SUCCESS`: some suppliers failed, so the results may be incomplete. `ALL_FAILED`: no supplier answered.", "example": "ALL_SUCCESS" }, "message": { "type": "string", "description": "Human-readable explanation.", "example": "All suppliers answered." } }, "required": [ "code", "message" ], "nullable": true }, "ttl": { "type": "number", "description": "Seconds until the search expires.", "example": 1800 }, "facets": { "description": "Facets to build filters from (star ratings, price ranges). `null` until the search completes.", "type": "object", "additionalProperties": {}, "nullable": true }, "createdAt": { "type": "string", "description": "When the search was created.", "example": "2026-10-19T15:00:00.000Z", "format": "date-time" } }, "required": [ "id", "searchParams", "type", "status", "warning", "ttl", "facets", "createdAt" ], "description": "A search just created for hotels. Results come later: poll the search." } } } }, "422": { "description": "`BAD_REQUEST` — A path parameter is not a valid ID or the body failed validation; `fields` lists each offending field.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "BAD_REQUEST" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "TRAVEL" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." }, "fields": { "type": "array", "description": "One entry per invalid request field (validation errors only).", "items": { "type": "object", "properties": { "field": { "type": "string", "description": "Path of the invalid field, e.g. `label` or `values[0].value`.", "example": "label" }, "message": { "type": "string", "description": "Why the field was rejected.", "example": "label is required" }, "code": { "type": "string", "description": "`_` — e.g. `LABEL_REQUIRED`, `TYPE_ONE_OF`, `VALUES_VALUE_TYPE_ERROR`.", "example": "LABEL_REQUIRED" }, "values": { "type": "array", "items": { "type": "string" }, "description": "The accepted values, when the field is an enumeration." } }, "required": [ "field", "message", "code" ] } } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "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": "checkInDate", "message": "Invalid input: expected string, received undefined", "code": "CHECKINDATE_REQUIRED" } ] } } } }, "503": { "description": "`PROVIDER_UNAVAILABLE` — The travel provider could not be reached; no search was created. Retry later.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "PROVIDER_UNAVAILABLE" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "TRAVEL" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b", "code": "PROVIDER_UNAVAILABLE", "origin": "TRAVEL", "message": "Travel provider temporarily unavailable, please retry." } } } } }, "x-p3-confidence": { "response": "generated:typed", "request": "generated:typed" } } }, "/realms/{realmId}/organizations/{organizationId}/hotel/searches/{searchId}": { "get": { "operationId": "getRealmsByRealmIdOrganizationsByOrganizationIdHotelSearchesBySearchId", "summary": "Get a hotel search and its results", "tags": [ "Hotel search" ], "x-p3-sidebar-order": 3, "description": "Returns a hotel search and, once it has finished, one page of its hotels.", "x-mint": { "content": "Searches are asynchronous: while `status` is `PROCESSING` only the search itself comes back, so poll until it is `COMPLETED`, then read `items`. A `FAILED` search has no results. A hotel search expires after its `ttl` (30 minutes) and then answers `404 SEARCH_NOT_FOUND`. Only the organization that created a search can read it.\n\nResults come in pages. Sort them with `order` and `orderBy`, narrow them with `minAmount`, `maxAmount`, `starRating`, `hotelIds`, `latitude`, `longitude` and `radius`, then walk the pages with `limit` and the `next` cursor each response returns (`null` on the last page). A filter that takes several values accepts them repeated or comma-separated (`?starRating=4&starRating=5` or `?starRating=4,5`). Amounts are integers in cents: `98700` is R$ 987,00.\n\nEach item is a summary with its cheapest fare. To book one, open it with the hotel search item endpoint for everything a trip needs, and create the trip with the item's `id` as `searchItemId`. To place the hotels on a map, read the same search as map points with the map endpoint. An error the travel provider reports about the request — a filter value it does not accept, say — is returned with its own status, `code` and `message`." }, "parameters": [ { "name": "realmId", "in": "path", "required": true, "description": "ID of your realm.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b" }, { "name": "organizationId", "in": "path", "required": true, "description": "ID of your organization.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410" }, { "name": "searchId", "in": "path", "required": true, "description": "ID of the hotel search, as returned when it was created.", "schema": { "type": "string", "pattern": "^srch_[0-9A-Za-z]{21}$" }, "example": "srch_V1StGXR8Z5jdHi6BmyT2k" }, { "name": "order", "in": "query", "required": false, "description": "Sort direction applied to `orderBy`: `ASC` lists the cheapest results first, `DESC` the most expensive first.", "schema": { "type": "string", "enum": [ "ASC", "DESC" ] }, "example": "ASC" }, { "name": "orderBy", "in": "query", "required": false, "description": "Field to sort the results by. Currently only `amount` is supported.", "schema": { "type": "string", "minLength": 1 }, "example": "amount" }, { "name": "next", "in": "query", "required": false, "description": "Cursor returned as `next` by the previous page. Omit for the first page.", "schema": { "type": "string", "minLength": 1 }, "example": "eyJwIjoyfQ==" }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of items per page, from 1 to 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "example": 20 }, { "name": "minAmount", "in": "query", "required": false, "description": "Only results costing at least this amount, in the same unit as the `amount` of the results (cents).", "schema": { "type": "number", "minimum": 0 }, "example": 20000 }, { "name": "maxAmount", "in": "query", "required": false, "description": "Only results costing at most this amount, in the same unit as the `amount` of the results (cents).", "schema": { "type": "number", "minimum": 0 }, "example": 100000 }, { "name": "starRating", "in": "query", "required": false, "description": "Only hotels with these star ratings, from `1` to `5`.\n\n---\n\nExample (comma-separated list): `?starRating=4,5`", "schema": { "type": "array", "items": { "type": "string" } }, "style": "form", "explode": false }, { "name": "hotelIds", "in": "query", "required": false, "description": "Only these hotels, by ID (`hotelId` in the results). A hotel that appears more than once in the search keeps all of its items.\n\n---\n\nExample (comma-separated list): `?hotelIds=htl_Pd4Mx9TgUa6Rj1WnKc3Sv,htl_Ek8Bn2VqLt5Hy7DwXu1Zo`", "schema": { "type": "array", "items": { "type": "string", "pattern": "^htl_[0-9A-Za-z]{21}$" } }, "style": "form", "explode": false }, { "name": "latitude", "in": "query", "required": false, "description": "Latitude of the center of a circle to search in, in decimal degrees (-90 to 90). Send it together with `longitude` and `radius`.", "schema": { "type": "number" }, "example": -23.5721 }, { "name": "longitude", "in": "query", "required": false, "description": "Longitude of the center of a circle to search in, in decimal degrees (-180 to 180). Send it together with `latitude` and `radius`.", "schema": { "type": "number" }, "example": -46.6684 }, { "name": "radius", "in": "query", "required": false, "description": "Radius of the circle around `latitude` and `longitude`, in meters (1 to 100000). Hotels whose position is unknown are never inside it. Send it together with `latitude` and `longitude`.", "schema": { "type": "integer", "minimum": 1, "maximum": 100000 }, "example": 5000 } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the search.", "example": "srch_V1StGXR8Z5jdHi6BmyT2k" }, "status": { "type": "string", "enum": [ "PROCESSING", "FAILED", "COMPLETED" ], "description": "`PROCESSING` while the suppliers answer, then `COMPLETED` or `FAILED`. Only `COMPLETED` carries `items`.", "example": "COMPLETED" }, "warning": { "description": "How the search went across the suppliers. `null` while it is processing.", "type": "object", "properties": { "code": { "type": "string", "enum": [ "ALL_FAILED", "PARTIAL_SUCCESS", "ALL_SUCCESS" ], "description": "`ALL_SUCCESS`: every supplier answered. `PARTIAL_SUCCESS`: some suppliers failed, so the results may be incomplete. `ALL_FAILED`: no supplier answered.", "example": "ALL_SUCCESS" }, "message": { "type": "string", "description": "Human-readable explanation.", "example": "All suppliers answered." } }, "required": [ "code", "message" ], "nullable": true }, "createdAt": { "type": "string", "description": "When the search was created.", "example": "2026-10-19T15:00:00.000Z", "format": "date-time" }, "next": { "type": "string", "nullable": true, "description": "Cursor for the next page. `null` on the last page. Present only once the search is `COMPLETED`.", "example": "eyJwIjoyfQ==" }, "totalCount": { "type": "number", "description": "Number of results that match the filters, across every page. Present only once the search is `COMPLETED`.", "example": 1 }, "searchParams": { "type": "object", "properties": { "checkInDate": { "type": "string", "description": "Check-in date, as sent.", "example": "2026-11-02" }, "checkOutDate": { "type": "string", "description": "Check-out date, as sent.", "example": "2026-11-05" }, "destinationId": { "type": "string", "description": "Destination, as sent.", "example": "sao-paulo-sp" }, "rooms": { "type": "array", "items": { "type": "object", "properties": { "adults": { "type": "number", "description": "Number of adults staying in the room.", "example": 2 }, "children": { "type": "number", "description": "Number of children staying in the room. Omitted when there are none.", "example": 1 } }, "required": [ "adults" ], "description": "The occupancy of one room of a hotel search." }, "description": "Rooms, as sent." } }, "required": [ "checkInDate", "checkOutDate", "destinationId", "rooms" ], "description": "What the search was made for, as sent." }, "type": { "type": "string", "enum": [ "HOTEL" ], "description": "Always `HOTEL`.", "example": "HOTEL" }, "ttl": { "type": "number", "description": "Seconds until the search expires (a hotel search lasts 30 minutes).", "example": 1500 }, "facets": { "description": "Facets to build filters from (star ratings, price ranges). `null` until the search completes.", "type": "object", "additionalProperties": {}, "nullable": true }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the item. Send it as `searchItemId` when you create a trip, and use it to load the item.", "example": "srch_item_Zt5Hk2NwQe8Lr3VcXb1Ya" }, "searchId": { "type": "string", "description": "ID of the search the item belongs to.", "example": "srch_Qm8Zt3LwXc1Ry7NvB0kHd" }, "hotel": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the hotel; the same property keeps it across searches.", "example": "htl_Pd4Mx9TgUa6Rj1WnKc3Sv" }, "name": { "type": "string", "description": "Name of the hotel.", "example": "Hotel Paulista Plaza" }, "shortAddress": { "type": "string", "nullable": true, "description": "The address in a single line. `null` when unknown.", "example": "Av. Paulista, 1000, Bela Vista, São Paulo, SP" }, "starRating": { "type": "string", "enum": [ "0", "1", "2", "3", "4", "5" ], "description": "Star rating, `0` to `5`.", "example": "4" }, "mainImageUrl": { "type": "string", "description": "URL of the main image.", "example": "https://example.com/hotels/paulista-plaza/main.jpg" }, "chain": { "type": "object", "properties": { "brandName": { "type": "string", "nullable": true, "description": "Brand within the chain. `null` when unknown.", "example": "Aurora Express" }, "chainName": { "type": "string", "nullable": true, "description": "Chain. `null` for an independent hotel.", "example": "Grupo Aurora" }, "logo": { "type": "string", "nullable": true, "description": "URL of the chain's logo. `null` when there is none.", "example": "https://example.com/logos/aurora.svg" } }, "required": [ "brandName", "chainName", "logo" ], "description": "Chain and brand of the hotel." }, "amenities": { "type": "array", "items": { "type": "string", "example": "WIRELESS_INTERNET_CONNECTION_IN_PUBLIC_AREAS" }, "description": "Amenities the hotel advertises, as codes.\n\n---\n\nExample: `[\"WIRELESS_INTERNET_CONNECTION_IN_PUBLIC_AREAS\",\"RESTAURANT\"]`" } }, "required": [ "id", "name", "shortAddress", "starRating", "mainImageUrl", "chain", "amenities" ], "description": "The hotel." }, "checkIn": { "type": "string", "description": "Check-in date (`YYYY-MM-DD`).", "example": "2026-11-02" }, "checkOut": { "type": "string", "description": "Check-out date (`YYYY-MM-DD`).", "example": "2026-11-05" }, "cheapestFare": { "type": "object", "properties": { "fare": { "type": "object", "properties": { "originalAmount": { "type": "number", "description": "Price before discounts and fees, in cents.", "example": 135000 }, "discountAmount": { "type": "number", "description": "Discount applied to the original amount, in cents.", "example": 15000 }, "feeAmount": { "type": "number", "description": "Fees added to the rate, in cents.", "example": 5000 }, "amount": { "type": "number", "description": "Total rate charged: `originalAmount - discountAmount + feeAmount`, in cents (`125000` is R$ 1.250,00).", "example": 125000 }, "currency": { "type": "string", "description": "Currency of the amounts (ISO 4217).", "example": "BRL" }, "boardType": { "type": "string", "enum": [ "ONLY_ROOM", "BREAKFAST", "HALF_BOARD", "FULL_BOARD", "ALL_INCLUSIVE" ], "description": "Meal plan: `ONLY_ROOM`, `BREAKFAST`, `HALF_BOARD`, `FULL_BOARD` or `ALL_INCLUSIVE`.", "example": "BREAKFAST" }, "cancellationPolicies": { "type": "object", "properties": { "refundable": { "type": "boolean", "description": "Whether the fare allows any refund at all.", "example": true }, "immediateFine": { "type": "boolean", "description": "Whether a fine is charged for cancelling right after booking.", "example": false }, "penalties": { "type": "array", "items": { "type": "object", "properties": { "from": { "type": "string", "description": "Date (`YYYY-MM-DD`) from which this tier applies.", "example": "2026-10-30" }, "currency": { "type": "string", "description": "Currency of the penalty (ISO 4217).", "example": "BRL" }, "fineAmount": { "type": "number", "description": "Penalty charged when cancelling or changing from `from` onward, in cents.", "example": 15000 } }, "required": [ "from", "currency", "fineAmount" ], "description": "One tier of a cancellation or change penalty schedule." }, "description": "Penalty schedule, in effect from each tier's date. Empty or omitted when no scheduled penalty applies." } }, "required": [ "refundable", "immediateFine" ], "description": "Cancellation rules of the rate. Only in the item detail, not in the search results." } }, "required": [ "originalAmount", "discountAmount", "feeAmount", "amount", "currency", "boardType" ], "description": "The rate of the cheapest room." } }, "required": [ "fare" ], "description": "The lowest rate available at this hotel." } }, "required": [ "id", "searchId", "hotel", "checkIn", "checkOut", "cheapestFare" ], "description": "A hotel in the search results, with the cheapest room found. Load the item for every room." }, "description": "The hotels of this page, filtered and sorted by the query parameters. Present only once the search is `COMPLETED`." } }, "required": [ "createdAt", "facets", "id", "searchParams", "status", "ttl", "type", "warning" ], "description": "A hotel search with, once it is `COMPLETED`, one page of its hotels." } } } }, "404": { "description": "`SEARCH_NOT_FOUND` — The search doesn't exist, has expired, was created by another organization or is not a hotel search.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "SEARCH_NOT_FOUND" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "TRAVEL" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b", "code": "SEARCH_NOT_FOUND", "origin": "TRAVEL", "message": "Search not found" } } } }, "422": { "description": "`BAD_REQUEST` — A path parameter is not a valid ID or a query parameter is invalid; `fields` lists each one.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "BAD_REQUEST" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "TRAVEL" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." }, "fields": { "type": "array", "description": "One entry per invalid request field (validation errors only).", "items": { "type": "object", "properties": { "field": { "type": "string", "description": "Path of the invalid field, e.g. `label` or `values[0].value`.", "example": "label" }, "message": { "type": "string", "description": "Why the field was rejected.", "example": "label is required" }, "code": { "type": "string", "description": "`_` — e.g. `LABEL_REQUIRED`, `TYPE_ONE_OF`, `VALUES_VALUE_TYPE_ERROR`.", "example": "LABEL_REQUIRED" }, "values": { "type": "array", "items": { "type": "string" }, "description": "The accepted values, when the field is an enumeration." } }, "required": [ "field", "message", "code" ] } } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "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": "order", "message": "Invalid option: expected one of \"ASC\"|\"DESC\"", "code": "ORDER_ONE_OF" } ] } } } }, "503": { "description": "`PROVIDER_UNAVAILABLE` — The travel provider could not be reached. Retry later.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "PROVIDER_UNAVAILABLE" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "TRAVEL" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b", "code": "PROVIDER_UNAVAILABLE", "origin": "TRAVEL", "message": "Travel provider temporarily unavailable, please retry." } } } } }, "x-p3-confidence": { "response": "generated:typed", "parameters": "generated:typed" } } }, "/realms/{realmId}/organizations/{organizationId}/hotel/searches/{searchId}/map": { "get": { "operationId": "getRealmsByRealmIdOrganizationsByOrganizationIdHotelSearchesBySearchIdMap", "summary": "Get a hotel search as map points", "tags": [ "Hotel search" ], "x-p3-sidebar-order": 4, "description": "Returns every hotel of a search as a point to plot on a map.", "x-mint": { "content": "The list is unpaginated, so the whole result set can be drawn at once. Each point has the hotel's name, its position, the total of the cheapest room found for it and the `itemId` to open its rooms with the search item endpoint. There is one point per hotel — when the same property appears more than once, the cheapest occurrence wins — and hotels with no known position are left out, so the list can be shorter than the search's `totalCount`.\n\nIt works on hotel searches only and takes no query parameters. While `status` is `PROCESSING` or `FAILED`, `results` is empty: poll until `status` is `COMPLETED`. Amounts are integers in cents: `125000` is R$ 1.250,00. An error the travel provider reports about the request is returned with its own status, `code` and `message`." }, "parameters": [ { "name": "realmId", "in": "path", "required": true, "description": "ID of your realm.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b" }, { "name": "organizationId", "in": "path", "required": true, "description": "ID of your organization.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410" }, { "name": "searchId", "in": "path", "required": true, "description": "ID of the hotel search, as returned when it was created.", "schema": { "type": "string", "pattern": "^srch_[0-9A-Za-z]{21}$" }, "example": "srch_Qm8Zt3LwXc1Ry7NvB0kHd" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "PROCESSING", "FAILED", "COMPLETED" ], "description": "Status of the search: `PROCESSING`, `COMPLETED` or `FAILED`. `results` is filled only when it is `COMPLETED`.", "example": "COMPLETED" }, "results": { "type": "array", "items": { "type": "object", "properties": { "itemId": { "type": "string", "description": "ID of the search item. Use it to load the hotel's rooms; send it as `searchItemId` when you create a trip.", "example": "srch_item_Zt5Hk2NwQe8Lr3VcXb1Ya" }, "hotelId": { "type": "string", "description": "ID of the hotel; the same property keeps it across searches.", "example": "htl_Pd4Mx9TgUa6Rj1WnKc3Sv" }, "name": { "type": "string", "description": "Name of the hotel.", "example": "Hotel Paulista Plaza" }, "cheapestFareAmount": { "type": "number", "description": "Total of the cheapest room found for the hotel, in cents (`125000` is R$ 1.250,00).", "example": 125000 }, "cheapestFareCurrency": { "type": "string", "description": "Currency of `cheapestFareAmount` (ISO 4217).", "example": "BRL" }, "coordinates": { "type": "object", "properties": { "lat": { "type": "number", "description": "Latitude, in decimal degrees.", "example": -23.4356 }, "lng": { "type": "number", "description": "Longitude, in decimal degrees.", "example": -46.4731 } }, "required": [ "lat", "lng" ], "description": "Position of the hotel." } }, "required": [ "itemId", "hotelId", "name", "cheapestFareAmount", "cheapestFareCurrency", "coordinates" ], "description": "A hotel on the map of a search." }, "description": "One point per hotel, with the cheapest room found, in a single unpaginated list. Hotels with no known position are left out, so it can be shorter than the search's `totalCount`. Empty while `status` is `PROCESSING` or `FAILED`." } }, "required": [ "status", "results" ], "description": "Every hotel of a search that can be placed on a map." } } } }, "404": { "description": "`SEARCH_NOT_FOUND` — The search doesn't exist, has expired, was created by another organization or is not a hotel search.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "SEARCH_NOT_FOUND" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "TRAVEL" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b", "code": "SEARCH_NOT_FOUND", "origin": "TRAVEL", "message": "Search not found" } } } }, "422": { "description": "`BAD_REQUEST` — A path parameter is not a valid ID; `fields` lists each one.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "BAD_REQUEST" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "TRAVEL" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." }, "fields": { "type": "array", "description": "One entry per invalid request field (validation errors only).", "items": { "type": "object", "properties": { "field": { "type": "string", "description": "Path of the invalid field, e.g. `label` or `values[0].value`.", "example": "label" }, "message": { "type": "string", "description": "Why the field was rejected.", "example": "label is required" }, "code": { "type": "string", "description": "`_` — e.g. `LABEL_REQUIRED`, `TYPE_ONE_OF`, `VALUES_VALUE_TYPE_ERROR`.", "example": "LABEL_REQUIRED" }, "values": { "type": "array", "items": { "type": "string" }, "description": "The accepted values, when the field is an enumeration." } }, "required": [ "field", "message", "code" ] } } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "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": "organizationId", "message": "Invalid UUID", "code": "ORGANIZATIONID_UUID" } ] } } } }, "503": { "description": "`PROVIDER_UNAVAILABLE` — The travel provider could not be reached. Retry later.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "PROVIDER_UNAVAILABLE" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "TRAVEL" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b", "code": "PROVIDER_UNAVAILABLE", "origin": "TRAVEL", "message": "Travel provider temporarily unavailable, please retry." } } } } }, "x-p3-confidence": { "response": "generated:typed" } } }, "/realms/{realmId}/organizations/{organizationId}/hotel/searches/{searchId}/items/{itemId}": { "get": { "operationId": "getRealmsByRealmIdOrganizationsByOrganizationIdHotelSearchesBySearchIdItemsByItemId", "summary": "Get a hotel search item", "tags": [ "Hotel search" ], "x-p3-sidebar-order": 5, "description": "Returns the full detail of one hotel of a hotel search: the hotel record and its room combinations.", "x-mint": { "content": "Open a hotel of the search results to see what the list only summarizes: the full `hotel` record and the `roomGroups` available for the requested occupancy, each with its rooms and rates. To book it, create a trip with the item's `id` as `searchItemId` and each chosen room's `id` as `roomId`. Amounts are integers in cents: `98700` is R$ 987,00. The item lives as long as its search (see `ttl`). An error the travel provider reports about the request is returned with its own status, `code` and `message`." }, "parameters": [ { "name": "realmId", "in": "path", "required": true, "description": "ID of your realm.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b" }, { "name": "organizationId", "in": "path", "required": true, "description": "ID of your organization.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410" }, { "name": "searchId", "in": "path", "required": true, "description": "ID of the search, as returned when it was created.", "schema": { "type": "string", "pattern": "^srch_[0-9A-Za-z]{21}$" }, "example": "srch_V1StGXR8Z5jdHi6BmyT2k" }, { "name": "itemId", "in": "path", "required": true, "description": "ID of the item to load, as listed in the `items` of the search results.", "schema": { "type": "string", "pattern": "^srch_item_[0-9A-Za-z]{21}$" }, "example": "srch_item_V1StGXR8Z5jdHi6BmyT2k" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the item. Send it as `searchItemId` when you create a trip.", "example": "srch_item_Zt5Hk2NwQe8Lr3VcXb1Ya" }, "searchId": { "type": "string", "description": "ID of the search the item belongs to.", "example": "srch_Qm8Zt3LwXc1Ry7NvB0kHd" }, "hotel": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the hotel; the same property keeps it across searches.", "example": "htl_Pd4Mx9TgUa6Rj1WnKc3Sv" }, "name": { "type": "string", "description": "Name of the hotel.", "example": "Hotel Paulista Plaza" }, "address": { "type": "object", "properties": { "shortAddress": { "type": "string", "nullable": true, "description": "The address in a single line. `null` when unknown.", "example": "Guarulhos, SP, Brazil" }, "adressLines": { "type": "array", "items": { "type": "string", "example": "Rod. Hélio Smidt, s/n" }, "description": "The address in postal lines. Empty when unknown. The field name is spelled `adressLines`.\n\n---\n\nExample: `[\"Rod. Hélio Smidt, s/n\"]`" }, "locality": { "type": "string", "nullable": true, "description": "City. `null` when unknown.", "example": "Guarulhos" }, "administrativeArea": { "type": "string", "nullable": true, "description": "State or province code. `null` when unknown.", "example": "SP" }, "administrativeAreaName": { "type": "string", "nullable": true, "description": "State or province name. `null` when unknown.", "example": "São Paulo" }, "postalCode": { "type": "string", "nullable": true, "description": "Postal code. `null` when unknown.", "example": "07190-100" }, "country": { "type": "string", "description": "Country (ISO 3166-1 alpha-2).", "example": "BR" }, "timezone": { "type": "string", "description": "IANA time zone of the place, or `Unknown`.", "example": "America/Sao_Paulo" }, "coordinates": { "description": "Position of the place. `null` when unknown.", "type": "object", "properties": { "lat": { "type": "number", "description": "Latitude, in decimal degrees.", "example": -23.4356 }, "lng": { "type": "number", "description": "Longitude, in decimal degrees.", "example": -46.4731 } }, "required": [ "lat", "lng" ], "nullable": true }, "localityId": { "type": "string", "nullable": true, "description": "ID of the locality the bus station belongs to. Bus stations only; `null` when the station is not grouped under a locality." } }, "required": [ "shortAddress", "adressLines", "locality", "administrativeArea", "administrativeAreaName", "postalCode", "country", "timezone", "coordinates" ], "description": "Address and position of the hotel." }, "phoneNumbers": { "type": "array", "items": { "type": "string", "example": "+551133334444" }, "description": "Contact phone numbers. Empty when none is registered.\n\n---\n\nExample: `[\"+551133334444\"]`" }, "emails": { "type": "array", "items": { "type": "string", "example": "reservas@paulistaplaza.example.com" }, "description": "Contact e-mails. Empty when none is registered.\n\n---\n\nExample: `[\"reservas@paulistaplaza.example.com\"]`" }, "website": { "type": "string", "nullable": true, "description": "Website. `null` when none is registered.", "example": "https://example.com/paulista-plaza" }, "amenities": { "type": "array", "items": { "type": "string", "example": "RESTAURANT" }, "description": "Amenities of the hotel, as codes.\n\n---\n\nExample: `[\"RESTAURANT\",\"EXERCISE_GYM\"]`" }, "description": { "type": "string", "description": "Description of the hotel.", "example": "Four-star hotel on Avenida Paulista, close to the subway." }, "chain": { "type": "object", "properties": { "brandName": { "type": "string", "nullable": true, "description": "Brand within the chain. `null` when unknown.", "example": "Aurora Express" }, "chainName": { "type": "string", "nullable": true, "description": "Chain. `null` for an independent hotel.", "example": "Grupo Aurora" }, "logo": { "type": "string", "nullable": true, "description": "URL of the chain's logo. `null` when there is none.", "example": "https://example.com/logos/aurora.svg" } }, "required": [ "brandName", "chainName", "logo" ], "description": "Chain and brand of the hotel." }, "starRating": { "type": "string", "enum": [ "0", "1", "2", "3", "4", "5" ], "description": "Star rating, `0` to `5`.", "example": "4" }, "publicRating": { "type": "number", "description": "Public rating score, typically 0 to 10.", "example": 8.6 }, "propertyType": { "type": "string", "description": "Kind of property, as a code (`HOTEL`, `RESORT`, `HOSTEL`…).", "example": "HOTEL" }, "mainImage": { "type": "object", "properties": { "category": { "type": "string", "description": "What the image shows, as a code.", "example": "EXTERIOR_VIEW" }, "uri": { "type": "string", "description": "URL of the image.", "example": "https://example.com/hotels/paulista-plaza/exterior.jpg" }, "blurHash": { "type": "string", "description": "BlurHash placeholder for previews. Omitted when unavailable.", "example": "LEHV6nWB2yk8pyo0adR*.7kCMdnj" }, "dominantColor": { "type": "string", "description": "Dominant color, as hex. Omitted when unavailable.", "example": "#8a9fb3" } }, "required": [ "category", "uri" ], "description": "Cover image." }, "images": { "type": "array", "items": { "type": "object", "properties": { "category": { "type": "string", "description": "What the image shows, as a code.", "example": "EXTERIOR_VIEW" }, "uri": { "type": "string", "description": "URL of the image.", "example": "https://example.com/hotels/paulista-plaza/exterior.jpg" }, "blurHash": { "type": "string", "description": "BlurHash placeholder for previews. Omitted when unavailable.", "example": "LEHV6nWB2yk8pyo0adR*.7kCMdnj" }, "dominantColor": { "type": "string", "description": "Dominant color, as hex. Omitted when unavailable.", "example": "#8a9fb3" } }, "required": [ "category", "uri" ], "description": "An image of a hotel or room." }, "description": "More images. Empty when none." }, "checkInTime": { "type": "string", "nullable": true, "description": "Standard check-in time (`HH:mm`). `null` when not informed.", "example": "14:00" }, "checkOutTime": { "type": "string", "nullable": true, "description": "Standard check-out time (`HH:mm`). `null` when not informed.", "example": "12:00" }, "rooms": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the room.", "example": "Standard Double" }, "description": { "type": "string", "description": "Description of the room.", "example": "Double room with city view, 28 m²." }, "amenities": { "type": "array", "items": { "type": "string", "example": "AIR_CONDITIONING" }, "description": "Amenities of the room, as codes.\n\n---\n\nExample: `[\"AIR_CONDITIONING\",\"MINIBAR\"]`" }, "images": { "type": "array", "items": { "type": "object", "properties": { "category": { "type": "string", "description": "What the image shows, as a code.", "example": "EXTERIOR_VIEW" }, "uri": { "type": "string", "description": "URL of the image.", "example": "https://example.com/hotels/paulista-plaza/exterior.jpg" }, "blurHash": { "type": "string", "description": "BlurHash placeholder for previews. Omitted when unavailable.", "example": "LEHV6nWB2yk8pyo0adR*.7kCMdnj" }, "dominantColor": { "type": "string", "description": "Dominant color, as hex. Omitted when unavailable.", "example": "#8a9fb3" } }, "required": [ "category", "uri" ], "description": "An image of a hotel or room." }, "description": "Images of the room. Empty when none." } }, "required": [ "name", "description", "amenities", "images" ], "description": "A room type in the hotel's catalogue." }, "description": "The room types the hotel offers." }, "status": { "type": "string", "enum": [ "ACTIVE", "INACTIVE" ], "description": "`ACTIVE` or `INACTIVE`.", "example": "ACTIVE" } }, "required": [ "id", "name", "address", "phoneNumbers", "emails", "website", "amenities", "description", "chain", "starRating", "publicRating", "propertyType", "mainImage", "images", "checkInTime", "checkOutTime", "rooms", "status" ], "description": "The full record of the hotel." }, "checkIn": { "type": "string", "description": "Check-in date (`YYYY-MM-DD`).", "example": "2026-11-02" }, "checkOut": { "type": "string", "description": "Check-out date (`YYYY-MM-DD`).", "example": "2026-11-05" }, "roomGroups": { "type": "array", "items": { "type": "object", "properties": { "rooms": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the room offer. Send it as `roomId` when you create a trip.", "example": "room_Gt6Ws1KeYb4Nc8PqLr2Xd" }, "passengers": { "type": "object", "properties": { "adult": { "type": "number", "description": "Adults.", "example": 2 }, "child": { "type": "number", "description": "Children.", "example": 0 }, "infant": { "type": "number", "description": "Infants.", "example": 0 }, "senior": { "type": "number", "description": "Seniors.", "example": 0 } }, "required": [ "adult", "child", "infant", "senior" ], "description": "Who the offer is for." }, "quantity": { "type": "number", "nullable": true, "description": "Number of rooms available at this rate. `null` when not informed.", "example": 3 }, "roomName": { "type": "string", "description": "Name of the room.", "example": "Standard Double" }, "fare": { "type": "object", "properties": { "originalAmount": { "type": "number", "description": "Price before discounts and fees, in cents.", "example": 135000 }, "discountAmount": { "type": "number", "description": "Discount applied to the original amount, in cents.", "example": 15000 }, "feeAmount": { "type": "number", "description": "Fees added to the rate, in cents.", "example": 5000 }, "amount": { "type": "number", "description": "Total rate charged: `originalAmount - discountAmount + feeAmount`, in cents (`125000` is R$ 1.250,00).", "example": 125000 }, "currency": { "type": "string", "description": "Currency of the amounts (ISO 4217).", "example": "BRL" }, "boardType": { "type": "string", "enum": [ "ONLY_ROOM", "BREAKFAST", "HALF_BOARD", "FULL_BOARD", "ALL_INCLUSIVE" ], "description": "Meal plan: `ONLY_ROOM`, `BREAKFAST`, `HALF_BOARD`, `FULL_BOARD` or `ALL_INCLUSIVE`.", "example": "BREAKFAST" }, "cancellationPolicies": { "type": "object", "properties": { "refundable": { "type": "boolean", "description": "Whether the fare allows any refund at all.", "example": true }, "immediateFine": { "type": "boolean", "description": "Whether a fine is charged for cancelling right after booking.", "example": false }, "penalties": { "type": "array", "items": { "type": "object", "properties": { "from": { "type": "string", "description": "Date (`YYYY-MM-DD`) from which this tier applies.", "example": "2026-10-30" }, "currency": { "type": "string", "description": "Currency of the penalty (ISO 4217).", "example": "BRL" }, "fineAmount": { "type": "number", "description": "Penalty charged when cancelling or changing from `from` onward, in cents.", "example": 15000 } }, "required": [ "from", "currency", "fineAmount" ], "description": "One tier of a cancellation or change penalty schedule." }, "description": "Penalty schedule, in effect from each tier's date. Empty or omitted when no scheduled penalty applies." } }, "required": [ "refundable", "immediateFine" ], "description": "Cancellation rules of the rate. Only in the item detail, not in the search results." } }, "required": [ "originalAmount", "discountAmount", "feeAmount", "amount", "currency", "boardType" ], "description": "Rate of the room, with its cancellation rules." } }, "required": [ "id", "passengers", "quantity", "roomName", "fare" ], "description": "A bookable room with its rate." }, "description": "The bookable rooms of the combination." } }, "required": [ "rooms" ], "description": "The rooms offered together to fulfil the requested occupancy: one per room of the search." }, "description": "The room combinations available for the requested occupancy, each with its rooms and rates — send a room's `id` as `roomId` when you create a trip." } }, "required": [ "id", "searchId", "hotel", "checkIn", "checkOut", "roomGroups" ], "description": "The detail of one hotel of a hotel search: the full hotel record and its room combinations." } } } }, "404": { "description": "`SEARCH_NOT_FOUND` — The search doesn't exist, has expired, was created by another organization or is not a hotel search.\n\n`HOTEL_SEARCH_ITEM_NOT_FOUND` — The hotel search has no item with this ID, or it expired.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "SEARCH_NOT_FOUND", "HOTEL_SEARCH_ITEM_NOT_FOUND" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "TRAVEL" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b", "code": "SEARCH_NOT_FOUND", "origin": "TRAVEL", "message": "Search not found" } } } }, "422": { "description": "`BAD_REQUEST` — A path parameter is not a valid ID; `fields` lists each one.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "BAD_REQUEST" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "TRAVEL" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." }, "fields": { "type": "array", "description": "One entry per invalid request field (validation errors only).", "items": { "type": "object", "properties": { "field": { "type": "string", "description": "Path of the invalid field, e.g. `label` or `values[0].value`.", "example": "label" }, "message": { "type": "string", "description": "Why the field was rejected.", "example": "label is required" }, "code": { "type": "string", "description": "`_` — e.g. `LABEL_REQUIRED`, `TYPE_ONE_OF`, `VALUES_VALUE_TYPE_ERROR`.", "example": "LABEL_REQUIRED" }, "values": { "type": "array", "items": { "type": "string" }, "description": "The accepted values, when the field is an enumeration." } }, "required": [ "field", "message", "code" ] } } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "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": "organizationId", "message": "Invalid UUID", "code": "ORGANIZATIONID_UUID" } ] } } } }, "503": { "description": "`PROVIDER_UNAVAILABLE` — The travel provider could not be reached. Retry later.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "PROVIDER_UNAVAILABLE" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "TRAVEL" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b", "code": "PROVIDER_UNAVAILABLE", "origin": "TRAVEL", "message": "Travel provider temporarily unavailable, please retry." } } } } }, "x-p3-confidence": { "response": "generated:typed" } } }, "/realms/{realmId}/organizations/{organizationId}/bus/locations": { "get": { "operationId": "getRealmsByRealmIdOrganizationsByOrganizationIdBusLocations", "summary": "Search bus stations", "tags": [ "Bus search" ], "x-p3-sidebar-order": 1, "description": "Searches bus stations for a bus search.", "x-mint": { "content": "Use it to fill the origin and destination pickers before you create a bus search, then send the station's `id` — or its `slug` — as `from` or `to`. Matches come most relevant first, and an empty `results` means nothing matched. An error the travel provider reports about the request is returned with its own status, `code` and `message`." }, "parameters": [ { "name": "realmId", "in": "path", "required": true, "description": "ID of your realm.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b" }, { "name": "organizationId", "in": "path", "required": true, "description": "ID of your organization.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410" }, { "name": "query", "in": "query", "required": true, "description": "Text to search bus stations for: part of the station or city name, a slug or an address, case-insensitive.", "schema": { "type": "string", "minLength": 1 }, "example": "Tiete" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the station. Use it, or its `slug`, as `from` / `to` of a bus search.", "example": "bus_sta_Ts5Gm8XqVb2Hw7NcKe1Ld" }, "name": { "type": "string", "description": "Official name of the station.", "example": "Terminal Rodoviário Tietê" }, "slug": { "type": "string", "description": "Readable unique identifier of the station.", "example": "terminal-rodoviario-tiete" }, "address": { "type": "object", "properties": { "shortAddress": { "type": "string", "nullable": true, "description": "The address in a single line. `null` when unknown.", "example": "Guarulhos, SP, Brazil" }, "adressLines": { "type": "array", "items": { "type": "string", "example": "Rod. Hélio Smidt, s/n" }, "description": "The address in postal lines. Empty when unknown. The field name is spelled `adressLines`.\n\n---\n\nExample: `[\"Rod. Hélio Smidt, s/n\"]`" }, "locality": { "type": "string", "nullable": true, "description": "City. `null` when unknown.", "example": "Guarulhos" }, "administrativeArea": { "type": "string", "nullable": true, "description": "State or province code. `null` when unknown.", "example": "SP" }, "administrativeAreaName": { "type": "string", "nullable": true, "description": "State or province name. `null` when unknown.", "example": "São Paulo" }, "postalCode": { "type": "string", "nullable": true, "description": "Postal code. `null` when unknown.", "example": "07190-100" }, "country": { "type": "string", "description": "Country (ISO 3166-1 alpha-2).", "example": "BR" }, "timezone": { "type": "string", "description": "IANA time zone of the place, or `Unknown`.", "example": "America/Sao_Paulo" }, "coordinates": { "description": "Position of the place. `null` when unknown.", "type": "object", "properties": { "lat": { "type": "number", "description": "Latitude, in decimal degrees.", "example": -23.4356 }, "lng": { "type": "number", "description": "Longitude, in decimal degrees.", "example": -46.4731 } }, "required": [ "lat", "lng" ], "nullable": true }, "localityId": { "type": "string", "nullable": true, "description": "ID of the locality the bus station belongs to. Bus stations only; `null` when the station is not grouped under a locality." } }, "required": [ "shortAddress", "adressLines", "locality", "administrativeArea", "administrativeAreaName", "postalCode", "country", "timezone", "coordinates" ], "description": "Address and position of the station." }, "terminalName": { "type": "string", "nullable": true, "description": "Terminal label, when the station has more than one. `null` otherwise." }, "phoneNumbers": { "type": "array", "items": { "type": "string", "example": "+551122222222" }, "description": "Contact phone numbers. Empty when none is registered.\n\n---\n\nExample: `[\"+551122222222\"]`" }, "groupByLocality": { "type": "boolean", "description": "Whether the station is grouped with its siblings of the same locality when results are shown.", "example": true } }, "required": [ "id", "name", "slug", "address", "terminalName", "phoneNumbers", "groupByLocality" ], "description": "A bus station (`bus` locations)." }, "description": "Matching bus stations, most relevant first. Empty when nothing matches." } }, "required": [ "results" ], "description": "The bus stations matching a bus location search." } } } }, "422": { "description": "`BAD_REQUEST` — A path parameter is not a valid ID, or `query` is missing or blank; `fields` lists each one.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "BAD_REQUEST" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "TRAVEL" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." }, "fields": { "type": "array", "description": "One entry per invalid request field (validation errors only).", "items": { "type": "object", "properties": { "field": { "type": "string", "description": "Path of the invalid field, e.g. `label` or `values[0].value`.", "example": "label" }, "message": { "type": "string", "description": "Why the field was rejected.", "example": "label is required" }, "code": { "type": "string", "description": "`_` — e.g. `LABEL_REQUIRED`, `TYPE_ONE_OF`, `VALUES_VALUE_TYPE_ERROR`.", "example": "LABEL_REQUIRED" }, "values": { "type": "array", "items": { "type": "string" }, "description": "The accepted values, when the field is an enumeration." } }, "required": [ "field", "message", "code" ] } } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "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": "query", "message": "Invalid input: expected string, received undefined", "code": "QUERY_REQUIRED" } ] } } } }, "503": { "description": "`PROVIDER_UNAVAILABLE` — The travel provider could not be reached. Retry later.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "PROVIDER_UNAVAILABLE" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "TRAVEL" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b", "code": "PROVIDER_UNAVAILABLE", "origin": "TRAVEL", "message": "Travel provider temporarily unavailable, please retry." } } } } }, "x-p3-confidence": { "response": "generated:typed", "parameters": "generated:typed" } } }, "/realms/{realmId}/organizations/{organizationId}/bus/searches": { "post": { "operationId": "postRealmsByRealmIdOrganizationsByOrganizationIdBusSearches", "summary": "Create a bus search", "tags": [ "Bus search" ], "x-p3-sidebar-order": 2, "description": "Starts a search for bus trips between two stations, one way or round trip.", "x-mint": { "content": "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.\n\nFind `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`.\n\nAn error the travel provider reports about the request — an unknown station, say — is returned with its own status, `code` and `message`." }, "parameters": [ { "name": "realmId", "in": "path", "required": true, "description": "ID of your realm.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b" }, { "name": "organizationId", "in": "path", "required": true, "description": "ID of your organization.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "from": { "type": "string", "minLength": 1, "description": "Origin bus station: its `id` or its `slug` from the locations endpoint. Must differ from `to`.", "example": "terminal-rodoviario-tiete" }, "to": { "type": "string", "minLength": 1, "description": "Destination bus station: its `id` or its `slug` from the locations endpoint. Must differ from `from`.", "example": "rodoviaria-novo-rio" }, "departureDate": { "type": "string", "minLength": 1, "description": "Outbound trip date (`YYYY-MM-DD`). Today or later.", "example": "2026-11-02" }, "returnDate": { "description": "Return trip date (`YYYY-MM-DD`), on or after `departureDate`. Omit it for a one-way trip.", "example": "2026-11-05", "type": "string", "minLength": 1 }, "serviceClass": { "description": "Preferred service class: `SLEEPER_BED`, `BED`, `SEMI_BED`, `EXECUTIVE`, `CONVENTIONAL` or `UNDEFINED`. Omit it to search every class.", "example": "EXECUTIVE", "type": "string", "minLength": 1 } }, "required": [ "from", "to", "departureDate" ] } } } }, "responses": { "202": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the search. The same search parameters, within the time the search lasts, return the same ID.", "example": "srch_Fg4Ju9SaPe2Wx6TnCi5Oz" }, "searchParams": { "type": "object", "properties": { "from": { "type": "string", "description": "Origin station, as sent.", "example": "terminal-rodoviario-tiete" }, "to": { "type": "string", "description": "Destination station, as sent.", "example": "rodoviaria-novo-rio" }, "departureDate": { "type": "string", "description": "Outbound date, as sent.", "example": "2026-11-02" }, "returnDate": { "type": "string", "description": "Return date, as sent. Absent for a one-way trip.", "example": "2026-11-05" }, "serviceClass": { "type": "string", "enum": [ "SLEEPER_BED", "BED", "SEMI_BED", "EXECUTIVE", "CONVENTIONAL", "UNDEFINED" ], "description": "Service class preference, as sent. Absent when the request had none.", "example": "EXECUTIVE" } }, "required": [ "from", "to", "departureDate" ], "description": "What the search was made for." }, "type": { "type": "string", "enum": [ "BUS" ], "description": "Always `BUS`.", "example": "BUS" }, "status": { "type": "string", "enum": [ "PROCESSING", "FAILED", "COMPLETED" ], "description": "`PROCESSING` right after creation. It becomes `COMPLETED` or `FAILED` on its own: poll the search.", "example": "PROCESSING" }, "warning": { "description": "How the search went across the suppliers. `null` while it is processing.", "type": "object", "properties": { "code": { "type": "string", "enum": [ "ALL_FAILED", "PARTIAL_SUCCESS", "ALL_SUCCESS" ], "description": "`ALL_SUCCESS`: every supplier answered. `PARTIAL_SUCCESS`: some suppliers failed, so the results may be incomplete. `ALL_FAILED`: no supplier answered.", "example": "ALL_SUCCESS" }, "message": { "type": "string", "description": "Human-readable explanation.", "example": "All suppliers answered." } }, "required": [ "code", "message" ], "nullable": true }, "ttl": { "type": "number", "description": "Seconds until the search expires.", "example": 900 }, "facets": { "description": "Facets to build filters from (companies, service classes, price ranges). `null` until the search completes.", "type": "object", "additionalProperties": {}, "nullable": true }, "createdAt": { "type": "string", "description": "When the search was created.", "example": "2026-10-19T15:00:00.000Z", "format": "date-time" } }, "required": [ "id", "searchParams", "type", "status", "warning", "ttl", "facets", "createdAt" ], "description": "A search just created for bus trips. Results come later: poll the search." } } } }, "422": { "description": "`BAD_REQUEST` — A path parameter is not a valid ID or the body failed validation; `fields` lists each offending field.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "BAD_REQUEST" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "TRAVEL" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." }, "fields": { "type": "array", "description": "One entry per invalid request field (validation errors only).", "items": { "type": "object", "properties": { "field": { "type": "string", "description": "Path of the invalid field, e.g. `label` or `values[0].value`.", "example": "label" }, "message": { "type": "string", "description": "Why the field was rejected.", "example": "label is required" }, "code": { "type": "string", "description": "`_` — e.g. `LABEL_REQUIRED`, `TYPE_ONE_OF`, `VALUES_VALUE_TYPE_ERROR`.", "example": "LABEL_REQUIRED" }, "values": { "type": "array", "items": { "type": "string" }, "description": "The accepted values, when the field is an enumeration." } }, "required": [ "field", "message", "code" ] } } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "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" } ] } } } }, "503": { "description": "`PROVIDER_UNAVAILABLE` — The travel provider could not be reached; no search was created. Retry later.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "PROVIDER_UNAVAILABLE" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "TRAVEL" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b", "code": "PROVIDER_UNAVAILABLE", "origin": "TRAVEL", "message": "Travel provider temporarily unavailable, please retry." } } } } }, "x-p3-confidence": { "response": "generated:typed", "request": "generated:typed" } } }, "/realms/{realmId}/organizations/{organizationId}/bus/searches/{searchId}": { "get": { "operationId": "getRealmsByRealmIdOrganizationsByOrganizationIdBusSearchesBySearchId", "summary": "Get a bus search and its results", "tags": [ "Bus search" ], "x-p3-sidebar-order": 3, "description": "Returns a bus search and, once it has finished, one page of its trips.", "x-mint": { "content": "Searches are asynchronous: while `status` is `PROCESSING` only the search itself comes back, so poll until it is `COMPLETED`, then read `items`. A `FAILED` search has no results. A bus search expires after its `ttl` (15 minutes) and then answers `404 SEARCH_NOT_FOUND`. Only the organization that created a search can read it.\n\nResults come in pages. Sort them with `order` and `orderBy`, narrow them with `minAmount`, `maxAmount`, `type`, `serviceClass`, `company`, `departureOriginName`, `departureDestinationName`, `departureTimePeriod`, `returnOriginName`, `returnDestinationName`, `returnTimePeriod` and `routeDirection`, then walk the pages with `limit` and the `next` cursor each response returns (`null` on the last page). A filter that takes several values accepts them repeated or comma-separated (`?serviceClass=EXECUTIVE&serviceClass=SEMI_BED` or `?serviceClass=EXECUTIVE,SEMI_BED`). Amounts are integers in cents: `98700` is R$ 987,00.\n\nEach item is a summary with its cheapest fare. To book one, open it with the bus search item endpoint for everything a trip needs, and create the trip with the item's `id` as `searchItemId`. An error the travel provider reports about the request — a filter value it does not accept, say — is returned with its own status, `code` and `message`." }, "parameters": [ { "name": "realmId", "in": "path", "required": true, "description": "ID of your realm.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b" }, { "name": "organizationId", "in": "path", "required": true, "description": "ID of your organization.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410" }, { "name": "searchId", "in": "path", "required": true, "description": "ID of the bus search, as returned when it was created.", "schema": { "type": "string", "pattern": "^srch_[0-9A-Za-z]{21}$" }, "example": "srch_V1StGXR8Z5jdHi6BmyT2k" }, { "name": "order", "in": "query", "required": false, "description": "Sort direction applied to `orderBy`: `ASC` lists the cheapest results first, `DESC` the most expensive first.", "schema": { "type": "string", "enum": [ "ASC", "DESC" ] }, "example": "ASC" }, { "name": "orderBy", "in": "query", "required": false, "description": "Field to sort the results by. Currently only `amount` is supported.", "schema": { "type": "string", "minLength": 1 }, "example": "amount" }, { "name": "next", "in": "query", "required": false, "description": "Cursor returned as `next` by the previous page. Omit for the first page.", "schema": { "type": "string", "minLength": 1 }, "example": "eyJwIjoyfQ==" }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of items per page, from 1 to 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "example": 20 }, { "name": "minAmount", "in": "query", "required": false, "description": "Only results costing at least this amount, in the same unit as the `amount` of the results (cents).", "schema": { "type": "number", "minimum": 0 }, "example": 20000 }, { "name": "maxAmount", "in": "query", "required": false, "description": "Only results costing at most this amount, in the same unit as the `amount` of the results (cents).", "schema": { "type": "number", "minimum": 0 }, "example": 100000 }, { "name": "type", "in": "query", "required": false, "description": "Only trips of these types: `DIRECT`, `CONNECTION` or `ONE_STOP`.\n\n---\n\nExample (comma-separated list): `?type=DIRECT,ONE_STOP`", "schema": { "type": "array", "items": { "type": "string" } }, "style": "form", "explode": false }, { "name": "serviceClass", "in": "query", "required": false, "description": "Only these service classes: `SLEEPER_BED`, `BED`, `SEMI_BED`, `EXECUTIVE`, `CONVENTIONAL` or `UNDEFINED`.\n\n---\n\nExample (comma-separated list): `?serviceClass=EXECUTIVE,SEMI_BED`", "schema": { "type": "array", "items": { "type": "string" } }, "style": "form", "explode": false }, { "name": "company", "in": "query", "required": false, "description": "Only trips run by these bus companies, by name.\n\n---\n\nExample (comma-separated list): `?company=Viação Aurora,Expresso Litoral`", "schema": { "type": "array", "items": { "type": "string" } }, "style": "form", "explode": false }, { "name": "departureOriginName", "in": "query", "required": false, "description": "Only outbound trips leaving from these stations, by name.\n\n---\n\nExample (comma-separated list): `?departureOriginName=Terminal Rodoviário Tietê,Terminal Barra Funda`", "schema": { "type": "array", "items": { "type": "string" } }, "style": "form", "explode": false }, { "name": "departureDestinationName", "in": "query", "required": false, "description": "Only outbound trips arriving at these stations, by name.\n\n---\n\nExample (comma-separated list): `?departureDestinationName=Rodoviária Novo Rio,Terminal Américo Fontenelle`", "schema": { "type": "array", "items": { "type": "string" } }, "style": "form", "explode": false }, { "name": "departureTimePeriod", "in": "query", "required": false, "description": "Only outbound trips leaving in these periods of the day: `DAWN`, `MORNING`, `AFTERNOON` or `NIGHT`.\n\n---\n\nExample (comma-separated list): `?departureTimePeriod=MORNING,AFTERNOON`", "schema": { "type": "array", "items": { "type": "string" } }, "style": "form", "explode": false }, { "name": "returnOriginName", "in": "query", "required": false, "description": "Only return trips leaving from these stations, by name.\n\n---\n\nExample (comma-separated list): `?returnOriginName=Rodoviária Novo Rio,Terminal Américo Fontenelle`", "schema": { "type": "array", "items": { "type": "string" } }, "style": "form", "explode": false }, { "name": "returnDestinationName", "in": "query", "required": false, "description": "Only return trips arriving at these stations, by name.\n\n---\n\nExample (comma-separated list): `?returnDestinationName=Terminal Rodoviário Tietê,Terminal Barra Funda`", "schema": { "type": "array", "items": { "type": "string" } }, "style": "form", "explode": false }, { "name": "returnTimePeriod", "in": "query", "required": false, "description": "Only return trips leaving in these periods of the day: `DAWN`, `MORNING`, `AFTERNOON` or `NIGHT`.\n\n---\n\nExample (comma-separated list): `?returnTimePeriod=NIGHT,DAWN`", "schema": { "type": "array", "items": { "type": "string" } }, "style": "form", "explode": false }, { "name": "routeDirection", "in": "query", "required": false, "description": "Only trips in one direction: `DEPARTURE` (outbound) or `RETURN`. Omit it to get both.", "schema": { "type": "string", "minLength": 1 }, "example": "DEPARTURE" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the search.", "example": "srch_V1StGXR8Z5jdHi6BmyT2k" }, "status": { "type": "string", "enum": [ "PROCESSING", "FAILED", "COMPLETED" ], "description": "`PROCESSING` while the suppliers answer, then `COMPLETED` or `FAILED`. Only `COMPLETED` carries `items`.", "example": "COMPLETED" }, "warning": { "description": "How the search went across the suppliers. `null` while it is processing.", "type": "object", "properties": { "code": { "type": "string", "enum": [ "ALL_FAILED", "PARTIAL_SUCCESS", "ALL_SUCCESS" ], "description": "`ALL_SUCCESS`: every supplier answered. `PARTIAL_SUCCESS`: some suppliers failed, so the results may be incomplete. `ALL_FAILED`: no supplier answered.", "example": "ALL_SUCCESS" }, "message": { "type": "string", "description": "Human-readable explanation.", "example": "All suppliers answered." } }, "required": [ "code", "message" ], "nullable": true }, "createdAt": { "type": "string", "description": "When the search was created.", "example": "2026-10-19T15:00:00.000Z", "format": "date-time" }, "next": { "type": "string", "nullable": true, "description": "Cursor for the next page. `null` on the last page. Present only once the search is `COMPLETED`.", "example": "eyJwIjoyfQ==" }, "totalCount": { "type": "number", "description": "Number of results that match the filters, across every page. Present only once the search is `COMPLETED`.", "example": 1 }, "searchParams": { "type": "object", "properties": { "from": { "type": "string", "description": "Origin station, as sent.", "example": "terminal-rodoviario-tiete" }, "to": { "type": "string", "description": "Destination station, as sent.", "example": "rodoviaria-novo-rio" }, "departureDate": { "type": "string", "description": "Outbound date, as sent.", "example": "2026-11-02" }, "returnDate": { "type": "string", "description": "Return date, as sent. Absent for a one-way trip.", "example": "2026-11-05" }, "serviceClass": { "type": "string", "enum": [ "SLEEPER_BED", "BED", "SEMI_BED", "EXECUTIVE", "CONVENTIONAL", "UNDEFINED" ], "description": "Service class preference, as sent. Absent when the request had none.", "example": "EXECUTIVE" } }, "required": [ "from", "to", "departureDate" ], "description": "What the search was made for, as sent." }, "type": { "type": "string", "enum": [ "BUS" ], "description": "Always `BUS`.", "example": "BUS" }, "ttl": { "type": "number", "description": "Seconds until the search expires (a bus search lasts 15 minutes).", "example": 640 }, "facets": { "description": "Facets to build filters from (companies, service classes, price ranges). `null` until the search completes.", "type": "object", "additionalProperties": {}, "nullable": true }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the item. Use it to load the item (seat maps and per-segment fares); send it as `searchItemId` when you create a trip.", "example": "srch_item_Lc7Ve3PsKd9Ny2QtXw5Mb" }, "searchId": { "type": "string", "description": "ID of the search the item belongs to.", "example": "srch_Fg4Ju9SaPe2Wx6TnCi5Oz" }, "type": { "type": "string", "enum": [ "DIRECT", "CONNECTION", "ONE_STOP" ], "description": "`DIRECT`, `CONNECTION` or `ONE_STOP`.", "example": "DIRECT" }, "routeDirection": { "type": "string", "enum": [ "DEPARTURE", "RETURN" ], "description": "Whether the trip is an outbound (`DEPARTURE`) or a return (`RETURN`) one.", "example": "DEPARTURE" }, "origin": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the station.", "example": "bus_sta_Ts5Gm8XqVb2Hw7NcKe1Ld" }, "slug": { "type": "string", "description": "Readable unique identifier of the station.", "example": "terminal-rodoviario-tiete" }, "locality": { "type": "string", "description": "City.", "example": "São Paulo" }, "administrativeArea": { "type": "string", "description": "State code.", "example": "SP" }, "name": { "type": "string", "nullable": true, "description": "Official name of the station. `null` when not informed.", "example": "Terminal Rodoviário Tietê" }, "shortAddress": { "type": "string", "nullable": true, "description": "The address in a single line. `null` when unknown.", "example": "Av. Cruzeiro do Sul, 1800, São Paulo, SP" }, "phoneNumbers": { "type": "array", "items": { "type": "string", "example": "+551122222222" }, "description": "Contact phone numbers. Empty when none is registered.\n\n---\n\nExample: `[\"+551122222222\"]`" }, "coordinates": { "description": "Position of the station. `null` when unknown.", "type": "object", "properties": { "lat": { "type": "number", "description": "Latitude, in decimal degrees.", "example": -23.4356 }, "lng": { "type": "number", "description": "Longitude, in decimal degrees.", "example": -46.4731 } }, "required": [ "lat", "lng" ], "nullable": true } }, "required": [ "id", "slug", "locality", "administrativeArea", "name", "shortAddress", "phoneNumbers", "coordinates" ], "description": "Origin station." }, "destination": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the station.", "example": "bus_sta_Ts5Gm8XqVb2Hw7NcKe1Ld" }, "slug": { "type": "string", "description": "Readable unique identifier of the station.", "example": "terminal-rodoviario-tiete" }, "locality": { "type": "string", "description": "City.", "example": "São Paulo" }, "administrativeArea": { "type": "string", "description": "State code.", "example": "SP" }, "name": { "type": "string", "nullable": true, "description": "Official name of the station. `null` when not informed.", "example": "Terminal Rodoviário Tietê" }, "shortAddress": { "type": "string", "nullable": true, "description": "The address in a single line. `null` when unknown.", "example": "Av. Cruzeiro do Sul, 1800, São Paulo, SP" }, "phoneNumbers": { "type": "array", "items": { "type": "string", "example": "+551122222222" }, "description": "Contact phone numbers. Empty when none is registered.\n\n---\n\nExample: `[\"+551122222222\"]`" }, "coordinates": { "description": "Position of the station. `null` when unknown.", "type": "object", "properties": { "lat": { "type": "number", "description": "Latitude, in decimal degrees.", "example": -23.4356 }, "lng": { "type": "number", "description": "Longitude, in decimal degrees.", "example": -46.4731 } }, "required": [ "lat", "lng" ], "nullable": true } }, "required": [ "id", "slug", "locality", "administrativeArea", "name", "shortAddress", "phoneNumbers", "coordinates" ], "description": "Destination station." }, "departureDate": { "type": "string", "description": "Departure, in the local time of the origin station (`YYYY-MM-DDTHH:mm:ss`, no time-zone offset).", "example": "2026-11-02T22:30:00" }, "arrivalDate": { "type": "string", "description": "Arrival, in the local time of the destination station (`YYYY-MM-DDTHH:mm:ss`, no time-zone offset).", "example": "2026-11-03T05:15:00" }, "company": { "type": "object", "properties": { "name": { "type": "string", "description": "Commercial name.", "example": "Viação Aurora" }, "logo": { "type": "string", "nullable": true, "description": "URL of the company's logo. `null` when unknown.", "example": "https://example.com/logos/aurora-bus.svg" }, "id": { "type": "string", "nullable": true, "description": "ID of the company. `null` when not informed.", "example": "bus_co_Nx3Rp8YtKd5Wc1LqHe7Va" } }, "required": [ "name", "logo", "id" ], "description": "Company that runs the trip." }, "availableSeats": { "type": "number", "description": "Seats available to book.", "example": 18 }, "totalSeats": { "type": "number", "nullable": true, "description": "Seats on the bus. `null` when not informed.", "example": 42 }, "lowFareAvailableSeats": { "type": "number", "nullable": true, "description": "Low-fare seats still available. `null` when not informed.", "example": 4 }, "fare": { "type": "object", "properties": { "originalAmount": { "type": "number", "description": "Price before discounts and fees, in cents.", "example": 21000 }, "discountAmount": { "type": "number", "description": "Discount applied to the original amount, in cents.", "example": 2000 }, "feeAmount": { "type": "number", "description": "Fees added to the fare, in cents.", "example": 1500 }, "amount": { "type": "number", "description": "Total charged per passenger: `originalAmount - discountAmount + feeAmount`, in cents (`20500` is R$ 205,00).", "example": 20500 }, "currency": { "type": "string", "description": "Currency of the amounts (ISO 4217).", "example": "BRL" }, "isLowFare": { "type": "boolean", "description": "Whether the fare is a low-fare seat.", "example": false }, "cancellationPolicies": { "type": "object", "properties": { "refundable": { "type": "boolean", "description": "Whether the fare allows any refund at all.", "example": true }, "immediateFine": { "type": "boolean", "description": "Whether a fine is charged for cancelling right after booking.", "example": false }, "penalties": { "type": "array", "items": { "type": "object", "properties": { "from": { "type": "string", "description": "Date (`YYYY-MM-DD`) from which this tier applies.", "example": "2026-10-30" }, "currency": { "type": "string", "description": "Currency of the penalty (ISO 4217).", "example": "BRL" }, "fineAmount": { "type": "number", "description": "Penalty charged when cancelling or changing from `from` onward, in cents.", "example": 15000 } }, "required": [ "from", "currency", "fineAmount" ], "description": "One tier of a cancellation or change penalty schedule." }, "description": "Penalty schedule, in effect from each tier's date. Empty or omitted when no scheduled penalty applies." } }, "required": [ "refundable", "immediateFine" ], "description": "Cancellation rules of the fare. Only in the item detail, not in the search results." } }, "required": [ "originalAmount", "discountAmount", "feeAmount", "amount", "currency" ], "description": "Fare per passenger." }, "boardingPassType": { "type": "string", "enum": [ "RETRIEVE_AT_BOX_OFFICE", "ELECTRONIC" ], "description": "How the boarding pass is delivered: `ELECTRONIC` or `RETRIEVE_AT_BOX_OFFICE`.", "example": "ELECTRONIC" }, "serviceClass": { "type": "string", "enum": [ "SLEEPER_BED", "BED", "SEMI_BED", "EXECUTIVE", "CONVENTIONAL", "UNDEFINED" ], "description": "`SLEEPER_BED`, `BED`, `SEMI_BED`, `EXECUTIVE`, `CONVENTIONAL` or `UNDEFINED`.", "example": "EXECUTIVE" }, "waitingTime": { "type": "string", "description": "Wait between connecting legs, as an ISO 8601 duration. Empty for a direct trip.", "example": "" }, "duration": { "type": "string", "description": "Duration of the trip, as an ISO 8601 duration.", "example": "PT6H45M" }, "amenities": { "type": "array", "items": { "type": "string", "example": "AIR_CONDITIONING" }, "description": "Amenities of the bus, as codes: `AIR_CONDITIONING`, `BATHROOM`, `LEG_SUPPORT`, `SEAT_RECLINE`, `BETWEEN_SEATS`, `BUS_PHOTO`, `WIFI`, `POWER_OUTLETS`, `MINERAL_WATER`, `DOUBLE_DECK` or `COMFORT_KIT`.\n\n---\n\nExample: `[\"AIR_CONDITIONING\",\"WIFI\"]`" }, "segmentsCount": { "type": "number", "description": "Number of segments the trip is made of: 1 for a direct trip, more with connections.", "example": 1 }, "createdAt": { "type": "string", "description": "When the item was created.", "example": "2026-10-19T15:00:21.000Z", "format": "date-time" } }, "required": [ "id", "searchId", "type", "routeDirection", "origin", "destination", "departureDate", "arrivalDate", "company", "availableSeats", "totalSeats", "lowFareAvailableSeats", "fare", "boardingPassType", "serviceClass", "waitingTime", "duration", "amenities", "segmentsCount", "createdAt" ], "description": "A bus trip in the search results." }, "description": "The bus trips of this page, filtered and sorted by the query parameters. Present only once the search is `COMPLETED`." } }, "required": [ "createdAt", "facets", "id", "searchParams", "status", "ttl", "type", "warning" ], "description": "A bus search with, once it is `COMPLETED`, one page of its trips." } } } }, "404": { "description": "`SEARCH_NOT_FOUND` — The search doesn't exist, has expired, was created by another organization or is not a bus search.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "SEARCH_NOT_FOUND" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "TRAVEL" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b", "code": "SEARCH_NOT_FOUND", "origin": "TRAVEL", "message": "Search not found" } } } }, "422": { "description": "`BAD_REQUEST` — A path parameter is not a valid ID or a query parameter is invalid; `fields` lists each one.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "BAD_REQUEST" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "TRAVEL" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." }, "fields": { "type": "array", "description": "One entry per invalid request field (validation errors only).", "items": { "type": "object", "properties": { "field": { "type": "string", "description": "Path of the invalid field, e.g. `label` or `values[0].value`.", "example": "label" }, "message": { "type": "string", "description": "Why the field was rejected.", "example": "label is required" }, "code": { "type": "string", "description": "`_` — e.g. `LABEL_REQUIRED`, `TYPE_ONE_OF`, `VALUES_VALUE_TYPE_ERROR`.", "example": "LABEL_REQUIRED" }, "values": { "type": "array", "items": { "type": "string" }, "description": "The accepted values, when the field is an enumeration." } }, "required": [ "field", "message", "code" ] } } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "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": "order", "message": "Invalid option: expected one of \"ASC\"|\"DESC\"", "code": "ORDER_ONE_OF" } ] } } } }, "503": { "description": "`PROVIDER_UNAVAILABLE` — The travel provider could not be reached. Retry later.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "PROVIDER_UNAVAILABLE" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "TRAVEL" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b", "code": "PROVIDER_UNAVAILABLE", "origin": "TRAVEL", "message": "Travel provider temporarily unavailable, please retry." } } } } }, "x-p3-confidence": { "response": "generated:typed", "parameters": "generated:typed" } } }, "/realms/{realmId}/organizations/{organizationId}/bus/searches/{searchId}/items/{itemId}": { "get": { "operationId": "getRealmsByRealmIdOrganizationsByOrganizationIdBusSearchesBySearchIdItemsByItemId", "summary": "Get a bus search item", "tags": [ "Bus search" ], "x-p3-sidebar-order": 5, "description": "Returns the full detail of one bus trip of a bus search: the trip and its legs, with seat maps and fares.", "x-mint": { "content": "Open a trip of the search results to see what the list only summarizes: its `segments` — the legs of the trip — each with its seat map and fare. To book it, create a trip with the item's `id` as `searchItemId` and, for each leg, its `id` as `segmentId` with a bookable seat's `seatNumber`. Amounts are integers in cents: `98700` is R$ 987,00. The item lives as long as its search (see `ttl`). An error the travel provider reports about the request is returned with its own status, `code` and `message`." }, "parameters": [ { "name": "realmId", "in": "path", "required": true, "description": "ID of your realm.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b" }, { "name": "organizationId", "in": "path", "required": true, "description": "ID of your organization.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410" }, { "name": "searchId", "in": "path", "required": true, "description": "ID of the search, as returned when it was created.", "schema": { "type": "string", "pattern": "^srch_[0-9A-Za-z]{21}$" }, "example": "srch_V1StGXR8Z5jdHi6BmyT2k" }, { "name": "itemId", "in": "path", "required": true, "description": "ID of the item to load, as listed in the `items` of the search results.", "schema": { "type": "string", "pattern": "^srch_item_[0-9A-Za-z]{21}$" }, "example": "srch_item_V1StGXR8Z5jdHi6BmyT2k" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the item. Use it to load the item (seat maps and per-segment fares); send it as `searchItemId` when you create a trip.", "example": "srch_item_Lc7Ve3PsKd9Ny2QtXw5Mb" }, "searchId": { "type": "string", "description": "ID of the search the item belongs to.", "example": "srch_Fg4Ju9SaPe2Wx6TnCi5Oz" }, "type": { "type": "string", "enum": [ "DIRECT", "CONNECTION", "ONE_STOP" ], "description": "`DIRECT`, `CONNECTION` or `ONE_STOP`.", "example": "DIRECT" }, "routeDirection": { "type": "string", "enum": [ "DEPARTURE", "RETURN" ], "description": "Whether the trip is an outbound (`DEPARTURE`) or a return (`RETURN`) one.", "example": "DEPARTURE" }, "origin": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the station.", "example": "bus_sta_Ts5Gm8XqVb2Hw7NcKe1Ld" }, "slug": { "type": "string", "description": "Readable unique identifier of the station.", "example": "terminal-rodoviario-tiete" }, "locality": { "type": "string", "description": "City.", "example": "São Paulo" }, "administrativeArea": { "type": "string", "description": "State code.", "example": "SP" }, "name": { "type": "string", "nullable": true, "description": "Official name of the station. `null` when not informed.", "example": "Terminal Rodoviário Tietê" }, "shortAddress": { "type": "string", "nullable": true, "description": "The address in a single line. `null` when unknown.", "example": "Av. Cruzeiro do Sul, 1800, São Paulo, SP" }, "phoneNumbers": { "type": "array", "items": { "type": "string", "example": "+551122222222" }, "description": "Contact phone numbers. Empty when none is registered.\n\n---\n\nExample: `[\"+551122222222\"]`" }, "coordinates": { "description": "Position of the station. `null` when unknown.", "type": "object", "properties": { "lat": { "type": "number", "description": "Latitude, in decimal degrees.", "example": -23.4356 }, "lng": { "type": "number", "description": "Longitude, in decimal degrees.", "example": -46.4731 } }, "required": [ "lat", "lng" ], "nullable": true } }, "required": [ "id", "slug", "locality", "administrativeArea", "name", "shortAddress", "phoneNumbers", "coordinates" ], "description": "Origin station." }, "destination": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the station.", "example": "bus_sta_Ts5Gm8XqVb2Hw7NcKe1Ld" }, "slug": { "type": "string", "description": "Readable unique identifier of the station.", "example": "terminal-rodoviario-tiete" }, "locality": { "type": "string", "description": "City.", "example": "São Paulo" }, "administrativeArea": { "type": "string", "description": "State code.", "example": "SP" }, "name": { "type": "string", "nullable": true, "description": "Official name of the station. `null` when not informed.", "example": "Terminal Rodoviário Tietê" }, "shortAddress": { "type": "string", "nullable": true, "description": "The address in a single line. `null` when unknown.", "example": "Av. Cruzeiro do Sul, 1800, São Paulo, SP" }, "phoneNumbers": { "type": "array", "items": { "type": "string", "example": "+551122222222" }, "description": "Contact phone numbers. Empty when none is registered.\n\n---\n\nExample: `[\"+551122222222\"]`" }, "coordinates": { "description": "Position of the station. `null` when unknown.", "type": "object", "properties": { "lat": { "type": "number", "description": "Latitude, in decimal degrees.", "example": -23.4356 }, "lng": { "type": "number", "description": "Longitude, in decimal degrees.", "example": -46.4731 } }, "required": [ "lat", "lng" ], "nullable": true } }, "required": [ "id", "slug", "locality", "administrativeArea", "name", "shortAddress", "phoneNumbers", "coordinates" ], "description": "Destination station." }, "departureDate": { "type": "string", "description": "Departure, in the local time of the origin station (`YYYY-MM-DDTHH:mm:ss`, no time-zone offset).", "example": "2026-11-02T22:30:00" }, "arrivalDate": { "type": "string", "description": "Arrival, in the local time of the destination station (`YYYY-MM-DDTHH:mm:ss`, no time-zone offset).", "example": "2026-11-03T05:15:00" }, "company": { "type": "object", "properties": { "name": { "type": "string", "description": "Commercial name.", "example": "Viação Aurora" }, "logo": { "type": "string", "nullable": true, "description": "URL of the company's logo. `null` when unknown.", "example": "https://example.com/logos/aurora-bus.svg" }, "id": { "type": "string", "nullable": true, "description": "ID of the company. `null` when not informed.", "example": "bus_co_Nx3Rp8YtKd5Wc1LqHe7Va" } }, "required": [ "name", "logo", "id" ], "description": "Company that runs the trip." }, "availableSeats": { "type": "number", "description": "Seats available to book.", "example": 18 }, "totalSeats": { "type": "number", "nullable": true, "description": "Seats on the bus. `null` when not informed.", "example": 42 }, "lowFareAvailableSeats": { "type": "number", "nullable": true, "description": "Low-fare seats still available. `null` when not informed.", "example": 4 }, "fare": { "type": "object", "properties": { "originalAmount": { "type": "number", "description": "Price before discounts and fees, in cents.", "example": 21000 }, "discountAmount": { "type": "number", "description": "Discount applied to the original amount, in cents.", "example": 2000 }, "feeAmount": { "type": "number", "description": "Fees added to the fare, in cents.", "example": 1500 }, "amount": { "type": "number", "description": "Total charged per passenger: `originalAmount - discountAmount + feeAmount`, in cents (`20500` is R$ 205,00).", "example": 20500 }, "currency": { "type": "string", "description": "Currency of the amounts (ISO 4217).", "example": "BRL" }, "isLowFare": { "type": "boolean", "description": "Whether the fare is a low-fare seat.", "example": false }, "cancellationPolicies": { "type": "object", "properties": { "refundable": { "type": "boolean", "description": "Whether the fare allows any refund at all.", "example": true }, "immediateFine": { "type": "boolean", "description": "Whether a fine is charged for cancelling right after booking.", "example": false }, "penalties": { "type": "array", "items": { "type": "object", "properties": { "from": { "type": "string", "description": "Date (`YYYY-MM-DD`) from which this tier applies.", "example": "2026-10-30" }, "currency": { "type": "string", "description": "Currency of the penalty (ISO 4217).", "example": "BRL" }, "fineAmount": { "type": "number", "description": "Penalty charged when cancelling or changing from `from` onward, in cents.", "example": 15000 } }, "required": [ "from", "currency", "fineAmount" ], "description": "One tier of a cancellation or change penalty schedule." }, "description": "Penalty schedule, in effect from each tier's date. Empty or omitted when no scheduled penalty applies." } }, "required": [ "refundable", "immediateFine" ], "description": "Cancellation rules of the fare. Only in the item detail, not in the search results." } }, "required": [ "originalAmount", "discountAmount", "feeAmount", "amount", "currency" ], "description": "Fare per passenger." }, "boardingPassType": { "type": "string", "enum": [ "RETRIEVE_AT_BOX_OFFICE", "ELECTRONIC" ], "description": "How the boarding pass is delivered: `ELECTRONIC` or `RETRIEVE_AT_BOX_OFFICE`.", "example": "ELECTRONIC" }, "serviceClass": { "type": "string", "enum": [ "SLEEPER_BED", "BED", "SEMI_BED", "EXECUTIVE", "CONVENTIONAL", "UNDEFINED" ], "description": "`SLEEPER_BED`, `BED`, `SEMI_BED`, `EXECUTIVE`, `CONVENTIONAL` or `UNDEFINED`.", "example": "EXECUTIVE" }, "waitingTime": { "type": "string", "description": "Wait between connecting legs, as an ISO 8601 duration. Empty for a direct trip.", "example": "" }, "duration": { "type": "string", "description": "Duration of the trip, as an ISO 8601 duration.", "example": "PT6H45M" }, "amenities": { "type": "array", "items": { "type": "string", "example": "AIR_CONDITIONING" }, "description": "Amenities of the bus, as codes: `AIR_CONDITIONING`, `BATHROOM`, `LEG_SUPPORT`, `SEAT_RECLINE`, `BETWEEN_SEATS`, `BUS_PHOTO`, `WIFI`, `POWER_OUTLETS`, `MINERAL_WATER`, `DOUBLE_DECK` or `COMFORT_KIT`.\n\n---\n\nExample: `[\"AIR_CONDITIONING\",\"WIFI\"]`" }, "segmentsCount": { "type": "number", "description": "Number of segments the trip is made of: 1 for a direct trip, more with connections.", "example": 1 }, "createdAt": { "type": "string", "description": "When the item was created.", "example": "2026-10-19T15:00:21.000Z", "format": "date-time" }, "segments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the segment. Send it as `segmentId` when you create a trip.", "example": "seg_Ye6Kt2WnBd9Pq4LsRc1Xv" }, "type": { "type": "string", "enum": [ "DIRECT", "CONNECTION", "ONE_STOP" ], "description": "`DIRECT`, `CONNECTION` or `ONE_STOP`.", "example": "DIRECT" }, "fare": { "type": "object", "properties": { "originalAmount": { "type": "number", "description": "Price before discounts and fees, in cents.", "example": 21000 }, "discountAmount": { "type": "number", "description": "Discount applied to the original amount, in cents.", "example": 2000 }, "feeAmount": { "type": "number", "description": "Fees added to the fare, in cents.", "example": 1500 }, "amount": { "type": "number", "description": "Total charged per passenger: `originalAmount - discountAmount + feeAmount`, in cents (`20500` is R$ 205,00).", "example": 20500 }, "currency": { "type": "string", "description": "Currency of the amounts (ISO 4217).", "example": "BRL" }, "isLowFare": { "type": "boolean", "description": "Whether the fare is a low-fare seat.", "example": false }, "cancellationPolicies": { "type": "object", "properties": { "refundable": { "type": "boolean", "description": "Whether the fare allows any refund at all.", "example": true }, "immediateFine": { "type": "boolean", "description": "Whether a fine is charged for cancelling right after booking.", "example": false }, "penalties": { "type": "array", "items": { "type": "object", "properties": { "from": { "type": "string", "description": "Date (`YYYY-MM-DD`) from which this tier applies.", "example": "2026-10-30" }, "currency": { "type": "string", "description": "Currency of the penalty (ISO 4217).", "example": "BRL" }, "fineAmount": { "type": "number", "description": "Penalty charged when cancelling or changing from `from` onward, in cents.", "example": 15000 } }, "required": [ "from", "currency", "fineAmount" ], "description": "One tier of a cancellation or change penalty schedule." }, "description": "Penalty schedule, in effect from each tier's date. Empty or omitted when no scheduled penalty applies." } }, "required": [ "refundable", "immediateFine" ], "description": "Cancellation rules of the fare. Only in the item detail, not in the search results." } }, "required": [ "originalAmount", "discountAmount", "feeAmount", "amount", "currency" ], "description": "Fare of the segment, per passenger." }, "origin": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the station.", "example": "bus_sta_Ts5Gm8XqVb2Hw7NcKe1Ld" }, "slug": { "type": "string", "description": "Readable unique identifier of the station.", "example": "terminal-rodoviario-tiete" }, "locality": { "type": "string", "description": "City.", "example": "São Paulo" }, "administrativeArea": { "type": "string", "description": "State code.", "example": "SP" }, "name": { "type": "string", "nullable": true, "description": "Official name of the station. `null` when not informed.", "example": "Terminal Rodoviário Tietê" }, "shortAddress": { "type": "string", "nullable": true, "description": "The address in a single line. `null` when unknown.", "example": "Av. Cruzeiro do Sul, 1800, São Paulo, SP" }, "phoneNumbers": { "type": "array", "items": { "type": "string", "example": "+551122222222" }, "description": "Contact phone numbers. Empty when none is registered.\n\n---\n\nExample: `[\"+551122222222\"]`" }, "coordinates": { "description": "Position of the station. `null` when unknown.", "type": "object", "properties": { "lat": { "type": "number", "description": "Latitude, in decimal degrees.", "example": -23.4356 }, "lng": { "type": "number", "description": "Longitude, in decimal degrees.", "example": -46.4731 } }, "required": [ "lat", "lng" ], "nullable": true } }, "required": [ "id", "slug", "locality", "administrativeArea", "name", "shortAddress", "phoneNumbers", "coordinates" ], "description": "Boarding station." }, "destination": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the station.", "example": "bus_sta_Ts5Gm8XqVb2Hw7NcKe1Ld" }, "slug": { "type": "string", "description": "Readable unique identifier of the station.", "example": "terminal-rodoviario-tiete" }, "locality": { "type": "string", "description": "City.", "example": "São Paulo" }, "administrativeArea": { "type": "string", "description": "State code.", "example": "SP" }, "name": { "type": "string", "nullable": true, "description": "Official name of the station. `null` when not informed.", "example": "Terminal Rodoviário Tietê" }, "shortAddress": { "type": "string", "nullable": true, "description": "The address in a single line. `null` when unknown.", "example": "Av. Cruzeiro do Sul, 1800, São Paulo, SP" }, "phoneNumbers": { "type": "array", "items": { "type": "string", "example": "+551122222222" }, "description": "Contact phone numbers. Empty when none is registered.\n\n---\n\nExample: `[\"+551122222222\"]`" }, "coordinates": { "description": "Position of the station. `null` when unknown.", "type": "object", "properties": { "lat": { "type": "number", "description": "Latitude, in decimal degrees.", "example": -23.4356 }, "lng": { "type": "number", "description": "Longitude, in decimal degrees.", "example": -46.4731 } }, "required": [ "lat", "lng" ], "nullable": true } }, "required": [ "id", "slug", "locality", "administrativeArea", "name", "shortAddress", "phoneNumbers", "coordinates" ], "description": "Drop-off station." }, "departureDate": { "type": "string", "description": "Departure, in the local time of the boarding station (`YYYY-MM-DDTHH:mm:ss`, no time-zone offset).", "example": "2026-11-02T22:30:00" }, "arrivalDate": { "type": "string", "description": "Arrival, in the local time of the drop-off station (`YYYY-MM-DDTHH:mm:ss`, no time-zone offset).", "example": "2026-11-03T05:15:00" }, "company": { "type": "object", "properties": { "name": { "type": "string", "description": "Commercial name.", "example": "Viação Aurora" }, "logo": { "type": "string", "nullable": true, "description": "URL of the company's logo. `null` when unknown.", "example": "https://example.com/logos/aurora-bus.svg" }, "id": { "type": "string", "nullable": true, "description": "ID of the company. `null` when not informed.", "example": "bus_co_Nx3Rp8YtKd5Wc1LqHe7Va" } }, "required": [ "name", "logo", "id" ], "description": "Company that runs the segment." }, "availableSeats": { "type": "number", "description": "Seats available to book on the segment.", "example": 18 }, "lowFareAvailableSeats": { "type": "number", "description": "Low-fare seats still available on the segment.", "example": 4 }, "duration": { "type": "string", "description": "Duration of the segment, as an ISO 8601 duration.", "example": "PT6H45M" }, "serviceClass": { "type": "string", "enum": [ "SLEEPER_BED", "BED", "SEMI_BED", "EXECUTIVE", "CONVENTIONAL", "UNDEFINED" ], "description": "`SLEEPER_BED`, `BED`, `SEMI_BED`, `EXECUTIVE`, `CONVENTIONAL` or `UNDEFINED`.", "example": "EXECUTIVE" }, "seats": { "type": "array", "items": { "type": "object", "properties": { "seatNumber": { "type": "number", "description": "Seat number, as printed on the boarding pass. Send it as `seatNumber` when you create a trip.", "example": 12 }, "position": { "type": "object", "properties": { "x": { "type": "number", "nullable": true, "description": "Horizontal position. `null` when the layout is not available.", "example": 2 }, "y": { "type": "number", "nullable": true, "description": "Vertical position. `null` when the layout is not available.", "example": 5 }, "z": { "type": "number", "nullable": true, "description": "Deck: `0` for a single-deck bus or the lower deck, `1` for the upper deck. `null` when the layout is not available.", "example": 0 } }, "required": [ "x", "y", "z" ], "description": "Where the seat is." }, "isBookable": { "type": "boolean", "description": "Whether the seat can be booked now.", "example": true } }, "required": [ "seatNumber", "position", "isBookable" ], "description": "A seat of a bus segment." }, "description": "The seat map of the segment." } }, "required": [ "id", "type", "fare", "origin", "destination", "departureDate", "arrivalDate", "company", "availableSeats", "lowFareAvailableSeats", "duration", "serviceClass", "seats" ], "description": "One leg of a bus trip, with its seat map and fare." }, "description": "The legs of the trip, each with its seat map and fare — send each leg's `id` as `segmentId`, with a bookable seat's `seatNumber`, when you create a trip." } }, "required": [ "amenities", "arrivalDate", "availableSeats", "boardingPassType", "company", "createdAt", "departureDate", "destination", "duration", "fare", "id", "lowFareAvailableSeats", "origin", "routeDirection", "searchId", "segments", "segmentsCount", "serviceClass", "totalSeats", "type", "waitingTime" ], "description": "The detail of one bus trip of a bus search: the trip and its legs, with seat maps and fares." } } } }, "404": { "description": "`SEARCH_NOT_FOUND` — The search doesn't exist, has expired, was created by another organization or is not a bus search.\n\n`BUS_ROUTE_SEARCH_ITEM_NOT_FOUND` — The bus search has no item with this ID, or it expired.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "SEARCH_NOT_FOUND", "BUS_ROUTE_SEARCH_ITEM_NOT_FOUND" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "TRAVEL" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b", "code": "SEARCH_NOT_FOUND", "origin": "TRAVEL", "message": "Search not found" } } } }, "422": { "description": "`BAD_REQUEST` — A path parameter is not a valid ID; `fields` lists each one.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "BAD_REQUEST" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "TRAVEL" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." }, "fields": { "type": "array", "description": "One entry per invalid request field (validation errors only).", "items": { "type": "object", "properties": { "field": { "type": "string", "description": "Path of the invalid field, e.g. `label` or `values[0].value`.", "example": "label" }, "message": { "type": "string", "description": "Why the field was rejected.", "example": "label is required" }, "code": { "type": "string", "description": "`_` — e.g. `LABEL_REQUIRED`, `TYPE_ONE_OF`, `VALUES_VALUE_TYPE_ERROR`.", "example": "LABEL_REQUIRED" }, "values": { "type": "array", "items": { "type": "string" }, "description": "The accepted values, when the field is an enumeration." } }, "required": [ "field", "message", "code" ] } } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "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": "organizationId", "message": "Invalid UUID", "code": "ORGANIZATIONID_UUID" } ] } } } }, "503": { "description": "`PROVIDER_UNAVAILABLE` — The travel provider could not be reached. Retry later.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "PROVIDER_UNAVAILABLE" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "TRAVEL" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b", "code": "PROVIDER_UNAVAILABLE", "origin": "TRAVEL", "message": "Travel provider temporarily unavailable, please retry." } } } } }, "x-p3-confidence": { "response": "generated:typed" } } }, "/realms/{realmId}/organizations/{organizationId}/vehicle/locations": { "get": { "operationId": "getRealmsByRealmIdOrganizationsByOrganizationIdVehicleLocations", "summary": "Search vehicle pick-up places", "tags": [ "Vehicle search" ], "x-p3-sidebar-order": 1, "description": "Searches pick-up and drop-off places for a vehicle search.", "x-mint": { "content": "Use it to fill the pick-up and drop-off pickers before you create a vehicle search, then send the place's `id` — or its `slug` — as `pickUpLocation` or `dropOffLocation`. Matches come most relevant first, and an empty `results` means nothing matched. An error the travel provider reports about the request is returned with its own status, `code` and `message`." }, "parameters": [ { "name": "realmId", "in": "path", "required": true, "description": "ID of your realm.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b" }, { "name": "organizationId", "in": "path", "required": true, "description": "ID of your organization.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410" }, { "name": "query", "in": "query", "required": true, "description": "Text to search pick-up and drop-off places for: part of a city, airport or place name, a slug or an address, case-insensitive.", "schema": { "type": "string", "minLength": 1 }, "example": "Sao Paulo" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the place. Use it, or its `slug`, as `destinationId` of a hotel search or as a pick-up or drop-off place of a vehicle search.", "example": "lctn_Mr4Bn7YcQd1Ks9TeVw2Xh" }, "slug": { "type": "string", "description": "Readable unique identifier of the place.", "example": "sao-paulo-sp" }, "name": { "type": "string", "description": "Display name.", "example": "São Paulo" }, "region": { "type": "string", "description": "Region the place belongs to.", "example": "Brasil" }, "address": { "type": "object", "properties": { "shortAddress": { "type": "string", "nullable": true, "description": "The address in a single line. `null` when unknown.", "example": "Guarulhos, SP, Brazil" }, "adressLines": { "type": "array", "items": { "type": "string", "example": "Rod. Hélio Smidt, s/n" }, "description": "The address in postal lines. Empty when unknown. The field name is spelled `adressLines`.\n\n---\n\nExample: `[\"Rod. Hélio Smidt, s/n\"]`" }, "locality": { "type": "string", "nullable": true, "description": "City. `null` when unknown.", "example": "Guarulhos" }, "administrativeArea": { "type": "string", "nullable": true, "description": "State or province code. `null` when unknown.", "example": "SP" }, "administrativeAreaName": { "type": "string", "nullable": true, "description": "State or province name. `null` when unknown.", "example": "São Paulo" }, "postalCode": { "type": "string", "nullable": true, "description": "Postal code. `null` when unknown.", "example": "07190-100" }, "country": { "type": "string", "description": "Country (ISO 3166-1 alpha-2).", "example": "BR" }, "timezone": { "type": "string", "description": "IANA time zone of the place, or `Unknown`.", "example": "America/Sao_Paulo" }, "coordinates": { "description": "Position of the place. `null` when unknown.", "type": "object", "properties": { "lat": { "type": "number", "description": "Latitude, in decimal degrees.", "example": -23.4356 }, "lng": { "type": "number", "description": "Longitude, in decimal degrees.", "example": -46.4731 } }, "required": [ "lat", "lng" ], "nullable": true }, "localityId": { "type": "string", "nullable": true, "description": "ID of the locality the bus station belongs to. Bus stations only; `null` when the station is not grouped under a locality." } }, "required": [ "shortAddress", "adressLines", "locality", "administrativeArea", "administrativeAreaName", "postalCode", "country", "timezone", "coordinates" ], "description": "Address and position of the place." }, "type": { "type": "string", "enum": [ "AIRPORT", "LOCALITY", "LOCALITY_AND_SURROUNDINGS", "GENERIC_PLACE" ], "description": "What the place is: `AIRPORT`, `LOCALITY`, `LOCALITY_AND_SURROUNDINGS` or `GENERIC_PLACE`.", "example": "LOCALITY" } }, "required": [ "id", "slug", "name", "region", "address", "type" ], "description": "A destination or pick-up place (`hotel` and `vehicle` locations)." }, "description": "Matching places, most relevant first. Empty when nothing matches." } }, "required": [ "results" ], "description": "The pick-up and drop-off places matching a vehicle location search." } } } }, "422": { "description": "`BAD_REQUEST` — A path parameter is not a valid ID, or `query` is missing or blank; `fields` lists each one.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "BAD_REQUEST" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "TRAVEL" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." }, "fields": { "type": "array", "description": "One entry per invalid request field (validation errors only).", "items": { "type": "object", "properties": { "field": { "type": "string", "description": "Path of the invalid field, e.g. `label` or `values[0].value`.", "example": "label" }, "message": { "type": "string", "description": "Why the field was rejected.", "example": "label is required" }, "code": { "type": "string", "description": "`_` — e.g. `LABEL_REQUIRED`, `TYPE_ONE_OF`, `VALUES_VALUE_TYPE_ERROR`.", "example": "LABEL_REQUIRED" }, "values": { "type": "array", "items": { "type": "string" }, "description": "The accepted values, when the field is an enumeration." } }, "required": [ "field", "message", "code" ] } } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "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": "query", "message": "Invalid input: expected string, received undefined", "code": "QUERY_REQUIRED" } ] } } } }, "503": { "description": "`PROVIDER_UNAVAILABLE` — The travel provider could not be reached. Retry later.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "PROVIDER_UNAVAILABLE" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "TRAVEL" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b", "code": "PROVIDER_UNAVAILABLE", "origin": "TRAVEL", "message": "Travel provider temporarily unavailable, please retry." } } } } }, "x-p3-confidence": { "response": "generated:typed", "parameters": "generated:typed" } } }, "/realms/{realmId}/organizations/{organizationId}/vehicle/searches": { "post": { "operationId": "postRealmsByRealmIdOrganizationsByOrganizationIdVehicleSearches", "summary": "Create a vehicle search", "tags": [ "Vehicle search" ], "x-p3-sidebar-order": 2, "description": "Starts a search for car rentals, from a pick-up place and time to a drop-off place and time.", "x-mint": { "content": "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 vehicle search lasts 30 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.\n\nFind `pickUpLocation` and `dropOffLocation` with the locations endpoint. To book a result, open the item for its fare options, then create a trip with the item's `id` as `searchItemId` and the chosen fare option's `id` as `fareId`.\n\nAn error the travel provider reports about the request — an unknown place, say — is returned with its own status, `code` and `message`." }, "parameters": [ { "name": "realmId", "in": "path", "required": true, "description": "ID of your realm.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b" }, { "name": "organizationId", "in": "path", "required": true, "description": "ID of your organization.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "pickUpLocation": { "type": "string", "minLength": 1, "description": "Pick-up place: its `id` or its `slug` from the locations endpoint.", "example": "sao-paulo-sp" }, "dropOffLocation": { "type": "string", "minLength": 1, "description": "Drop-off place: its `id` or its `slug` from the locations endpoint.", "example": "sao-paulo-sp" }, "pickUpDate": { "type": "string", "minLength": 1, "description": "Pick-up date and time, local to the pick-up place (`YYYY-MM-DDTHH:mm:ss`, no time-zone offset). Today or later, and before `dropOffDate`.", "example": "2026-11-02T10:00:00" }, "dropOffDate": { "type": "string", "minLength": 1, "description": "Drop-off date and time, local to the drop-off place (`YYYY-MM-DDTHH:mm:ss`, no time-zone offset), after `pickUpDate`.", "example": "2026-11-05T10:00:00" } }, "required": [ "pickUpLocation", "dropOffLocation", "pickUpDate", "dropOffDate" ] } } } }, "responses": { "202": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the search. The same search parameters, within the time the search lasts, return the same ID.", "example": "srch_Hb7Yk1DrMv3Lq8UsAe0Xj" }, "searchParams": { "type": "object", "properties": { "pickUpLocation": { "type": "string", "description": "Pick-up place, as sent.", "example": "sao-paulo-sp" }, "dropOffLocation": { "type": "string", "description": "Drop-off place, as sent.", "example": "sao-paulo-sp" }, "pickUpDate": { "type": "string", "description": "Pick-up date and time, as sent.", "example": "2026-11-02T10:00:00" }, "dropOffDate": { "type": "string", "description": "Drop-off date and time, as sent.", "example": "2026-11-05T10:00:00" } }, "required": [ "pickUpLocation", "dropOffLocation", "pickUpDate", "dropOffDate" ], "description": "What the search was made for." }, "type": { "type": "string", "enum": [ "VEHICLE" ], "description": "Always `VEHICLE`.", "example": "VEHICLE" }, "status": { "type": "string", "enum": [ "PROCESSING", "FAILED", "COMPLETED" ], "description": "`PROCESSING` right after creation. It becomes `COMPLETED` or `FAILED` on its own: poll the search.", "example": "PROCESSING" }, "warning": { "description": "How the search went across the suppliers. `null` while it is processing.", "type": "object", "properties": { "code": { "type": "string", "enum": [ "ALL_FAILED", "PARTIAL_SUCCESS", "ALL_SUCCESS" ], "description": "`ALL_SUCCESS`: every supplier answered. `PARTIAL_SUCCESS`: some suppliers failed, so the results may be incomplete. `ALL_FAILED`: no supplier answered.", "example": "ALL_SUCCESS" }, "message": { "type": "string", "description": "Human-readable explanation.", "example": "All suppliers answered." } }, "required": [ "code", "message" ], "nullable": true }, "ttl": { "type": "number", "description": "Seconds until the search expires.", "example": 1800 }, "facets": { "description": "Facets to build filters from (price ranges, categories, rental companies, with their counts). `null` until the search completes.", "type": "object", "additionalProperties": {}, "nullable": true }, "createdAt": { "type": "string", "description": "When the search was created.", "example": "2026-10-19T15:00:00.000Z", "format": "date-time" } }, "required": [ "id", "searchParams", "type", "status", "warning", "ttl", "facets", "createdAt" ], "description": "A search just created for vehicle rentals. Results come later: poll the search." } } } }, "422": { "description": "`BAD_REQUEST` — A path parameter is not a valid ID or the body failed validation; `fields` lists each offending field.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "BAD_REQUEST" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "TRAVEL" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." }, "fields": { "type": "array", "description": "One entry per invalid request field (validation errors only).", "items": { "type": "object", "properties": { "field": { "type": "string", "description": "Path of the invalid field, e.g. `label` or `values[0].value`.", "example": "label" }, "message": { "type": "string", "description": "Why the field was rejected.", "example": "label is required" }, "code": { "type": "string", "description": "`_` — e.g. `LABEL_REQUIRED`, `TYPE_ONE_OF`, `VALUES_VALUE_TYPE_ERROR`.", "example": "LABEL_REQUIRED" }, "values": { "type": "array", "items": { "type": "string" }, "description": "The accepted values, when the field is an enumeration." } }, "required": [ "field", "message", "code" ] } } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "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": "pickUpLocation", "message": "Invalid input: expected string, received undefined", "code": "PICKUPLOCATION_REQUIRED" } ] } } } }, "503": { "description": "`PROVIDER_UNAVAILABLE` — The travel provider could not be reached; no search was created. Retry later.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "PROVIDER_UNAVAILABLE" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "TRAVEL" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b", "code": "PROVIDER_UNAVAILABLE", "origin": "TRAVEL", "message": "Travel provider temporarily unavailable, please retry." } } } } }, "x-p3-confidence": { "response": "generated:typed", "request": "generated:typed" } } }, "/realms/{realmId}/organizations/{organizationId}/vehicle/searches/{searchId}": { "get": { "operationId": "getRealmsByRealmIdOrganizationsByOrganizationIdVehicleSearchesBySearchId", "summary": "Get a vehicle search and its results", "tags": [ "Vehicle search" ], "x-p3-sidebar-order": 3, "description": "Returns a vehicle search and, once it has finished, one page of its vehicles.", "x-mint": { "content": "Searches are asynchronous: while `status` is `PROCESSING` only the search itself comes back, so poll until it is `COMPLETED`, then read `items`. A `FAILED` search has no results. A vehicle search expires after its `ttl` (30 minutes) and then answers `404 SEARCH_NOT_FOUND`. Only the organization that created a search can read it.\n\nResults come in pages. Sort them with `order` and `orderBy`, narrow them with `minAmount`, `maxAmount`, `category` and `rentalCompany`, then walk the pages with `limit` and the `next` cursor each response returns (`null` on the last page). A filter that takes several values accepts them repeated or comma-separated (`?category=Compact&category=SUV` or `?category=Compact,SUV`). Amounts are integers in cents: `98700` is R$ 987,00.\n\nEach item is a summary with its cheapest fare. To book one, open it with the vehicle search item endpoint for everything a trip needs, and create the trip with the item's `id` as `searchItemId`. An error the travel provider reports about the request — a filter value it does not accept, say — is returned with its own status, `code` and `message`." }, "parameters": [ { "name": "realmId", "in": "path", "required": true, "description": "ID of your realm.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b" }, { "name": "organizationId", "in": "path", "required": true, "description": "ID of your organization.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410" }, { "name": "searchId", "in": "path", "required": true, "description": "ID of the vehicle search, as returned when it was created.", "schema": { "type": "string", "pattern": "^srch_[0-9A-Za-z]{21}$" }, "example": "srch_V1StGXR8Z5jdHi6BmyT2k" }, { "name": "order", "in": "query", "required": false, "description": "Sort direction applied to `orderBy`: `ASC` lists the cheapest results first, `DESC` the most expensive first.", "schema": { "type": "string", "enum": [ "ASC", "DESC" ] }, "example": "ASC" }, { "name": "orderBy", "in": "query", "required": false, "description": "Field to sort the results by. Currently only `amount` is supported.", "schema": { "type": "string", "minLength": 1 }, "example": "amount" }, { "name": "next", "in": "query", "required": false, "description": "Cursor returned as `next` by the previous page. Omit for the first page.", "schema": { "type": "string", "minLength": 1 }, "example": "eyJwIjoyfQ==" }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of items per page, from 1 to 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "example": 20 }, { "name": "minAmount", "in": "query", "required": false, "description": "Only results costing at least this amount, in the same unit as the `amount` of the results (cents).", "schema": { "type": "number", "minimum": 0 }, "example": 20000 }, { "name": "maxAmount", "in": "query", "required": false, "description": "Only results costing at most this amount, in the same unit as the `amount` of the results (cents).", "schema": { "type": "number", "minimum": 0 }, "example": 100000 }, { "name": "category", "in": "query", "required": false, "description": "Only vehicles of these categories, matched exactly and case-sensitive.\n\n---\n\nExample (comma-separated list): `?category=Compact,SUV`", "schema": { "type": "array", "items": { "type": "string" } }, "style": "form", "explode": false }, { "name": "rentalCompany", "in": "query", "required": false, "description": "Only vehicles of these rental companies, by name, matched exactly and case-sensitive.\n\n---\n\nExample (comma-separated list): `?rentalCompany=Aurora Rent,Via Carros`", "schema": { "type": "array", "items": { "type": "string" } }, "style": "form", "explode": false } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the search.", "example": "srch_V1StGXR8Z5jdHi6BmyT2k" }, "status": { "type": "string", "enum": [ "PROCESSING", "FAILED", "COMPLETED" ], "description": "`PROCESSING` while the suppliers answer, then `COMPLETED` or `FAILED`. Only `COMPLETED` carries `items`.", "example": "COMPLETED" }, "warning": { "description": "How the search went across the suppliers. `null` while it is processing.", "type": "object", "properties": { "code": { "type": "string", "enum": [ "ALL_FAILED", "PARTIAL_SUCCESS", "ALL_SUCCESS" ], "description": "`ALL_SUCCESS`: every supplier answered. `PARTIAL_SUCCESS`: some suppliers failed, so the results may be incomplete. `ALL_FAILED`: no supplier answered.", "example": "ALL_SUCCESS" }, "message": { "type": "string", "description": "Human-readable explanation.", "example": "All suppliers answered." } }, "required": [ "code", "message" ], "nullable": true }, "createdAt": { "type": "string", "description": "When the search was created.", "example": "2026-10-19T15:00:00.000Z", "format": "date-time" }, "next": { "type": "string", "nullable": true, "description": "Cursor for the next page. `null` on the last page. Present only once the search is `COMPLETED`.", "example": "eyJwIjoyfQ==" }, "totalCount": { "type": "number", "description": "Number of results that match the filters, across every page. Present only once the search is `COMPLETED`.", "example": 1 }, "searchParams": { "type": "object", "properties": { "pickUpLocation": { "type": "string", "description": "Pick-up place, as sent.", "example": "sao-paulo-sp" }, "dropOffLocation": { "type": "string", "description": "Drop-off place, as sent.", "example": "sao-paulo-sp" }, "pickUpDate": { "type": "string", "description": "Pick-up date and time, as sent.", "example": "2026-11-02T10:00:00" }, "dropOffDate": { "type": "string", "description": "Drop-off date and time, as sent.", "example": "2026-11-05T10:00:00" } }, "required": [ "pickUpLocation", "dropOffLocation", "pickUpDate", "dropOffDate" ], "description": "What the search was made for, as sent." }, "type": { "type": "string", "enum": [ "VEHICLE" ], "description": "Always `VEHICLE`.", "example": "VEHICLE" }, "ttl": { "type": "number", "description": "Seconds until the search expires (a vehicle search lasts 30 minutes).", "example": 1500 }, "facets": { "description": "Facets to build filters from (price ranges, categories, rental companies, with their counts). `null` until the search completes.", "type": "object", "additionalProperties": {}, "nullable": true }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the item. Use it to load the item (every fare option); send it as `searchItemId` when you create a trip.", "example": "srch_item_Rn2Xd8GuYc4Wv6ZkJe1Ta" }, "searchId": { "type": "string", "description": "ID of the search the item belongs to.", "example": "srch_Hb7Yk1DrMv3Lq8UsAe0Xj" }, "groupName": { "type": "string", "description": "Name of the group of vehicles that fulfil the same booking class.", "example": "Economy" }, "class": { "type": "string", "description": "Class of the vehicle.", "example": "Economy" }, "name": { "type": "string", "description": "Commercial name of the vehicle.", "example": "Fiat Mobi" }, "sipp": { "type": "string", "description": "SIPP (ACRISS) code of the vehicle.", "example": "EDMR" }, "pickUpLocation": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the station.", "example": "Aurora Rent - Aeroporto de Guarulhos" }, "phoneNumbers": { "type": "array", "items": { "type": "string", "example": "+551133334444" }, "description": "Contact phone numbers. Empty when none is registered.\n\n---\n\nExample: `[\"+551133334444\"]`" }, "address": { "type": "object", "properties": { "shortAddress": { "type": "string", "nullable": true, "description": "The address in a single line. `null` when unknown.", "example": "Guarulhos, SP, Brazil" }, "adressLines": { "type": "array", "items": { "type": "string", "example": "Rod. Hélio Smidt, s/n" }, "description": "The address in postal lines. Empty when unknown. The field name is spelled `adressLines`.\n\n---\n\nExample: `[\"Rod. Hélio Smidt, s/n\"]`" }, "locality": { "type": "string", "nullable": true, "description": "City. `null` when unknown.", "example": "Guarulhos" }, "administrativeArea": { "type": "string", "nullable": true, "description": "State or province code. `null` when unknown.", "example": "SP" }, "administrativeAreaName": { "type": "string", "nullable": true, "description": "State or province name. `null` when unknown.", "example": "São Paulo" }, "postalCode": { "type": "string", "nullable": true, "description": "Postal code. `null` when unknown.", "example": "07190-100" }, "country": { "type": "string", "description": "Country (ISO 3166-1 alpha-2).", "example": "BR" }, "timezone": { "type": "string", "description": "IANA time zone of the place, or `Unknown`.", "example": "America/Sao_Paulo" }, "coordinates": { "description": "Position of the place. `null` when unknown.", "type": "object", "properties": { "lat": { "type": "number", "description": "Latitude, in decimal degrees.", "example": -23.4356 }, "lng": { "type": "number", "description": "Longitude, in decimal degrees.", "example": -46.4731 } }, "required": [ "lat", "lng" ], "nullable": true }, "localityId": { "type": "string", "nullable": true, "description": "ID of the locality the bus station belongs to. Bus stations only; `null` when the station is not grouped under a locality." } }, "required": [ "shortAddress", "adressLines", "locality", "administrativeArea", "administrativeAreaName", "postalCode", "country", "timezone", "coordinates" ], "description": "Address and position of the station." } }, "required": [ "name", "phoneNumbers", "address" ], "description": "Where the vehicle is picked up." }, "dropOffLocation": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the station.", "example": "Aurora Rent - Aeroporto de Guarulhos" }, "phoneNumbers": { "type": "array", "items": { "type": "string", "example": "+551133334444" }, "description": "Contact phone numbers. Empty when none is registered.\n\n---\n\nExample: `[\"+551133334444\"]`" }, "address": { "type": "object", "properties": { "shortAddress": { "type": "string", "nullable": true, "description": "The address in a single line. `null` when unknown.", "example": "Guarulhos, SP, Brazil" }, "adressLines": { "type": "array", "items": { "type": "string", "example": "Rod. Hélio Smidt, s/n" }, "description": "The address in postal lines. Empty when unknown. The field name is spelled `adressLines`.\n\n---\n\nExample: `[\"Rod. Hélio Smidt, s/n\"]`" }, "locality": { "type": "string", "nullable": true, "description": "City. `null` when unknown.", "example": "Guarulhos" }, "administrativeArea": { "type": "string", "nullable": true, "description": "State or province code. `null` when unknown.", "example": "SP" }, "administrativeAreaName": { "type": "string", "nullable": true, "description": "State or province name. `null` when unknown.", "example": "São Paulo" }, "postalCode": { "type": "string", "nullable": true, "description": "Postal code. `null` when unknown.", "example": "07190-100" }, "country": { "type": "string", "description": "Country (ISO 3166-1 alpha-2).", "example": "BR" }, "timezone": { "type": "string", "description": "IANA time zone of the place, or `Unknown`.", "example": "America/Sao_Paulo" }, "coordinates": { "description": "Position of the place. `null` when unknown.", "type": "object", "properties": { "lat": { "type": "number", "description": "Latitude, in decimal degrees.", "example": -23.4356 }, "lng": { "type": "number", "description": "Longitude, in decimal degrees.", "example": -46.4731 } }, "required": [ "lat", "lng" ], "nullable": true }, "localityId": { "type": "string", "nullable": true, "description": "ID of the locality the bus station belongs to. Bus stations only; `null` when the station is not grouped under a locality." } }, "required": [ "shortAddress", "adressLines", "locality", "administrativeArea", "administrativeAreaName", "postalCode", "country", "timezone", "coordinates" ], "description": "Address and position of the station." } }, "required": [ "name", "phoneNumbers", "address" ], "description": "Where the vehicle is dropped off." }, "pickUpDate": { "type": "string", "description": "Pick-up, in the local time of the station (`YYYY-MM-DDTHH:mm:ss`, no time-zone offset).", "example": "2026-11-02T10:00:00" }, "dropOffDate": { "type": "string", "description": "Drop-off, in the local time of the station (`YYYY-MM-DDTHH:mm:ss`, no time-zone offset).", "example": "2026-11-05T10:00:00" }, "model": { "type": "string", "description": "Model of the vehicle.", "example": "Mobi Like 1.0" }, "vehicleDetails": { "type": "object", "properties": { "hasAirConditioning": { "type": "boolean", "description": "Whether the vehicle has air conditioning.", "example": true }, "fuelType": { "type": "string", "enum": [ "ELECTRIC", "HYBRID", "FLEX", "DIESEL", "GASOLINE", "ETHANOL", "LPG", "HYDROGEN", "NOT_INFORMED" ], "description": "Fuel: `ELECTRIC`, `HYBRID`, `FLEX`, `DIESEL`, `GASOLINE`, `ETHANOL`, `LPG`, `HYDROGEN` or `NOT_INFORMED`.", "example": "FLEX" }, "category": { "type": "string", "description": "Category label.", "example": "Compact" }, "passengerQtd": { "type": "number", "description": "Passengers the vehicle seats.", "example": 5 }, "luggageQtd": { "type": "number", "description": "Pieces of luggage the vehicle holds.", "example": 2 }, "doorsQtd": { "type": "number", "description": "Number of doors.", "example": 4 }, "transmissionType": { "type": "string", "enum": [ "AUTOMATIC", "MANUAL", "NOT_INFORMED" ], "description": "`AUTOMATIC`, `MANUAL` or `NOT_INFORMED`.", "example": "MANUAL" }, "includedMileage": { "type": "string", "description": "Mileage included in the rental.", "example": "UNLIMITED" } }, "required": [ "hasAirConditioning", "fuelType", "category", "passengerQtd", "luggageQtd", "doorsQtd", "transmissionType", "includedMileage" ], "description": "Specifications of the vehicle." }, "rentalCompany": { "type": "object", "properties": { "code": { "type": "string", "description": "Code of the company.", "example": "AUR" }, "name": { "type": "string", "description": "Commercial name.", "example": "Aurora Rent" }, "logo": { "type": "string", "nullable": true, "description": "URL of the company's logo. `null` when unknown.", "example": "https://example.com/logos/aurora-rent.svg" } }, "required": [ "code", "name", "logo" ], "description": "Company that rents the vehicle." }, "mainImage": { "type": "object", "properties": { "uri": { "type": "string", "description": "URL of the image.", "example": "https://example.com/vehicles/compact.jpg" }, "blurHash": { "type": "string", "description": "BlurHash placeholder for previews. Omitted when unavailable.", "example": "LEHV6nWB2yk8pyo0adR*.7kCMdnj" }, "dominantColor": { "type": "string", "description": "Dominant color, as hex. Omitted when unavailable.", "example": "#c9d3dc" } }, "required": [ "uri" ], "description": "Main image of the vehicle." }, "cheapestFare": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the fare option. Send it as `fareId` when you create a trip with this item.", "example": "fare_Sv9Lc4TdHy1Qn6BwKe3Pr" }, "description": { "type": "string", "nullable": true, "description": "Name of the fare option. `null` when not available.", "example": "Basic protection" }, "fare": { "type": "object", "properties": { "currency": { "type": "string", "description": "Currency of the amounts (ISO 4217).", "example": "BRL" }, "originalAmount": { "type": "number", "description": "Price before discounts and fees, in cents.", "example": 48000 }, "discountAmount": { "type": "number", "description": "Discount applied to the original amount, in cents.", "example": 4800 }, "feeAmount": { "type": "number", "description": "Fees added to the rental, in cents.", "example": 1800 }, "amount": { "type": "number", "description": "Total charged for the rental: `originalAmount - discountAmount + feeAmount`, in cents (`45000` is R$ 450,00).", "example": 45000 }, "cancellationPolicies": { "type": "object", "properties": { "refundable": { "type": "boolean", "description": "Whether the fare allows any refund at all.", "example": true }, "immediateFine": { "type": "boolean", "description": "Whether a fine is charged for cancelling right after booking.", "example": false }, "penalties": { "type": "array", "items": { "type": "object", "properties": { "from": { "type": "string", "description": "Date (`YYYY-MM-DD`) from which this tier applies.", "example": "2026-10-30" }, "currency": { "type": "string", "description": "Currency of the penalty (ISO 4217).", "example": "BRL" }, "fineAmount": { "type": "number", "description": "Penalty charged when cancelling or changing from `from` onward, in cents.", "example": 15000 } }, "required": [ "from", "currency", "fineAmount" ], "description": "One tier of a cancellation or change penalty schedule." }, "description": "Penalty schedule, in effect from each tier's date. Empty or omitted when no scheduled penalty applies." } }, "required": [ "refundable", "immediateFine" ], "description": "Cancellation rules of the rate. Only in the item detail, not in the search results." }, "changePolicies": { "type": "object", "properties": { "canChange": { "type": "boolean", "description": "Whether the fare allows the booking to be changed.", "example": true }, "immediateFine": { "type": "boolean", "description": "Whether a fine is charged for changing right after booking.", "example": false }, "penalties": { "type": "array", "items": { "type": "object", "properties": { "from": { "type": "string", "description": "Date (`YYYY-MM-DD`) from which this tier applies.", "example": "2026-10-30" }, "currency": { "type": "string", "description": "Currency of the penalty (ISO 4217).", "example": "BRL" }, "fineAmount": { "type": "number", "description": "Penalty charged when cancelling or changing from `from` onward, in cents.", "example": 15000 } }, "required": [ "from", "currency", "fineAmount" ], "description": "One tier of a cancellation or change penalty schedule." }, "description": "Penalty schedule, in effect from each tier's date. Empty when none applies." } }, "required": [ "canChange", "immediateFine", "penalties" ], "description": "Change rules of the rate. Only in the item detail, not in the search results. Car rentals can't be changed today, so `canChange` is `false`." } }, "required": [ "currency", "originalAmount", "discountAmount", "feeAmount", "amount" ], "description": "Price of the fare option." } }, "required": [ "id", "description", "fare" ], "description": "The cheapest fare option. Absent when the vehicle has none." } }, "required": [ "id", "searchId", "groupName", "class", "name", "sipp", "pickUpLocation", "dropOffLocation", "pickUpDate", "dropOffDate", "model", "vehicleDetails", "rentalCompany", "mainImage" ], "description": "A vehicle in the search results, with its cheapest fare option. Load the item for every one." }, "description": "The vehicles of this page, filtered and sorted by the query parameters. Present only once the search is `COMPLETED`." } }, "required": [ "createdAt", "facets", "id", "searchParams", "status", "ttl", "type", "warning" ], "description": "A vehicle search with, once it is `COMPLETED`, one page of its vehicles." } } } }, "404": { "description": "`SEARCH_NOT_FOUND` — The search doesn't exist, has expired, was created by another organization or is not a vehicle search.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "SEARCH_NOT_FOUND" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "TRAVEL" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b", "code": "SEARCH_NOT_FOUND", "origin": "TRAVEL", "message": "Search not found" } } } }, "422": { "description": "`BAD_REQUEST` — A path parameter is not a valid ID or a query parameter is invalid; `fields` lists each one.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "BAD_REQUEST" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "TRAVEL" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." }, "fields": { "type": "array", "description": "One entry per invalid request field (validation errors only).", "items": { "type": "object", "properties": { "field": { "type": "string", "description": "Path of the invalid field, e.g. `label` or `values[0].value`.", "example": "label" }, "message": { "type": "string", "description": "Why the field was rejected.", "example": "label is required" }, "code": { "type": "string", "description": "`_` — e.g. `LABEL_REQUIRED`, `TYPE_ONE_OF`, `VALUES_VALUE_TYPE_ERROR`.", "example": "LABEL_REQUIRED" }, "values": { "type": "array", "items": { "type": "string" }, "description": "The accepted values, when the field is an enumeration." } }, "required": [ "field", "message", "code" ] } } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "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": "order", "message": "Invalid option: expected one of \"ASC\"|\"DESC\"", "code": "ORDER_ONE_OF" } ] } } } }, "503": { "description": "`PROVIDER_UNAVAILABLE` — The travel provider could not be reached. Retry later.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "PROVIDER_UNAVAILABLE" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "TRAVEL" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b", "code": "PROVIDER_UNAVAILABLE", "origin": "TRAVEL", "message": "Travel provider temporarily unavailable, please retry." } } } } }, "x-p3-confidence": { "response": "generated:typed", "parameters": "generated:typed" } } }, "/realms/{realmId}/organizations/{organizationId}/vehicle/searches/{searchId}/items/{itemId}": { "get": { "operationId": "getRealmsByRealmIdOrganizationsByOrganizationIdVehicleSearchesBySearchIdItemsByItemId", "summary": "Get a vehicle search item", "tags": [ "Vehicle search" ], "x-p3-sidebar-order": 5, "description": "Returns the full detail of one vehicle of a vehicle search: the vehicle and every fare option.", "x-mint": { "content": "Open a vehicle of the search results to see what the list only summarizes: its specifications and every fare option. To book it, create a trip with the item's `id` as `searchItemId` and the chosen `fareOptions` entry's `id` as `fareId`. Amounts are integers in cents: `98700` is R$ 987,00. The item lives as long as its search (see `ttl`). An error the travel provider reports about the request is returned with its own status, `code` and `message`." }, "parameters": [ { "name": "realmId", "in": "path", "required": true, "description": "ID of your realm.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b" }, { "name": "organizationId", "in": "path", "required": true, "description": "ID of your organization.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410" }, { "name": "searchId", "in": "path", "required": true, "description": "ID of the search, as returned when it was created.", "schema": { "type": "string", "pattern": "^srch_[0-9A-Za-z]{21}$" }, "example": "srch_V1StGXR8Z5jdHi6BmyT2k" }, { "name": "itemId", "in": "path", "required": true, "description": "ID of the item to load, as listed in the `items` of the search results.", "schema": { "type": "string", "pattern": "^srch_item_[0-9A-Za-z]{21}$" }, "example": "srch_item_V1StGXR8Z5jdHi6BmyT2k" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the item. Send it as `searchItemId` when you create a trip.", "example": "srch_item_Rn2Xd8GuYc4Wv6ZkJe1Ta" }, "searchId": { "type": "string", "description": "ID of the search the item belongs to.", "example": "srch_Hb7Yk1DrMv3Lq8UsAe0Xj" }, "groupName": { "type": "string", "description": "Name of the group of vehicles that fulfil the same booking class.", "example": "Economy" }, "class": { "type": "string", "description": "Class of the vehicle.", "example": "Economy" }, "name": { "type": "string", "description": "Commercial name of the vehicle.", "example": "Fiat Mobi" }, "sipp": { "type": "string", "description": "SIPP (ACRISS) code of the vehicle.", "example": "EDMR" }, "pickUpLocation": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the station.", "example": "Aurora Rent - Aeroporto de Guarulhos" }, "phoneNumbers": { "type": "array", "items": { "type": "string", "example": "+551133334444" }, "description": "Contact phone numbers. Empty when none is registered.\n\n---\n\nExample: `[\"+551133334444\"]`" }, "address": { "type": "object", "properties": { "shortAddress": { "type": "string", "nullable": true, "description": "The address in a single line. `null` when unknown.", "example": "Guarulhos, SP, Brazil" }, "adressLines": { "type": "array", "items": { "type": "string", "example": "Rod. Hélio Smidt, s/n" }, "description": "The address in postal lines. Empty when unknown. The field name is spelled `adressLines`.\n\n---\n\nExample: `[\"Rod. Hélio Smidt, s/n\"]`" }, "locality": { "type": "string", "nullable": true, "description": "City. `null` when unknown.", "example": "Guarulhos" }, "administrativeArea": { "type": "string", "nullable": true, "description": "State or province code. `null` when unknown.", "example": "SP" }, "administrativeAreaName": { "type": "string", "nullable": true, "description": "State or province name. `null` when unknown.", "example": "São Paulo" }, "postalCode": { "type": "string", "nullable": true, "description": "Postal code. `null` when unknown.", "example": "07190-100" }, "country": { "type": "string", "description": "Country (ISO 3166-1 alpha-2).", "example": "BR" }, "timezone": { "type": "string", "description": "IANA time zone of the place, or `Unknown`.", "example": "America/Sao_Paulo" }, "coordinates": { "description": "Position of the place. `null` when unknown.", "type": "object", "properties": { "lat": { "type": "number", "description": "Latitude, in decimal degrees.", "example": -23.4356 }, "lng": { "type": "number", "description": "Longitude, in decimal degrees.", "example": -46.4731 } }, "required": [ "lat", "lng" ], "nullable": true }, "localityId": { "type": "string", "nullable": true, "description": "ID of the locality the bus station belongs to. Bus stations only; `null` when the station is not grouped under a locality." } }, "required": [ "shortAddress", "adressLines", "locality", "administrativeArea", "administrativeAreaName", "postalCode", "country", "timezone", "coordinates" ], "description": "Address and position of the station." } }, "required": [ "name", "phoneNumbers", "address" ], "description": "Where the vehicle is picked up." }, "dropOffLocation": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the station.", "example": "Aurora Rent - Aeroporto de Guarulhos" }, "phoneNumbers": { "type": "array", "items": { "type": "string", "example": "+551133334444" }, "description": "Contact phone numbers. Empty when none is registered.\n\n---\n\nExample: `[\"+551133334444\"]`" }, "address": { "type": "object", "properties": { "shortAddress": { "type": "string", "nullable": true, "description": "The address in a single line. `null` when unknown.", "example": "Guarulhos, SP, Brazil" }, "adressLines": { "type": "array", "items": { "type": "string", "example": "Rod. Hélio Smidt, s/n" }, "description": "The address in postal lines. Empty when unknown. The field name is spelled `adressLines`.\n\n---\n\nExample: `[\"Rod. Hélio Smidt, s/n\"]`" }, "locality": { "type": "string", "nullable": true, "description": "City. `null` when unknown.", "example": "Guarulhos" }, "administrativeArea": { "type": "string", "nullable": true, "description": "State or province code. `null` when unknown.", "example": "SP" }, "administrativeAreaName": { "type": "string", "nullable": true, "description": "State or province name. `null` when unknown.", "example": "São Paulo" }, "postalCode": { "type": "string", "nullable": true, "description": "Postal code. `null` when unknown.", "example": "07190-100" }, "country": { "type": "string", "description": "Country (ISO 3166-1 alpha-2).", "example": "BR" }, "timezone": { "type": "string", "description": "IANA time zone of the place, or `Unknown`.", "example": "America/Sao_Paulo" }, "coordinates": { "description": "Position of the place. `null` when unknown.", "type": "object", "properties": { "lat": { "type": "number", "description": "Latitude, in decimal degrees.", "example": -23.4356 }, "lng": { "type": "number", "description": "Longitude, in decimal degrees.", "example": -46.4731 } }, "required": [ "lat", "lng" ], "nullable": true }, "localityId": { "type": "string", "nullable": true, "description": "ID of the locality the bus station belongs to. Bus stations only; `null` when the station is not grouped under a locality." } }, "required": [ "shortAddress", "adressLines", "locality", "administrativeArea", "administrativeAreaName", "postalCode", "country", "timezone", "coordinates" ], "description": "Address and position of the station." } }, "required": [ "name", "phoneNumbers", "address" ], "description": "Where the vehicle is dropped off." }, "pickUpDate": { "type": "string", "description": "Pick-up, in the local time of the station (`YYYY-MM-DDTHH:mm:ss`, no time-zone offset).", "example": "2026-11-02T10:00:00" }, "dropOffDate": { "type": "string", "description": "Drop-off, in the local time of the station (`YYYY-MM-DDTHH:mm:ss`, no time-zone offset).", "example": "2026-11-05T10:00:00" }, "model": { "type": "string", "description": "Model of the vehicle.", "example": "Mobi Like 1.0" }, "vehicleDetails": { "type": "object", "properties": { "hasAirConditioning": { "type": "boolean", "description": "Whether the vehicle has air conditioning.", "example": true }, "fuelType": { "type": "string", "enum": [ "ELECTRIC", "HYBRID", "FLEX", "DIESEL", "GASOLINE", "ETHANOL", "LPG", "HYDROGEN", "NOT_INFORMED" ], "description": "Fuel: `ELECTRIC`, `HYBRID`, `FLEX`, `DIESEL`, `GASOLINE`, `ETHANOL`, `LPG`, `HYDROGEN` or `NOT_INFORMED`.", "example": "FLEX" }, "category": { "type": "string", "description": "Category label.", "example": "Compact" }, "passengerQtd": { "type": "number", "description": "Passengers the vehicle seats.", "example": 5 }, "luggageQtd": { "type": "number", "description": "Pieces of luggage the vehicle holds.", "example": 2 }, "doorsQtd": { "type": "number", "description": "Number of doors.", "example": 4 }, "transmissionType": { "type": "string", "enum": [ "AUTOMATIC", "MANUAL", "NOT_INFORMED" ], "description": "`AUTOMATIC`, `MANUAL` or `NOT_INFORMED`.", "example": "MANUAL" }, "includedMileage": { "type": "string", "description": "Mileage included in the rental.", "example": "UNLIMITED" } }, "required": [ "hasAirConditioning", "fuelType", "category", "passengerQtd", "luggageQtd", "doorsQtd", "transmissionType", "includedMileage" ], "description": "Specifications of the vehicle." }, "rentalCompany": { "type": "object", "properties": { "code": { "type": "string", "description": "Code of the company.", "example": "AUR" }, "name": { "type": "string", "description": "Commercial name.", "example": "Aurora Rent" }, "logo": { "type": "string", "nullable": true, "description": "URL of the company's logo. `null` when unknown.", "example": "https://example.com/logos/aurora-rent.svg" } }, "required": [ "code", "name", "logo" ], "description": "Company that rents the vehicle." }, "mainImage": { "type": "object", "properties": { "uri": { "type": "string", "description": "URL of the image.", "example": "https://example.com/vehicles/compact.jpg" }, "blurHash": { "type": "string", "description": "BlurHash placeholder for previews. Omitted when unavailable.", "example": "LEHV6nWB2yk8pyo0adR*.7kCMdnj" }, "dominantColor": { "type": "string", "description": "Dominant color, as hex. Omitted when unavailable.", "example": "#c9d3dc" } }, "required": [ "uri" ], "description": "Main image of the vehicle." }, "fareOptions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the fare option. Send it as `fareId` when you create a trip with this item.", "example": "fare_Sv9Lc4TdHy1Qn6BwKe3Pr" }, "description": { "type": "string", "nullable": true, "description": "Name of the fare option. `null` when not available.", "example": "Basic protection" }, "fare": { "type": "object", "properties": { "currency": { "type": "string", "description": "Currency of the amounts (ISO 4217).", "example": "BRL" }, "originalAmount": { "type": "number", "description": "Price before discounts and fees, in cents.", "example": 48000 }, "discountAmount": { "type": "number", "description": "Discount applied to the original amount, in cents.", "example": 4800 }, "feeAmount": { "type": "number", "description": "Fees added to the rental, in cents.", "example": 1800 }, "amount": { "type": "number", "description": "Total charged for the rental: `originalAmount - discountAmount + feeAmount`, in cents (`45000` is R$ 450,00).", "example": 45000 }, "cancellationPolicies": { "type": "object", "properties": { "refundable": { "type": "boolean", "description": "Whether the fare allows any refund at all.", "example": true }, "immediateFine": { "type": "boolean", "description": "Whether a fine is charged for cancelling right after booking.", "example": false }, "penalties": { "type": "array", "items": { "type": "object", "properties": { "from": { "type": "string", "description": "Date (`YYYY-MM-DD`) from which this tier applies.", "example": "2026-10-30" }, "currency": { "type": "string", "description": "Currency of the penalty (ISO 4217).", "example": "BRL" }, "fineAmount": { "type": "number", "description": "Penalty charged when cancelling or changing from `from` onward, in cents.", "example": 15000 } }, "required": [ "from", "currency", "fineAmount" ], "description": "One tier of a cancellation or change penalty schedule." }, "description": "Penalty schedule, in effect from each tier's date. Empty or omitted when no scheduled penalty applies." } }, "required": [ "refundable", "immediateFine" ], "description": "Cancellation rules of the rate. Only in the item detail, not in the search results." }, "changePolicies": { "type": "object", "properties": { "canChange": { "type": "boolean", "description": "Whether the fare allows the booking to be changed.", "example": true }, "immediateFine": { "type": "boolean", "description": "Whether a fine is charged for changing right after booking.", "example": false }, "penalties": { "type": "array", "items": { "type": "object", "properties": { "from": { "type": "string", "description": "Date (`YYYY-MM-DD`) from which this tier applies.", "example": "2026-10-30" }, "currency": { "type": "string", "description": "Currency of the penalty (ISO 4217).", "example": "BRL" }, "fineAmount": { "type": "number", "description": "Penalty charged when cancelling or changing from `from` onward, in cents.", "example": 15000 } }, "required": [ "from", "currency", "fineAmount" ], "description": "One tier of a cancellation or change penalty schedule." }, "description": "Penalty schedule, in effect from each tier's date. Empty when none applies." } }, "required": [ "canChange", "immediateFine", "penalties" ], "description": "Change rules of the rate. Only in the item detail, not in the search results. Car rentals can't be changed today, so `canChange` is `false`." } }, "required": [ "currency", "originalAmount", "discountAmount", "feeAmount", "amount" ], "description": "Price of the fare option." } }, "required": [ "id", "description", "fare" ], "description": "One fare option of a vehicle." }, "description": "Every fare option of the vehicle, each with its price, rules and ID — send the chosen one's `id` as `fareId` when you create a trip." } }, "required": [ "id", "searchId", "groupName", "class", "name", "sipp", "pickUpLocation", "dropOffLocation", "pickUpDate", "dropOffDate", "model", "vehicleDetails", "rentalCompany", "mainImage", "fareOptions" ], "description": "The detail of one vehicle of a vehicle search: the vehicle and every fare option." } } } }, "404": { "description": "`SEARCH_NOT_FOUND` — The search doesn't exist, has expired, was created by another organization or is not a vehicle search.\n\n`VEHICLE_SEARCH_ITEM_NOT_FOUND` — The vehicle search has no item with this ID, or it expired.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "SEARCH_NOT_FOUND", "VEHICLE_SEARCH_ITEM_NOT_FOUND" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "TRAVEL" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b", "code": "SEARCH_NOT_FOUND", "origin": "TRAVEL", "message": "Search not found" } } } }, "422": { "description": "`BAD_REQUEST` — A path parameter is not a valid ID; `fields` lists each one.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "BAD_REQUEST" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "TRAVEL" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." }, "fields": { "type": "array", "description": "One entry per invalid request field (validation errors only).", "items": { "type": "object", "properties": { "field": { "type": "string", "description": "Path of the invalid field, e.g. `label` or `values[0].value`.", "example": "label" }, "message": { "type": "string", "description": "Why the field was rejected.", "example": "label is required" }, "code": { "type": "string", "description": "`_` — e.g. `LABEL_REQUIRED`, `TYPE_ONE_OF`, `VALUES_VALUE_TYPE_ERROR`.", "example": "LABEL_REQUIRED" }, "values": { "type": "array", "items": { "type": "string" }, "description": "The accepted values, when the field is an enumeration." } }, "required": [ "field", "message", "code" ] } } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "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": "organizationId", "message": "Invalid UUID", "code": "ORGANIZATIONID_UUID" } ] } } } }, "503": { "description": "`PROVIDER_UNAVAILABLE` — The travel provider could not be reached. Retry later.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "PROVIDER_UNAVAILABLE" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "TRAVEL" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b", "code": "PROVIDER_UNAVAILABLE", "origin": "TRAVEL", "message": "Travel provider temporarily unavailable, please retry." } } } } }, "x-p3-confidence": { "response": "generated:typed" } } } } }