Skip to main content
Três assuntos valem para a API inteira: como as listagens devolvem os dados em páginas, em que ordem os resultados vêm e como evitar que uma falha de rede vire uma cobrança duplicada. Esta página reúne os três, com as diferenças entre rotas que você precisa tratar no código.
Para o negócio: a API da Finvia não tem proteção automática contra requisições repetidas. Se o sistema reenvia uma criação de cobrança depois de uma falha de rede, o cliente pode ser cobrado duas vezes. O procedimento desta página evita isso e deve estar no escopo de qualquer integração.

Paginação

Todas as listagens paginadas da API usam os mesmos dois parâmetros de consulta:
O parâmetro de tamanho é size. A API ignora limit sem dar erro: limit=10 parece funcionar só porque 10 já é o padrão, e limit=50 continua devolvendo 10 itens. O mesmo vale para qualquer parâmetro desconhecido, que é ignorado em silêncio. Confira sempre o nome do filtro na referência da rota.

Formato da resposta em cada listagem

Há dois modelos de resposta paginada e algumas rotas que devolvem a lista inteira, sem paginação. Modelo A: totais na raiz do objeto
Modelo B: totais dentro de meta
No modelo B, o meta.limit da resposta é só o tamanho da página que você pediu em size. Ele não é um parâmetro de consulta.
Para o desenvolvedor: escreva um leitor de paginação que aceite os dois modelos. No modelo A, o total de páginas está em pages. No modelo B, está em meta.totalPages. Rotas que devolvem array não têm página seguinte.

Como percorrer todas as páginas

Node.js
A documentação não informa um valor máximo para size. Comece com valores moderados, como 20 ou 50, e ajuste conforme o tempo de resposta. Em clientes, page ou size menor que 1, ou não numérico, volta ao padrão.

Ordenação

A maior parte das listagens devolve os registros do mais recente para o mais antigo, e essa ordem não pode ser trocada. O parâmetro orderBy só funciona em GET /v1/submerchants. Formato do orderBy em subcontas:
Em subcontas, o orderBy com nomes em camelCase (como legalName,-createdAt) gera erro 500. Use legal_name,-created_at.
Para o desenvolvedor: em cobranças, novos registros entram no início da listagem. Se você percorre muitas páginas enquanto novas cobranças chegam, um item pode aparecer em duas páginas seguidas. Deduplique pelo id ou restrinja a leitura a um período fechado com createdAtStart e createdAtEnd.

Idempotência

Idempotência é a garantia de que repetir uma operação produz o mesmo efeito que executá-la uma vez. Ela importa sempre que a sua aplicação não sabe se uma requisição chegou ao destino, como num timeout ou numa queda de conexão.
O cabeçalho Idempotency-Key não existe hoje na API da Finvia. POST /v1/charges não lê nenhum cabeçalho de idempotência, então cada chamada cria uma cobrança nova. Reenviar a criação depois de um timeout pode gerar uma segunda cobrança para o mesmo pedido; no cartão, isso é cobrança em dobro.

Regra geral

Repita uma requisição só depois de confirmar que a primeira não produziu efeito.

Procedimento depois de um timeout ao criar cobrança

Depois de um timeout, você não tem o id da cobrança. Consultar GET /v1/charges/{id} com o número do seu pedido não resolve: para um id que não existe, a API responde hoje 200 com corpo vazio, sem 404. O caminho é este: O desenho abaixo resume a decisão depois de uma criação de cobrança sem resposta clara. Os passos a seguir detalham cada etapa.
1

Não reenvie o POST de imediato

Se a primeira chamada chegou, um novo POST /v1/charges cria uma segunda cobrança.
2

Mande sempre o identificador do pedido em metadata

Em toda criação, envie o número do seu pedido em metadata, por exemplo {"orderId": "PED-1001"}. É ele que liga a cobrança ao pedido quando o id se perde.
3

Recupere o id pelo webhook charge.created

