Pedidos

Consulte e filtre pedidos — o registro comercial que agrupa as tentativas de pagamento por trás de cada compra, checkout, renovação e fluxo de configuração.

Um pedido é o registro comercial de uma única intenção de compra. É a âncora durável e legível por humanos que agrupa uma ou mais tentativas de pagamento — as transações que a Tokeflow orquestra entre os provedores conectados — sob um identificador estável que você pode exibir em um recibo, reconciliar com seu razão contábil ou consultar no suporte.

Você nunca cria um pedido diretamente. A Tokeflow abre um automaticamente no momento em que uma cobrança é iniciada e, então, mantém seu status em sincronia com a transação subjacente conforme ela avança pelas suas regras de roteamento.

A Tokeflow é orquestração de pagamentos, não um processador de pagamentos. Um pedido registra e padroniza o evento comercial; o provedor conectado autoriza, captura e liquida os fundos. A Tokeflow nunca movimenta nem liquida dinheiro.

Como os pedidos são criados

Cada caminho de cobrança produz exatamente um pedido, distinguido pelo seu order_type:

`order_type`	Criado quando	`recurrence` típico
`api`	Você chama `POST /transactions` diretamente.	`none`
`checkout`	Uma sessão de Checkout hospedada ou embutida é paga.	`none` ou `initial`
`renewal`	Uma assinatura fatura um novo ciclo.	`subsequent`
`trial_setup`	Uma assinatura de teste é provisionada e sua primeira cobrança/cobrança de configuração é executada.	`initial`
`card_setup`	Um cartão é verificado e tokenizado sem uma venda imediata (uma verificação de zero valor/somente autorização).	`none`

O status do pedido é derivado da transação que ele agrupa. Conforme a transação é autorizada, estornada ou sofre chargeback, a Tokeflow avança o status do pedido e adiciona uma entrada ao seu histórico de status.

Hoje um pedido agrupa uma única transação de pagamento primária. O modelo de dados foi construído para agrupar múltiplas tentativas (por exemplo, um fallback em cascata entre provedores) sob um único pedido, portanto sempre trate o pedido — e não uma transação isolada — como a unidade de reconciliação.

O objeto do pedido

{
  "id": "ord_9f8e7d6c5b4a3210",
  "merchant_id": "mrc_8a1b2c3d4e5f",
  "organization_id": "org_1a2b3c4d5e6f",
  "customer_id": "cust_kj3x8rabc123",
  "external_order_id": "shop_order_456",
  "checkout_session_id": "cks_a1b2c3d4e5",
  "order_type": "checkout",
  "recurrence": "initial",
  "total_amount": 9900,
  "currency": "BRL",
  "status": "authorized",
  "metadata": {
    "cart_id": "cart_7788",
    "campaign": "winter_sale"
  },
  "created_at": "2026-01-15T12:30:00.000Z",
  "updated_at": "2026-01-15T12:30:04.000Z",
  "items": [
    {
      "id": "f3a1c2d4-1111-4a2b-9c3d-5e6f7a8b9c0d",
      "product_id": "prd_a1b2c3d4e5",
      "offer_id": "ofr_a1b2c3d4e5",
      "product_name": "Premium Plan",
      "offer_name": "Annual Discount",
      "billing_cycle": "yearly",
      "cycle_limit": 12,
      "is_first_charge": true,
      "quantity": 1,
      "unit_amount": 9900,
      "total_amount": 9900,
      "currency": "BRL",
      "installments": 1,
      "created_at": "2026-01-15T12:30:00.000Z"
    }
  ],
  "status_history": [
    {
      "from_status": null,
      "to_status": "pending",
      "triggered_by": "api",
      "created_at": "2026-01-15T12:30:00.000Z"
    },
    {
      "from_status": "pending",
      "to_status": "authorized",
      "triggered_by": "psp_webhook",
      "created_at": "2026-01-15T12:30:04.000Z"
    }
  ]
}

Campos

