API Reference

Criar novo pedido

post
https://platform-bff-partners.stg.clickbus.net/partners/api/v4/orders?mode=async

Cria um novo pedido com os itens, dados do cliente e informações de pagamento fornecidos. Este endpoint processa a criação completa de um pedido, incluindo validação dos dados, processamento do pagamento e geração do identificador único do pedido.

Recent Requests
Log in to see full request history
TimeStatusUser Agent
Retrieving recent requests…
LoadingLoading…

Diferenças entre os tipos de rota

A API retorna três tipos de viagem no campo type da busca de trips. Cada tipo impacta diretamente como o orderItem deve ser montado.

Conceitos

TipoDescrição
directViagem sem paradas intermediárias. O passageiro embarca na origem e desembarca no destino final no mesmo ônibus.
one_stopViagem com uma parada intermediária, mas sem troca de ônibus. O veículo faz uma pausa no terminal de conexão e segue viagem com o mesmo passageiro.
connectionViagem com troca de ônibus em um ponto intermediário (baldeação). Cada trecho é operado de forma independente e possui seu próprio UUID.

Impacto no payload do pedido

Campodirectone_stopconnection
type na busca"direct""one_stop""connection"
tripUuids["uuid-único"]["uuid-leg1", "uuid-leg2"]["uuid-leg1", "uuid-leg2"]
Número de orderItems1 item1 item por trecho1 item por trecho
meta.id no itemid seatBlock únicoid seatBlock trecho específicoid seatBlock trecho específico
meta.type no item"direct""one_stop""connection"
meta.tripLegausente ou 11 no primeiro, 2 no segundo1 no primeiro, 2 no segundo

Resumo prático: direct e one_stop são tratados da mesma forma no pedido — um único orderItem. A diferença entre eles existe apenas na experiência do passageiro (parada sem troca de ônibus). Já connection exige um orderItem separado para cada trecho, com tripLeg e o UUID correspondente.

Erros Comuns

ErroCausaSolução
400 Bad RequesttripLeg ausente em item de conexãoIncluir tripLeg: 1 e tripLeg: 2 em cada item
400 Bad RequestUUIDs trocados entre os trechosGarantir que tripUuids[0] vai para tripLeg: 1
401 Unauthorizedx-api-key inválidaVerificar credenciais com o time ClickBus
500 com code: "CHECKOUT_PENDING"O pedido foi criado, mas a confirmação na viação/pagamento não concluiu dentro da janela de espera da chamada síncronaNão repita o POST. Use o publicId do body de erro para consultar GET /partners/api/v5/orders/{publicId}/checkout-response até obter o resultado final

Erros após a criação do pedido

Na chamada síncrona (sem mode=async), a API cria o pedido e aguarda internamente a confirmação da viação e do pagamento antes de responder. Se qualquer erro acontecer depois de o pedido existir, o body de erro traz o campo publicId no nível raiz — é o identificador do pedido que já foi criado.

🚨

Regra: se a resposta de erro contém publicId, o pedido existe. Repetir o POST /orders cria um segundo pedido (e uma segunda cobrança). Consulte o status pelo publicId.

SituaçãoStatusComo identificarO que fazer
Confirmação não concluiu na janela de espera500code: "CHECKOUT_PENDING", error: "Polling timeout."Consultar GET /partners/api/v5/orders/{publicId}/checkout-response com intervalo de 2–5 s até status final
Viação/pagamento recusou o pedidostatus do erro (ex.: 400, 402)code numérico do serviço de origem em code e data.codeTratar como falha definitiva; o publicId serve para rastreio e suporte
Falha de comunicação ao consultar o resultado500 ou status do upstreampublicId presente, sem code: "CHECKOUT_PENDING"Consultar GET /partners/api/v5/orders/{publicId}/checkout-response

Se o erro acontecer antes de o pedido ser criado (validação, autenticação, indisponibilidade na criação), o body não traz publicId — nesse caso o POST pode ser repetido com segurança.

Exemplo — 500 com pedido criado

{
  "statusCode": 500,
  "error": "Polling timeout.",
  "code": "CHECKOUT_PENDING",
  "publicId": "QPOKV20Z",
  "message": ["Polling timeout."],
  "transactionId": "BFF=24978b17-2f9c-4552-a4b4-d52e98e0f5bc",
  "data": {
    "code": "CHECKOUT_PENDING",
    "error": "Polling timeout.",
    "message": "Polling timeout."
  }
}

