Visão geral da referência da API

A API da Tokeflow é uma interface JSON-sobre-HTTPS para orquestração de pagamentos. Use-a para gerenciar clientes, executar sessões de checkout, criar e capturar transações, emitir reembolsos, modelar seu catálogo e conduzir assinaturas — tudo padronizado sob sua própria marca, em todos os provedores de pagamento que você conectar.

A Tokeflow orquestra pagamentos; ela não processa nem liquida fundos. Autorização, captura e liquidação são realizadas pelos provedores de pagamento conectados. A Tokeflow normaliza o comportamento deles atrás de uma única API consistente, para que sua integração permaneça a mesma independentemente de quem esteja por trás.

Esta página é o hub de convenções. Leia-a uma vez, e todas as páginas de endpoint desta referência se comportarão da maneira que você espera.

URL base e versionamento

Todas as requisições vão para uma única URL base:

https://api.tokeflow.com

A API usa versionamento por URI. Todo endpoint fica sob um prefixo de versão, e a versão atual é v1:

https://api.tokeflow.com/api/v1/{resource}

Mudanças incompatíveis são lançadas sob um novo prefixo de versão (por exemplo /api/v2). Mudanças aditivas e retrocompatíveis — novos campos, novos valores de enum, novos endpoints — podem aparecer dentro da v1, então construa clientes que ignorem campos desconhecidos.

Autenticação

Autentique requisições servidor-para-servidor com uma chave de API secreta no cabeçalho Authorization usando o esquema Bearer:

Authorization: Bearer sk_live_mer_…

As chaves têm escopo para exatamente uma entidade:

Chaves públicas (pk_live_org_… / pk_live_mer_…) são restritas a escopos seguros para o cliente e são seguras para embutir em código de navegador. Chaves secretas (sk_*) nunca devem ser expostas no lado do cliente.

As permissões seguem um modelo resource:action (por exemplo transactions:read, products:write). Uma requisição que autentica mas não possui o escopo necessário retorna 403 (authorization_error).

Consulte Autenticação para detalhes sobre anatomia de chaves, rotação e escopos.

Chaves de Organization e merchant_id

Quando você usa uma chave de Organization em um recurso com escopo de Merchant, você deve informar à Tokeflow a qual Merchant você se refere:

• Em requisições de listagem e obtenção, passe merchant_id como parâmetro de query.
• Em requisições de criação, passe merchant_id no corpo da requisição.

Chaves de Merchant nunca precisam disso — o Merchant é derivado da chave.

# Organization key: merchant_id is required
curl https://api.tokeflow.com/api/v1/customers?merchant_id=mrc_a1b2c3 \
  -H "Authorization: Bearer sk_live_org_…"

# Merchant key: merchant is inferred
curl https://api.tokeflow.com/api/v1/customers \
  -H "Authorization: Bearer sk_live_mer_…"

Formato da requisição

Envie e aceite JSON.

Uma requisição típica:

curl -X POST https://api.tokeflow.com/api/v1/customers \
  -H "Authorization: Bearer sk_live_mer_…" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "name": "Joao da Silva",
    "email": "joao@example.com"
  }'

Envelope de resposta

Toda resposta é envolvida em um envelope consistente. Seu código lê success para ramificar, depois data para o payload — nunca o objeto de nível superior diretamente.

Envelope de sucesso

Uma resposta bem-sucedida define success: true e carrega o recurso (ou array de recursos) em data:

{
  "success": true,
  "data": {
    "id": "cust_9a8b7c",
    "name": "Joao da Silva",
    "email": "joao@example.com",
    "created_at": "2026-01-15T12:30:00.000Z"
  },
  "request_id": "req_8f3c…",
  "timestamp": "2026-01-15T12:30:00.000Z"
}

Onde as coisas ficam:

Para um endpoint de listagem, data é o array e meta.pagination descreve a página:

{
  "success": true,
  "data": [
    { "id": "cust_9a8b7c", "name": "Joao da Silva" },
    { "id": "cust_4d5e6f", "name": "Maria Souza" }
  ],
  "meta": {
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 42,
      "total_pages": 3,
      "has_next": true,
      "has_prev": false
    }
  },
  "request_id": "req_8f3c…",
  "timestamp": "2026-01-15T12:30:00.000Z"
}

