Modele a venda antes de modelar a chamada
Uma integração começa por uma pergunta de negócio: qual pedido essa cobrança representa? Defina uma referência que permita relacionar pedido, cobrança, pagamento e recebimento.
Depois, estabeleça quais eventos mudam o estado da sua operação. A criação de uma cobrança, a confirmação do pagamento e a liquidação não devem ser tratadas como sinônimos.
Repetição precisa ter tratamento
Requisições podem ser repetidas e notificações podem chegar mais de uma vez. O sistema consumidor precisa reconhecer uma ocorrência já tratada antes de repetir seus efeitos.
Idempotência é o conceito de obter o mesmo efeito esperado quando uma operação idêntica é repetida. O uso concreto depende do contrato da API: chave, validade e respostas devem ser confirmadas na documentação de integração aplicável.
Receba eventos com contexto
Valide as notificações de acordo com o mecanismo definido na integração e registre o identificador do evento. Separe o recebimento da mensagem do processamento do pedido para poder investigar falhas.
Não implemente nomes de campos ou endpoints a partir de um desenho de interface. Os eventos mostrados na página institucional são uma leitura ilustrativa do ciclo de cobrança, não um contrato de API para produção.
Teste o caminho que não deu certo
Além do sucesso, ensaie repetição de eventos, falha temporária, cobrança ainda não paga e estado em análise. Confira se o seu sistema consegue mostrar a diferença entre um pagamento confirmado e a etapa de envio à carteira.
Leve esses cenários para a conversa de integração com a Caiu. Um contrato claro sobre estados, autenticidade e retomada vale mais que uma sequência de chamadas que só cobre o caminho feliz.
Tem uma dúvida sobre a sua operação? Fale com a Caiu ou consulte a FAQ.