Idempotência
Como usar externalContractId e externalDocumentId para evitar duplicidade em criações.
Por que idempotência importa
Em cenários de rede instável ou retry automático, uma mesma requisição de criação pode ser enviada mais de uma vez. Para evitar que isso resulte em operações ou documentos duplicados, a API LaaS usa identificadores fornecidos pelo próprio parceiro como chave de idempotência.
Operações de crédito
Ao criar uma operação (POST /credit-operations), o campo externalContractId do CreateCreditOperationRequest é o identificador único do contrato no sistema do parceiro, e funciona como chave de idempotência: reenviar a mesma chamada com o mesmo externalContractId não cria uma segunda operação.
Esse mesmo valor é usado depois para referenciar a operação em todas as demais chamadas (GET, approve, ccb, ccb/sign, disbursement, cancel, kyc) — ele substitui o id interno (UUID) da entidade nas rotas da API.
Documentos
Ao enviar um documento (POST /credit-operations/{externalContractId}/documents), o campo externalDocumentId do BorrowerDocument cumpre o mesmo papel: identifica o documento no sistema do parceiro e evita reenvio duplicado do mesmo arquivo.
Recomendação
Gere o externalContractId e o externalDocumentId a partir de identificadores já existentes no seu sistema (ex: o ID do contrato ou do documento no seu banco de dados), garantindo que sejam únicos e estáveis por operação/documento — nunca gerados aleatoriamente a cada tentativa de chamada.
Updated 19 days ago