Envelope de erro

Erros nunca são envolvidos em data. Eles usam um formato dedicado com um code estável e legível por máquina:

{
  "error": {
    "type": "validation_error",
    "code": "INVALID_FIELD",
    "message": "The 'currency' field must be a valid ISO 4217 code.",
    "details": {
      "field": "currency"
    },
    "request_id": "req_8f3c…",
    "timestamp": "2026-01-15T12:30:00.000Z"
  }
}

O status HTTP mapeia diretamente para o type do erro:

Ramifique em error.code (uma string estável), não em error.message (legível por humanos e sujeita a mudanças). Consulte Erros para o catálogo completo.

const body = await res.json();

if (!res.ok) {
  // body.error.type, body.error.code, body.error.message
  throw new Error(`[${body.error.code}] ${body.error.message}`);
}

return body.data;

IDs de recursos

Todo recurso da Tokeflow possui um ID estável e opaco com um prefixo de tipo. O prefixo informa o tipo do recurso num relance — trate o restante como uma string opaca e nunca o interprete.

Formatos de dados

A Tokeflow padroniza formatos para que seus dados sejam inequívocos entre provedores e regiões.

Valores monetários

Os valores são inteiros nas unidades menores da moeda (por exemplo, centavos). Nunca envie um decimal.

Sempre pareie um valor com seu código currency ISO 4217 (por exemplo "BRL", "USD"). Um valor sem uma moeda é ambíguo e é rejeitado.

País, moeda e datas

Idempotência

Mutações de criação e cobrança são idempotentes. Envie um cabeçalho Idempotency-Key único (ou um campo idempotency_key no corpo) e a Tokeflow garante que a operação seja executada no máximo uma vez.

curl -X POST https://api.tokeflow.com/api/v1/transactions \
  -H "Authorization: Bearer sk_live_mer_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 4f1c2a9e-7b3d-4d2a-9f10-2e5a8c1b6d44" \
  -d '{ "amount": 15000, "currency": "BRL", "payment_method": "pix" }'

Repetir a mesma chave retorna o resultado original — HTTP 200 em uma repetição versus HTTP 201 na primeira criação — em vez de criar uma duplicata. Gere uma nova chave (como um UUID) por operação lógica e reutilize-a ao tentar novamente após uma falha de rede.

Consulte Idempotência para a semântica completa.

Limites de taxa

As requisições são limitadas por taxa por chave de API e por endpoint, em janelas de 60 segundos. Rotas de pagamento e de leitura permitem 600 requisições por minuto por padrão; rotas sem classe permitem 100. Exceder um limite retorna HTTP 429 com um rate_limit_error e um cabeçalho Retry-After.

Trate 429 com backoff exponencial e jitter, e distribua operações em massa ao longo do tempo em vez de dispará-las em rajada. Consulte Limites de taxa para detalhes.

Paginação e filtragem

Os endpoints de listagem são paginados com dois parâmetros de query:

A resposta carrega o estado da página em meta.pagination:

curl "https://api.tokeflow.com/api/v1/customers?page=2&limit=50" \
  -H "Authorization: Bearer sk_live_mer_…"

A maioria dos endpoints de listagem também aceita filtros específicos do recurso (por exemplo status, intervalo de datas, moeda). Cada página de endpoint documenta seus próprios filtros. Consulte Paginação e filtragem para as convenções compartilhadas.

Como uma requisição flui

A Tokeflow autentica a chave, aplica suas regras de roteamento (incluindo resiliência e fallback), encaminha para o provedor selecionado e normaliza a resposta do provedor no envelope padrão. Seu cliente sempre vê o mesmo formato.

Grupos de recursos

Todo endpoint abaixo aceita uma chave de Organization ou de Merchant. Com uma chave de Organization, adicione merchant_id onde o endpoint tem escopo de Merchant (conforme observado em cada página).

Catálogo num relance

O catálogo modela o que você vende e como é precificado.

Próximos passos

• Autenticação — provisione chaves e entenda os escopos.
• Erros — o catálogo completo de erros e códigos.
• Idempotência e Limites de taxa — repetições seguras em escala.
• Webhooks — receba e verifique eventos assinados.