API Reference

Consultar lista de pedidos

get
https://platform-bff-partners.stg.clickbus.net/partners/api/v6/orders

Consulta lista de pedidos por um filtro específico. Retorna informações resumidas sobre os pedidos, incluindo dados do cliente, tickets de ida e volta, pagamentos e status. Permite identificação do cliente por email, documento ou telefone, com suporte a filtros por data de embarque, status e ordenação. Ideal para exibir histórico de viagens ou próximas viagens do cliente.

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

Observações

  • Identificação do cliente: É obrigatório fornecer pelo menos um dos parâmetros: email, documentNumber ou phone. Caso nenhum seja enviado, retorna 400.
  • externalRemoteId: ID externo fornecido pelo parceiro no checkout. Quando informado, dispensa a obrigatoriedade de email/documento/telefone — busca diretamente pelo identificador do parceiro.
  • size: Controla a quantidade máxima de pedidos retornados. Quando omitido, retorna todos os pedidos encontrados.
  • departureDateFrom / departureDateTo: Formato YYYY-MM-DDTHH:mm. Define o range de datas de embarque. Use departureDateFrom sozinho para "próximas viagens", ou combine com departureDateTo para um período específico.
  • dateFrom / dateTo: Formato YYYY-MM-DD. Filtra pela data de criação do pedido (data da compra), diferente de departureDateFrom/To que filtra pela data de embarque.
  • localizer: Código localizador do ticket (o código que o passageiro recebe). Busca exata.
  • passenger: Nome do passageiro. Suporta busca parcial (contém).
  • sort: Aceita exatamente 4 combinações: departureDate,asc, departureDate,desc, createdAt,asc, createdAt,desc. Qualquer outro valor é ignorado.
  • ticketStatus: Filtra pelo status dos tickets/itens do pedido (não o status do pedido em si). Valores possíveis: completed, pending, canceled, partially_canceled.
  • status: Filtra pelo status da ordem (diferente de ticketStatus). Valores possíveis: pending, completed, canceled, partially_canceled, incomplete.
  • Pedidos sem ticket de volta: O campo tickets.return será null para viagens somente ida.
  • Pedidos com múltiplos passageiros: O array passengerNames dentro de cada ticket contém todos os nomes dos passageiros daquele trecho.

Cenários de uso

Listar próximas viagens do cliente

GET /partners/api/v6/[email protected]&departureDateFrom=2025-06-01T00:00&sort=departureDate,asc&ticketStatus=completed

Retorna apenas pedidos com embarque futuro, ordenados por data de partida crescente, que já foram pagos com sucesso.

Buscar pedido pelo ID externo do parceiro

GET /partners/api/v6/orders?externalRemoteId=PARTNER-ORDER-789

Busca diretamente pelo identificador que o parceiro informou no checkout. Não precisa de email/documento.

Buscar pedido pelo localizador do ticket

GET /partners/api/v6/[email protected]&localizer=ABC123

Localiza o pedido pelo código que o passageiro recebeu no ticket.

Listar pedidos em um período de embarque

GET /partners/api/v6/[email protected]&departureDateFrom=2025-07-01T00:00&departureDateTo=2025-07-31T23:59&sort=departureDate,asc

Retorna pedidos com embarque no mês de julho/2025.

Listar pedidos por período de compra

GET /partners/api/v6/orders?documentNumber=12345678901&dateFrom=2025-01-01&dateTo=2025-03-31&sort=createdAt,desc

Retorna pedidos criados no primeiro trimestre de 2025.

Buscar por nome do passageiro

GET /partners/api/v6/[email protected]&passenger=José

Busca pedidos que contenham um passageiro com o nome informado.

Listar histórico completo por documento

GET /partners/api/v6/orders?documentNumber=12345678901&sort=createdAt,desc&size=10

Retorna os 10 pedidos mais recentes do cliente identificado pelo CPF, independente de status.

Listar pedidos por telefone

GET /partners/api/v6/orders?phone=11999998888&size=5

