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: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 objetometa
meta.limit da resposta é só o tamanho da página que você pediu em size. Ele não é um parâmetro de consulta.
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âmetroorderBy só funciona em GET /v1/submerchants.
Formato do
orderBy em subcontas:
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.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 oid 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.GET /v1/charges:
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.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 comopostbackUrl, 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.
Erros comuns
Perguntas frequentes
Posso buscar uma cobrança pelo número do meu pedido?
Posso buscar uma cobrança pelo número do meu pedido?
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.Qual é o tamanho padrão da página?
Qual é o tamanho padrão da página?
10, em todas as listagens paginadas (cobranças, clientes, planos, assinaturas, subcontas, saques e endpoints de webhook).Todas as listagens aceitam orderBy?
Todas as listagens aceitam orderBy?
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.Existe Idempotency-Key?
Existe Idempotency-Key?
Não existe hoje. Use o identificador do pedido em
metadata e o procedimento de timeout desta página.Se o webhook chegar duas vezes, a Finvia considera erro?
Se o webhook chegar duas vezes, a Finvia considera erro?
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
pageesizee confira a paginação (base do cenário CHG-06 do roteiro de homologação). - Use
POST /v1/charges/{id}/resend-webhookduas vezes com o mesmo status e confirme que o seu receptor responde2xxnas 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 comidnovo, 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.createdou 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.

