Pedidos da Organization
Revise os pedidos de todos os Merchants da Organization a partir do Dashboard — liste-os, filtre-os e abra um para ver o detalhe completo.
Esses endpoints consolidam os pedidos de todos os Merchants da Organization em um só lugar: filtre por Merchant, status ou período, e abra um pedido para ver seus itens e as transações que o pagaram.
É o equivalente em nível de toda a Organization para a tela de pedidos do Merchant — os mesmos registros de pedidos, agregados entre Merchants para relatórios e suporte.
Esses endpoints alimentam a interface do Tokeflow Dashboard no nível da Organization. Eles são autenticados por sessão (JWT bearer) — o token vem do login no Dashboard, não de uma chave de API sk_/pk_. As solicitações também carregam o header x-organization-id, e o usuário autenticado deve ser membro dessa Organization.
Endpoints
GET/api/v1/org/orders
Auth: Dashboard session (JWT bearer). É necessário ser membro da Organization.
Lista os pedidos da Organization.
Parâmetros de consulta
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
page | number | Não | Número da página (indexado a partir de 1). Padrão 1, mín. 1. |
limit | number | Não | Número de itens por página. Padrão 20, mín. 1, máx. 100. |
status | array | Não | Lista de status de pedidos separados por vírgula |
order_type | string | Não | Filtra por tipo de pedido |
recurrence | string | Não | Filtra por recorrência |
currency | string | Não | Filtra por moeda (ISO 4217) |
search | string | Não | Busca por ID do pedido, nome do cliente, e-mail ou ID externo do pedido |
start_date | string | Não | Data de início (ISO 8601) |
end_date | string | Não | Data de término (ISO 8601) |
mode | string | Não | live ou test. Apenas pedidos cujo pagamento mais recente que chegou a um provedor rodou em um conector de produção (ou de teste). Um pedido sem esse tipo de pagamento não corresponde a nenhum dos dois. |
subscription_id | string | Não | Filtra por ID da assinatura |
Exemplo de solicitação
curl -G https://api.tokeflow.com/api/v1/org/orders \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
-H "x-organization-id: org_4b21e7c3" \
--data-urlencode "page=1" \
--data-urlencode "limit=20" \
--data-urlencode "status=['active']" \
--data-urlencode "order_type=api"GET/api/v1/org/orders/:id
Auth: Dashboard session (JWT bearer). É necessário ser membro da Organization.
Obtém um pedido por ID.
O detalhe do pedido inclui as transações que o pagaram e cada uma das tentativas delas. Cada pedido e cada transação trazem um mode (live, test ou null quando nenhum pagamento chegou a um provedor), e cada tentativa traz is_test_mode. Uma tentativa que falhou também mostra decline_reason — o motivo da falha segundo a Tokeflow, o mesmo valor qualquer que seja o provedor que respondeu — ao lado de psp_decline_code e psp_error_type, o código e a classe de erro próprios do provedor, como ele os informou.
Parâmetros de caminho
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
id | string | Sim | — |
Exemplo de solicitação
curl https://api.tokeflow.com/api/v1/org/orders/obj_1a2b3c4d \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
-H "x-organization-id: org_4b21e7c3"GET/api/v1/org/orders/:id/attempts/:attemptId/raw-response
Auth: Dashboard session (JWT bearer). É necessário ser membro da Organization.
Obtém a resposta bruta do PSP para uma tentativa.
Parâmetros de caminho
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
id | string | Sim | — |
attemptId | string | Sim | — |
Exemplo de solicitação
curl https://api.tokeflow.com/api/v1/org/orders/obj_1a2b3c4d/attempts/123/raw-response \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
-H "x-organization-id: org_4b21e7c3"POST/api/v1/org/orders/:id/refund
Auth: Dashboard session (JWT bearer). É necessário ser membro da Organization.
Reembolsa um pedido.
Parâmetros de caminho
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
id | string | Sim | — |
Campos da solicitação
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
amount | number | Não | Valor a reembolsar em unidades menores (reembolso parcial). Omita para reembolso total. |
reason | string | Não | Motivo do reembolso. Um de duplicate, fraudulent, requested_by_customer. |
Exemplo de solicitação
curl -X POST https://api.tokeflow.com/api/v1/org/orders/obj_1a2b3c4d/refund \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
-H "x-organization-id: org_4b21e7c3" \
-H "Content-Type: application/json" \
-d '{
"amount": 15000,
"reason": "requested_by_customer"
}'GET/api/v1/org/orders/:id/refunds
Auth: Dashboard session (JWT bearer). É necessário ser membro da Organization.
Lista os reembolsos de um pedido.
Parâmetros de caminho
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
id | string | Sim | — |
Parâmetros de consulta
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
page | number | Não | Número da página (indexado a partir de 1). Padrão 1, mín. 1. |
limit | number | Não | Número de itens por página. Padrão 20, mín. 1, máx. 100. |
Exemplo de solicitação
curl -G https://api.tokeflow.com/api/v1/org/orders/obj_1a2b3c4d/refunds \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
-H "x-organization-id: org_4b21e7c3" \
--data-urlencode "page=1" \
--data-urlencode "limit=20"Erros
Os erros usam o envelope padrão. Os casos mais comuns aqui:
| HTTP | Significado |
|---|---|
400 | Parâmetros inválidos ou um estado que não permite esta operação. |
401 | Token de sessão do Dashboard ausente, expirado ou inválido. |
403 | Autenticado, mas o usuário autenticado não tem acesso a esta entidade. |
404 | O registro não existe ou não é visível para esta entidade. |