O minimo que uma venda precisa carregar
Uma integracao util envia identificador externo, loja, data e hora, valor, modalidade, parcelas, bandeira quando disponivel, NSU ou TID quando conhecido e referencias que permitam localizar o pedido no ERP. O objetivo nao e enviar o maximo de campos possivel. E enviar contexto suficiente para que uma venda possa ser comparada com o extrato da adquirente e com o recebimento esperado.
O contrato da mensagem
Antes de desenvolver, o time do ERP deve combinar o significado de cada campo. Valor bruto nao e valor liquido. Data da venda nao e data de liquidacao. Uma parcela nao e o mesmo que uma ordem inteira. Campos opcionais precisam indicar quando nao estao disponiveis, sem preencher um identificador inventado.
Um evento normalmente precisa carregar:
- referencia externa estavel do pedido ou documento;
- identificacao da loja pelo cadastro autorizado da integracao;
- data e hora, fuso, valor bruto, modalidade e quantidade de parcelas;
- bandeira, NSU, TID, codigo de autorizacao ou end-to-end ID quando existirem;
- status da venda, cancelamento, estorno ou ajuste;
- uma chave idempotente que possa ser reenviada sem duplicar o evento.
Idempotencia e seguranca
O parceiro deve usar uma chave idempotente por evento e nunca enviar tenant_id escolhido pelo navegador. A organizacao e a loja precisam ser resolvidas pelo contexto autorizado da integracao. Se o mesmo lote for reenviado depois de um timeout, a plataforma deve reconhecer a chave e informar que o registro ja foi aceito, duplicado ou rejeitado com motivo.
Credenciais, segredos e tokens nao devem aparecer no corpo de uma venda, em URL, em planilhas ou em logs. O integrador deve receber apenas os escopos necessarios. A API tambem precisa limitar tamanho de lote, quantidade de requisicoes e periodo consultado. Esse cuidado reduz consumo acidental e dificulta abuso de fluxos sensiveis.
Exemplo de uma venda
Imagine a venda ERP-2026-000145, da loja cadastrada no contrato da integracao, no valor bruto de R$ 500,00, em cartao de credito com duas parcelas. O ERP pode informar NSU e bandeira, se ja tiver esses dados. Se o PDV ainda nao recebeu o NSU, deve enviar a referencia externa e o status conhecido. A adquirente e o banco podem completar outras informacoes depois; a ausencia de uma chave nao autoriza o integrador a criar um valor falso.
Comece pequeno
Homologue um recorte controlado antes de enviar todo o historico. Compare quantidade de eventos, soma dos valores, duplicidades e rejeicoes. A especificacao OpenAPI ajuda as equipes a compartilhar o contrato de uma API, mas nao substitui testes de autorizacao e de idempotencia. O fluxo de tres vias ajuda a alinhar o que o ERP informa com o que a adquirente e o banco conseguem confirmar.
Comece pequeno
Homologue um recorte controlado antes de enviar todo o historico. O fluxo de tres vias ajuda a alinhar o que o ERP informa com o que a adquirente e o banco conseguem confirmar.