Cadastre um endpoint de webhook com o evento charge.created. Ele é emitido assim que a cobrança é gravada, antes da resposta do processador, e traz em data o id da cobrança e o metadata com as chaves exatamente como você enviou. É a forma mais confiável de recuperar o id depois de um timeout.
4

Busque na listagem

Se o webhook não chegou, procure a cobrança com a mesma chave usada na criação (a chave de teste lista só cobranças de teste, e a de produção só as de produção):GET /v1/charges?createdAtStart=AAAA-MM-DD&createdAtEnd=AAAA-MM-DD&searchFor=<termo>&size=50Use como termo o documento ou o e-mail do comprador. Depois compare metadata e amount do seu lado.
5

Decida

Encontrou a cobrança: associe o id ao pedido e siga o fluxo. Não encontrou: a cobrança não foi criada e é seguro tentar de novo.
Regras da busca em GET /v1/charges:
Para o desenvolvedor: use um timeout de cliente generoso na criação, por exemplo 60 segundos. O cartão é processado de forma síncrona, e um timeout curto aumenta as chances de você não saber o resultado.
Node.js
Se a tentativa aconteceu perto da meia-noite em UTC, repita a busca com o dia anterior ou o seguinte, porque o filtro de datas usa o fuso do servidor.

Proteções que a própria API oferece

Algumas operações já têm comportamento que evita duplicidade. Use-as a seu favor, sem dispensar a verificação acima.
O reaproveitamento da validação no trial grátis não impede a criação de uma segunda assinatura. Antes de repetir POST /v1/subscriptions depois de um timeout, liste as assinaturas do cliente com GET /v1/subscriptions?customerId=... e confira se a primeira foi criada.

Idempotência no recebimento de webhooks

O mesmo evento pode chegar mais de uma vez. Isso acontece, por exemplo, quando a mesma URL está cadastrada como endpoint e como postbackUrl, ou em novas tentativas de entrega (veja a política de entrega em Webhooks). O seu receptor precisa reconhecer eventos repetidos. A chave de deduplicação de cada formato (envelope padrão, charge.updated, saque e conta) está na receita de deduplicação, com exemplo completo em Node.js e PHP.
Para o desenvolvedor: guarde as chaves processadas em armazenamento persistente (banco ou Redis), não em memória. Um Set em memória se perde a cada reinício do servidor.

Erros comuns

Perguntas frequentes

Não diretamente. GET /v1/charges não filtra por metadata. Guarde o id devolvido na criação junto com o pedido. Para recuperar uma cobrança sem o id, use o webhook charge.created ou a busca por período e searchFor, descritos no procedimento de timeout.
10, em todas as listagens paginadas (cobranças, clientes, planos, assinaturas, subcontas, saques e endpoints de webhook).
Não. Só GET /v1/submerchants aceita orderBy, com nomes em snake_case. Em cobranças ele é ignorado, e em saques gera erro. As demais listagens têm ordem fixa.
Não existe hoje. Use o identificador do pedido em metadata e o procedimento de timeout desta página.
Não. Reentregas fazem parte do funcionamento. Responda com status 2xx também para o evento repetido e apenas não o processe de novo.

Como testar

  • Liste cobranças com page e size e confira a paginação (base do cenário CHG-06 do roteiro de homologação).
  • Use POST /v1/charges/{id}/resend-webhook duas vezes com o mesmo status e confirme que o seu receptor responde 2xx nas duas vezes e não repete o efeito, como liberar o pedido (cenários CHG-08 e CHG-09). Cada simulação gera um evento com id novo, então quem segura a repetição é a checagem do pedido.
  • Simule um timeout no seu código (por exemplo, abortando a requisição antes da resposta) e confira se a rotina encontra a cobrança pelo charge.created ou pela listagem antes de criar outra.

Veja também

Erros e como tratar

Quando repetir e quando corrigir uma requisição.

Listar cobranças

Referência de GET /v1/charges.

Webhooks

Entrega e segurança das notificações.

Catálogo de eventos

Todos os eventos e seus envelopes.