Field	Type	Description
`id`	string	Identificador único do pedido, prefixado com `ord_`.
`merchant_id`	string	Merchant proprietário do pedido (`mrc_`).
`organization_id`	string	Organization à qual o merchant pertence (`org_`).
`customer_id`	string	Cliente ao qual o pedido pertence (`cust_`).
`external_order_id`	string \| null	Sua própria referência de pedido, retornada para reconciliação. `null` quando não fornecida.
`checkout_session_id`	string \| null	Sessão de checkout de origem (`cks_`) para pedidos `checkout` / `trial_setup`; `null` caso contrário.
`order_type`	string	Como o pedido foi originado. Um de `api`, `checkout`, `renewal`, `trial_setup`, `card_setup`.
`recurrence`	string	Posição em uma série recorrente: `none`, `initial`, `subsequent` ou `unscheduled`.
`total_amount`	integer	Total em unidades menores (centavos). `9900` = R$99,00.
`currency`	string	Código de moeda ISO 4217 (por exemplo, `BRL`).
`status`	string	Status atual do pedido. Consulte Status do pedido.
`metadata`	object \| null	Dados arbitrários de chave/valor que você anexa na criação.
`created_at`	string	Timestamp de criação em ISO 8601 UTC.
`updated_at`	string	Timestamp da última atualização em ISO 8601 UTC.
`items`	array	Itens de linha capturados como snapshot na criação do pedido. Retornados pelo endpoint de pedido único; vazios/omitidos nos resultados de lista.
`status_history`	array	Transições de status ordenadas. Retornadas pelo endpoint de pedido único.

Os resultados de lista (GET /orders) retornam os cabeçalhos do pedido — os campos de nível superior acima. Os arrays items e status_history são preenchidos apenas quando você recupera um único pedido por ID.

Campos do item do pedido

Cada item de linha é um snapshot imutável do produto e da oferta no momento em que o pedido foi criado, de modo que pedidos históricos permaneçam precisos mesmo depois de você alterar seu catálogo.

Field	Type	Description
`id`	string	Identificador do item de linha (UUID).
`product_id`	string \| null	Referência do produto (`prd_`).
`offer_id`	string \| null	Referência da oferta (`ofr_`).
`product_name`	string	Snapshot do nome do produto.
`offer_name`	string \| null	Snapshot do nome da oferta.
`billing_cycle`	string \| null	Snapshot do ciclo de faturamento da oferta (por exemplo, `monthly`, `yearly`). `null` para itens avulsos.
`cycle_limit`	integer \| null	Snapshot do limite de ciclos da oferta, se houver.
`is_first_charge`	boolean	`true` quando o preço de primeira cobrança / configuração foi aplicado.
`quantity`	integer	Quantidade adquirida.
`unit_amount`	integer	Preço unitário em unidades menores (reflete o preço de primeira cobrança quando `is_first_charge` é `true`).
`total_amount`	integer	Total da linha em unidades menores (`unit_amount` × `quantity`).
`currency`	string	Código de moeda ISO 4217.
`installments`	integer \| null	Parcelas escolhidas no checkout. `null` ou `1` significa uma única cobrança.
`created_at`	string	Timestamp em ISO 8601 UTC.

Campos do histórico de status

Field	Type	Description
`from_status`	string \| null	Status antes da transição. `null` para a primeira entrada.
`to_status`	string	Status após a transição.
`triggered_by`	string	O que provocou a mudança (por exemplo, `api`, `system`, `psp_webhook`).
`created_at`	string	Timestamp da transição em ISO 8601 UTC.

Status do pedido

Status	Meaning
`pending`	Pedido criado; a cobrança ainda não foi concluída.
`pre_authorized`	Uma reserva de autorização está em vigor, aguardando captura.
`authorized`	A cobrança foi bem-sucedida (autorizada/capturada).
`failed`	A cobrança não foi bem-sucedida. Terminal.
`canceled`	O pedido foi cancelado antes da conclusão. Terminal.
`refund_pending`	Um estorno foi solicitado e está sendo processado.
`partially_refunded`	Parte do valor foi estornada.
`refunded`	O valor total foi estornado.
`charged_back`	Um chargeback foi registrado contra o pedido.

O status do pedido espelha o ciclo de vida da transação subjacente. Para inspecionar o detalhe em nível de pagamento por trás de um status — resultados do provedor, capturas, cancelamentos — leia a transação vinculada e seus estornos.

Endpoints

URL base: https://api.tokeflow.com — todas as rotas ficam sob /api/v1.

