Idempotência

Como a API evita duplicidade — externalId, batchCode, número do processo e a regra de telefone + agente.

Rede falha, timeout acontece e retry é inevitável. A API externa foi desenhada para que repetir uma chamada não crie registros duplicados — desde que você envie a chave de idempotência correta.

Não existe um header Idempotency-Key genérico: cada recurso tem sua própria chave, sempre no corpo da requisição.

Chaves por recurso

Recurso	Chave	Escopo	Comportamento na repetição
Lote de notificações	`batchCode`	Empresa	Devolve o lote existente com `200`
Item de lote de notificações	`externalId`	Empresa	O item já criado é reaproveitado
Lote de negociações	`batchCode`	Empresa	Devolve o lote existente com `200`
Item de lote de negociações	`externalId`	Empresa	O item já criado é reaproveitado
Negociação individual	telefone + agente	Empresa	Devolve o caso ativo existente com `200`
Processo judicial	`numero`	Empresa	Devolve o processo existente com `idempotent: true`

200 significa reaproveitado

Nos endpoints de criação, 201 indica recurso novo e 200 indica que a API reconheceu a chave e devolveu o registro que já existia. Trate os dois como sucesso.

Lotes: `batchCode`

Envie um código estável e único por lote. Se o mesmo batchCode chegar novamente, o lote existente é devolvido em vez de um novo ser criado.

Body

{
  "batchCode": "cobranca-2026-08-lote-01",
  "deliveryMethod": "DIGITAL",
  "items": []
}

Isso também permite enviar um lote grande em partes: mantenha o mesmo batchCode em chamadas sucessivas e os itens vão sendo agregados ao mesmo lote, respeitando o teto de 1000 itens por chamada.

Como escolher o batchCode

Use algo derivado do seu próprio sistema e que não mude em um retry — o id da campanha, o id da remessa, uma combinação de data e cliente. Evite timestamps gerados na hora do envio: eles mudam a cada tentativa e derrotam a idempotência.

Itens: `externalId`

Dentro de um lote, cada item carrega um externalId próprio — normalmente o identificador do contrato, do título ou do registro no seu sistema.

Item

{
  "externalId": "contrato-8842",
  "amount": 1500.75,
  "contact": {
    "name": "Maria Souza",
    "taxId": "12345678900",
    "phoneNumbers": ["+5511999999999"]
  }
}

A resposta devolve o resultado item a item, sempre ecoando o externalId que você enviou — é assim que você reconcilia com a sua base:

Resultado por item

{
  "externalId": "contrato-8842",
  "itemId": "7c1d2e3f-4a5b-6c7d-8e9f-0a1b2c3d4e5f",
  "status": "VALIDATED"
}

Negociação individual: telefone + agente

A criação de negociação avulsa não usa externalId como chave. A regra é: se já existe uma negociação ativa para o mesmo telefone com o mesmo agente na empresa, o caso existente é devolvido com 200.

200 OK — caso existente

{
  "success": true,
  "data": {
    "negociacaoId": "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
    "status": "ACTIVE"
  },
  "message": "Negotiation created successfully."
}

Isso evita que o mesmo devedor receba duas abordagens simultâneas do mesmo agente. O campo externalId na criação individual existe apenas como referência sua, para rastreio — ele não altera a regra de idempotência.

Como distinguir criação de reaproveitamento

Olhe o status: STARTED ou SCHEDULED indicam negociação recém-criada (201). Qualquer outro valor com 200 indica que um caso ativo já existia.

Processos: número do processo

Na ingestão de processos, o numero é a chave. Se o processo já existir na empresa, ele é reaproveitado e a resposta traz idempotent: true:

201 Created — processo reaproveitado

{
  "success": true,
  "data": {
    "processoId": "9f8e7d6c-5b4a-4928-9706-f5e4d3c2b1a0",
    "numeroProcesso": "0001234-56.2026.8.26.0100",
    "partesCount": 3,
    "idempotent": true
  },
  "message": "Processo ingerido com sucesso."
}

Retry seguro

Regra prática para a sua camada de retry:

Situação	Repetir?
Timeout de rede sem resposta	Sim — com a mesma chave de idempotência
`429 RATE_LIMIT_EXCEEDED`	Sim — com backoff (ver Limite de requisições)
`503 SERVICE_UNAVAILABLE`	Sim — com backoff
`5xx` genérico	Sim — com backoff, no máximo 3 tentativas
`400` / `422` (validação)	Não — corrija o payload
`401` / `403`	Não — corrija a credencial
`404`	Não — o recurso não existe nesse workspace

Nunca repita sem chave de idempotência

Um retry de criação de lote sem batchCode cria um lote novo — e potencialmente dispara notificações duplicadas para os mesmos destinatários. Defina a chave sempre, mesmo quando ela é opcional no schema.