Em seguida:

GET /partners/api/v5/orders/QPOKV20Z/checkout-response
💡

Para não depender da janela de espera, use ?mode=async: o POST responde 201 { "publicId" } imediatamente e o acompanhamento é feito pelo checkout-response.

Exemplos de payload do pedido

Direct

  • id: Id retornado do bloqueio de assento para aquele trecho da viagem.
{
  "orderItems": [
    {
      "type": "ticket",
      "meta": {
        "id": "xlv51gva3tgbmtz5ith2nvgxb",
        "amount": 89.9,
        "tripTypeDirection": "departure_type",
        "type": "direct",
        "insurance": false,
        "passenger": {
          "name": "João da Silva",
          "documentType": "cpf",
          "documentNumber": "01234567890"
        }
      }
    }
  ]
}

Connection ou One Stop

  • orderItems: Um objeto dentro do array por trecho.
  • id: Id retornado do bloqueio de assento para cada trecho da viagem.
  • tripLeg: Declaração explicita do trecho da viagem.
  • totalAmount: É a soma dos dois trechos.
{
  "orderItems": [
    {
      "type": "ticket",
      "meta": {
        "id": "xlv51gva3tgbmtz5ith2nvgxb",
        "amount": 72.95,
        "tripTypeDirection": "departure_type",
        "type": "connection",
        "tripLeg": 1,
        "insurance": false,
        "passenger": {
          "name": "João da Silva",
          "documentType": "cpf",
          "documentNumber": "01234567890"
        }
      }
    }
  ]
}

Exemplos de respostas

201 - Criado com Sucesso (Viagem Direta)

  • item: Array com no máximo 3 objetos, service_fee, ticket e insurance (a compra do seguro junto com a viagem é opcional)
{
  [...]
      "item": [
        //objeto do service_fee
        {
            "id": 217139285,
            "type": "ticket",
            "status": "COMPLETE",
            "createdAt": "2026-04-15 17:26:28",
            "updatedAt": "2026-04-15 17:26:33",
            "lastUpdatedBy": "whitelabel_busao",
            "externalId": "",
            "currency": "BRL",
            "amount": "44.40",
            "refundedAmount": "0.00",
            "itemDetails": {
                "ticket": {
                    [...]
                    "type": "direct",
                    "tripLeg": 1,
                    "tripType": "departure_type",
                    "boardingPass": true,
                    [...]
                }
            },
            "meta": {}
        },
        //objeto do seguro
    ],
}

201 - Criado com Sucesso (Viagem com Conexão ou One Stop)

  • item: Array com no mínimo 2 objetos, service_fee, ticket e insurance (a compra do seguro junto com a viagem é opcional)
{
  [...]
      "item": [
        //objeto do service_fee
        {
            "id": 217139285,
            "type": "ticket",
            "status": "COMPLETE",
            [...]
            "refundedAmount": "0.00",
            "itemDetails": {
                "ticket": {
                    [...]
                    "type": "connection",
                    "tripLeg": 1,
                    "tripType": "departure_type",
                    "boardingPass": true,
                    [...]
                }
            },
            [...]
        },
        {
            "id": 217139285,
            "type": "ticket",
            "status": "COMPLETE",
            [...]
            "refundedAmount": "0.00",
            "itemDetails": {
                "ticket": {
                    [...]
                    "type": "connection",
                    "tripLeg": 2,
                    "tripType": "departure_type",
                    "boardingPass": true,
                    [...]
                }
            },
            [...]
        },
        //objeto do seguro
    ],
}
Body Params
client
object
required
customer
object
required
device
object
required
orderItems
array of objects
required
length ≥ 1

Lista de itens do pedido

orderItems*
string
enum
required

Tipo do item

Allowed:
boolean
required
Defaults to false

Indica se é uma ClickOferta

meta
object
required
payment
object
required
double
required

Valor total do pedido

string

Identificador do pedido no sistema do parceiro (opcional)

Responses

Updated 11 days ago

Did this page help you?
Language
Credentials
Bearer
JWT
URL
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json

Updated 11 days ago

Did this page help you?