Os pedidos são somente leitura pela API. Autentique-se com uma chave secreta do lado do servidor (Authorization: Bearer sk_live_…). Consulte Autenticação para a anatomia e os escopos da chave. Ambos os endpoints exigem o escopo orders:read.

Chaves secretas (sk_*) são exclusivas do lado do servidor — nunca as exponha em código de navegador ou mobile.

GET`/api/v1/orders`

Auth: chave de Organization (com merchant_id) ou chave de Merchant.

Retorna uma lista paginada de cabeçalhos de pedidos para o merchant resolvido, com os dados mais recentes primeiro. Uma chave de Merchant infere seu merchant automaticamente. Uma chave de Organization abrange todos os merchants da org, portanto ela deve passar merchant_id para delimitar a consulta.

Parâmetros de query

Field	Type	Required	Description
`merchant_id`	string	Condicional	Obrigatório para chaves de Organization; omita para chaves de Merchant (inferido).
`status`	string	Não	Filtra por status do pedido. Repita o parâmetro ou passe uma lista separada por vírgulas para múltiplos valores (por exemplo, `status=authorized,refunded`).
`customer_id`	string	Não	Retorna apenas pedidos deste cliente (`cust_`).
`external_order_id`	string	Não	Corresponde à sua própria referência de pedido.
`order_type`	string	Não	Um de `api`, `checkout`, `renewal`, `trial_setup`, `card_setup`.
`currency`	string	Não	Código de moeda ISO 4217 (por exemplo, `BRL`).
`date_from`	string	Não	Inclui pedidos criados nesta data ou depois dela, no formato ISO 8601.
`date_to`	string	Não	Inclui pedidos criados nesta data ou antes dela, no formato ISO 8601.
`page`	integer	Não	Número da página, indexado a partir de 1. Padrão `1`.
`limit`	integer	Não	Itens por página. Padrão `20`, máximo `100`.

Requisição

curl -G "https://api.tokeflow.com/api/v1/orders" \
  -H "Authorization: Bearer sk_live_mer_xxxxxxxxxxxxxxxx" \
  -H "Accept: application/json" \
  --data-urlencode "page=1" \
  --data-urlencode "limit=20" \
  --data-urlencode "status=authorized,refunded" \
  --data-urlencode "order_type=checkout" \
  --data-urlencode "currency=BRL" \
  --data-urlencode "date_from=2026-01-01T00:00:00Z" \
  --data-urlencode "date_to=2026-01-31T23:59:59Z"

Com uma chave de Organization, adicione merchant_id à query string para delimitar a lista a um único merchant: GET /api/v1/orders?merchant_id=mrc_8a1b2c3d4e5f&status=authorized

Resposta `200 OK`

{
  "success": true,
  "data": [
    {
      "id": "ord_9f8e7d6c5b4a3210",
      "merchant_id": "mrc_8a1b2c3d4e5f",
      "organization_id": "org_1a2b3c4d5e6f",
      "customer_id": "cust_kj3x8rabc123",
      "external_order_id": "shop_order_456",
      "checkout_session_id": "cks_a1b2c3d4e5",
      "order_type": "checkout",
      "recurrence": "initial",
      "total_amount": 9900,
      "currency": "BRL",
      "status": "authorized",
      "metadata": { "cart_id": "cart_7788" },
      "created_at": "2026-01-15T12:30:00.000Z",
      "updated_at": "2026-01-15T12:30:04.000Z"
    },
    {
      "id": "ord_1122334455667788",
      "merchant_id": "mrc_8a1b2c3d4e5f",
      "organization_id": "org_1a2b3c4d5e6f",
      "customer_id": "cust_kj3x8rabc123",
      "external_order_id": null,
      "checkout_session_id": null,
      "order_type": "api",
      "recurrence": "none",
      "total_amount": 15000,
      "currency": "BRL",
      "status": "refunded",
      "metadata": null,
      "created_at": "2026-01-12T09:05:00.000Z",
      "updated_at": "2026-01-13T17:42:00.000Z"
    }
  ],
  "meta": {
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 42,
      "total_pages": 3,
      "has_next": true,
      "has_prev": false
    }
  },
  "request_id": "req_8f3c2a1b9d7e",
  "timestamp": "2026-01-15T12:30:00.000Z"
}

GET`/api/v1/orders/:id`