Busca pelo telefone quando email/documento não estão disponíveis (ex: atendimento por chatbot).

Filtrar somente pedidos cancelados

GET /partners/api/v6/[email protected]&status=canceled

Retorna apenas pedidos com status de ordem cancelada.

Exemplos de respostas

200 - Sucesso (viagem ida e volta)

[
  {
    "publicId": "Q4RPRZ85",
    "status": "completed",
    "createdAt": "2024-09-27T20:25:01.203",
    "totalAmount": 154.90,
    "currency": "BRL",
    "clientApplication": {
      "id": 2,
      "name": "BR Web Desktop"
    },
    "customer": {
      "email": "[email protected]",
      "activeUser": true
    },
    "directionNextTrip": null,
    "tickets": {
      "departure": {
        "origin": "Sao Paulo, SP - Tiete",
        "destination": "Campinas, SP",
        "originSlug": "sao-paulo-tiete-sp",
        "destinationSlug": "campinas-sp",
        "travelCompany": "LiraBus",
        "departureDate": "2024-10-15T02:00:00",
        "arrivalDate": "2024-10-15T03:15:00",
        "passengerNames": ["José da Silva"]
      },
      "return": {
        "origin": "Campinas, SP",
        "destination": "Sao Paulo, SP - Tiete",
        "originSlug": "campinas-sp",
        "destinationSlug": "sao-paulo-tiete-sp",
        "travelCompany": "LiraBus",
        "departureDate": "2024-10-20T18:00:00",
        "arrivalDate": "2024-10-20T19:15:00",
        "passengerNames": ["José da Silva"]
      }
    },
    "payments": [
      {
        "paymentGateway": "mercadoPago",
        "paymentType": "credit_card"
      }
    ]
  }
]

200 - Sucesso (somente ida, múltiplos passageiros)

[
  {
    "publicId": "AB12CD34",
    "status": "completed",
    "createdAt": "2024-11-05T10:30:00.000",
    "totalAmount": 210.00,
    "currency": "BRL",
    "clientApplication": {
      "id": 5,
      "name": "Partner App"
    },
    "customer": {
      "email": "[email protected]",
      "activeUser": true
    },
    "directionNextTrip": null,
    "tickets": {
      "departure": {
        "origin": "Rio de Janeiro, RJ - Rodoviária do Rio",
        "destination": "São Paulo, SP - Tietê",
        "originSlug": "rio-de-janeiro-rj",
        "destinationSlug": "sao-paulo-tiete-sp",
        "travelCompany": "Catarinense",
        "departureDate": "2024-12-01T08:00:00",
        "arrivalDate": "2024-12-01T14:00:00",
        "passengerNames": ["Maria Silva", "João Silva"]
      },
      "return": null
    },
    "payments": [
      {
        "paymentGateway": "mercadoPago",
        "paymentType": "pix"
      }
    ]
  }
]

200 - Sucesso (pedido cancelado)

[
  {
    "publicId": "XY98WZ76",
    "status": "canceled",
    "createdAt": "2024-08-10T14:20:00.000",
    "totalAmount": 89.90,
    "currency": "BRL",
    "clientApplication": {
      "id": 2,
      "name": "BR Web Desktop"
    },
    "customer": {
      "email": "[email protected]",
      "activeUser": true
    },
    "directionNextTrip": null,
    "tickets": {
      "departure": {
        "origin": "Belo Horizonte, MG - Rodoviária",
        "destination": "São Paulo, SP - Tietê",
        "originSlug": "belo-horizonte-mg",
        "destinationSlug": "sao-paulo-tiete-sp",
        "travelCompany": "Util",
        "departureDate": "2024-09-01T22:00:00",
        "arrivalDate": "2024-09-02T05:30:00",
        "passengerNames": ["Carlos Oliveira"]
      },
      "return": null
    },
    "payments": [
      {
        "paymentGateway": "mercadoPago",
        "paymentType": "credit_card"
      }
    ]
  }
]

200 - Lista vazia (nenhum pedido encontrado)

[]

400 - Nenhum identificador fornecido