Auth: chave de Organization (com merchant_id) ou chave de Merchant.

Recupera um único pedido com seus items e status_history. O pedido é retornado apenas se pertencer ao merchant resolvido (e, para chaves de Organization, ao merchant_id especificado dentro da sua organization).

Parâmetros de path

Field	Type	Required	Description
`id`	string	Sim	O ID do pedido (`ord_`).

Parâmetros de query

Field	Type	Required	Description
`merchant_id`	string	Condicional	Obrigatório para chaves de Organization; omita para chaves de Merchant.

Requisição

curl "https://api.tokeflow.com/api/v1/orders/ord_9f8e7d6c5b4a3210" \
  -H "Authorization: Bearer sk_live_mer_xxxxxxxxxxxxxxxx" \
  -H "Accept: application/json"

Resposta `200 OK`

{
  "success": true,
  "data": {
    "id": "ord_9f8e7d6c5b4a3210",
    "merchant_id": "mrc_8a1b2c3d4e5f",
    "organization_id": "org_1a2b3c4d5e6f",
    "customer_id": "cust_kj3x8rabc123",
    "external_order_id": "shop_order_456",
    "checkout_session_id": "cks_a1b2c3d4e5",
    "order_type": "checkout",
    "recurrence": "initial",
    "total_amount": 9900,
    "currency": "BRL",
    "status": "authorized",
    "metadata": { "cart_id": "cart_7788", "campaign": "winter_sale" },
    "created_at": "2026-01-15T12:30:00.000Z",
    "updated_at": "2026-01-15T12:30:04.000Z",
    "items": [
      {
        "id": "f3a1c2d4-1111-4a2b-9c3d-5e6f7a8b9c0d",
        "product_id": "prd_a1b2c3d4e5",
        "offer_id": "ofr_a1b2c3d4e5",
        "product_name": "Premium Plan",
        "offer_name": "Annual Discount",
        "billing_cycle": "yearly",
        "cycle_limit": 12,
        "is_first_charge": true,
        "quantity": 1,
        "unit_amount": 9900,
        "total_amount": 9900,
        "currency": "BRL",
        "installments": 1,
        "created_at": "2026-01-15T12:30:00.000Z"
      }
    ],
    "status_history": [
      {
        "from_status": null,
        "to_status": "pending",
        "triggered_by": "api",
        "created_at": "2026-01-15T12:30:00.000Z"
      },
      {
        "from_status": "pending",
        "to_status": "authorized",
        "triggered_by": "psp_webhook",
        "created_at": "2026-01-15T12:30:04.000Z"
      }
    ]
  },
  "request_id": "req_7b2d1e0c8f6a",
  "timestamp": "2026-01-15T12:30:05.000Z"
}

Resposta `404 Not Found`

Retornada quando o pedido não existe ou não pertence ao merchant resolvido.

{
  "error": {
    "type": "not_found_error",
    "code": "ORDER_NOT_FOUND",
    "message": "Order ord_9f8e7d6c5b4a3210 not found or does not belong to your merchant",
    "details": {},
    "request_id": "req_3c9a7f2b1d8e",
    "timestamp": "2026-01-15T12:31:00.000Z"
  }
}

Erros

Os pedidos usam o envelope de erro padrão. Casos comuns:

HTTP	`type`	Quando
401	`authentication_error`	Chave de API ausente ou inválida.
403	`authorization_error`	A chave não possui o escopo `orders:read`, ou uma chave de Organization omitiu `merchant_id`.
404	`not_found_error`	Pedido não encontrado, ou não pertencente ao merchant resolvido.
429	`rate_limit_error`	Limite de requisições excedido (padrão de 600 requisições / minuto por chave em cada rota de pedidos). Respeite o `Retry-After`, faça backoff e tente novamente.

Relacionados

Transações — as tentativas de pagamento que um pedido agrupa, e onde ficam os estornos.
Checkout — sessões que criam pedidos checkout.
Assinaturas — a origem dos pedidos renewal e trial_setup.
Autenticação — tipos de chave, escopos e a regra de merchant_id para chaves de Organization.

Pedidos

GET/api/v1/orders

GET/api/v1/orders/:id

Nesta página

GET`/api/v1/orders`

GET`/api/v1/orders/:id`