{
  "statusCode": 400,
  "message": ["É obrigatório fornecer pelo menos um dos parâmetros: email, documentNumber ou phone"],
  "error": "Bad Request",
  "transactionId": "BFF=24978b17-2f9c-4552-a4b4-d52e98e0f5bc"
}

400 - Email inválido

{
  "statusCode": 400,
  "message": ["email must be an valid email. Value: emailinvalido"],
  "error": "Bad Request",
  "transactionId": "BFF=3a1b2c3d-4e5f-6789-abcd-ef0123456789"
}

401 - Não autorizado

{
  "statusCode": 401,
  "message": ["Unauthorized"],
  "error": "Unauthorized",
  "transactionId": "BFF=11111111-2222-3333-4444-555555555555"
}

500 - Erro interno

{
  "error": "Internal Server Error",
  "message": "An unexpected error occurred",
  "statusCode": 500
}
Query Params
string

ID externo fornecido pelo parceiro no momento do checkout. Quando informado, dispensa a obrigatoriedade de email/documentNumber/phone — a busca é feita diretamente pelo identificador do parceiro.

string

E-mail do cliente. Obrigatório se documentNumber, phone e externalRemoteId não forem fornecidos. Deve ser um email válido. A busca é case-insensitive.

number

Número de telefone do cliente. Deve ser numérico, sem caracteres especiais (sem +, parênteses, hífens ou espaços). Inclui DDD. Obrigatório se email e documentNumber não forem fornecidos.

number

Número do documento do cliente (CPF). Deve ser numérico, sem pontos ou hífens. Obrigatório se email e phone não forem fornecidos.

number

Quantidade máxima de pedidos retornados na resposta. Quando omitido, retorna todos os pedidos encontrados para os filtros informados. Recomendação: usar sempre para evitar respostas muito grandes em clientes com muitos pedidos.

string

Data de embarque a partir da qual filtrar os pedidos (inclusive). Formato: YYYY-MM-DDTHH:mm. Filtra pedidos cuja data de partida do ticket é igual ou posterior ao valor informado. Ideal para listar "próximas viagens".

string

Data de embarque até a qual filtrar os pedidos (inclusive). Formato: YYYY-MM-DDTHH:mm. Use em conjunto com departureDateFrom para definir um período específico de embarque.

string

Filtra pedidos criados a partir desta data (inclusive). Formato: YYYY-MM-DD. Refere-se à data de criação/compra do pedido, não à data de embarque.

string

Filtra pedidos criados até esta data (inclusive). Formato: YYYY-MM-DD. Use em conjunto com dateFrom para definir um período de compras.

string

Código localizador do ticket. É o código que o passageiro recebe após a compra para identificar sua passagem. Busca exata.

string

Nome do passageiro para busca. Suporta busca parcial (contém o texto informado). Útil quando o parceiro quer localizar um pedido pelo nome de quem vai viajar.

string
enum

Critério de ordenação dos pedidos no formato "campo,direção". Valores aceitos: departureDate,asc | departureDate,desc | createdAt,asc | createdAt,desc. 'departureDate' ordena pela data de embarque do ticket; 'createdAt' ordena pela data de criação do pedido. Quando omitido, a ordenação padrão é por relevância interna.

Allowed:
string
enum

Filtra pedidos pelo status dos tickets/itens. Atenção: filtra pelo status dos itens internos do pedido, não pelo status da ordem em si. 'completed' = tickets emitidos com sucesso; 'pending' = aguardando processamento; 'canceled' = tickets cancelados; 'partially_canceled' = parcialmente cancelados.

Allowed:
string
enum

Filtra pelo status da ordem (diferente de ticketStatus que filtra itens). 'pending' = aguardando processamento do pagamento; 'completed' = pagamento confirmado; 'canceled' = pedido totalmente cancelado; 'partially_canceled' = alguns itens cancelados, outros ativos; 'incomplete' = falha no pagamento ou timeout.

Allowed:
Responses

Updated 4 months 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 4 months ago

Did this page help you?