Reenvio e versões

Esta página é para quem configura as retentativas do ERP. Ela explica por que reenviar o balancete é seguro e como o TOPO trata a correção de uma competência.

Reenviar o mesmo conteúdo não duplica nadaCopiar link da seção

O TOPO compara o conteúdo recebido com a versão vigente do balancete daquela empresa e competência. Se for igual, ele não grava nada e responde 200 com reenvio: true e o id da versão que já existe.

Exemplo real, com a empresa de CNPJ 12.345.678/0001-90 e a competência 2026-08:

Por isso a retentativa do SAP ou de um script é segura: se a primeira chamada entrou e a resposta se perdeu no caminho, a segunda só confirma. Trate 200 e 201 como sucesso.

Não é preciso mandar nenhum cabeçalho especial. A comparação é pelo conteúdo:

• na importação em JSON, pelas linhas, pela empresa e pela competência;
• na importação por arquivo, pelo arquivo e pelo mapeamento de colunas salvo para a empresa. O mesmo arquivo lido com outro mapeamento conta como balancete novo.

Conteúdo diferente cria uma versão novaCopiar link da seção

Se o ERP mandar a mesma competência com outro conteúdo, por exemplo depois de um lançamento de ajuste, o TOPO grava uma versão nova do balancete e responde 201. A resposta traz avisos dizendo o que mudou:

{
  "success": true,
  "data": {
    "trialBalanceId": 319,
    "reenvio": false,
    "enviadas": 1,
    "importadas": 1,
    "avisos": [
      "Conta 1101.000 (Caixa 1) teve saldo alterado. Débito: 250 → 300. Saldo final: 1150 → 1200. Conciliação pode precisar ser reaberta.",
      "Conta 1102.001 (Bancos 2) foi removida nesta reimportação. Esta conta existia no balancete original mas não está mais presente."
    ]
  }
}

A lista de balancetes (GET /api/v1/trial-balances) mostra a versão vigente, com o número da versão em versao.

Mande sempre o balancete inteiro da competência. Uma conta que ficar de fora do reenvio é tratada como removida, como mostra o segundo aviso acima.

Competência encerradaCopiar link da seção

Se o cliente já fechou a competência no TOPO, o envio responde 409 com code: COMPETENCE_CLOSED, e nada muda. Se a competência fechada é a seguinte, o código é NEXT_COMPETENCE_CLOSED, porque a importação mudaria as conciliações dela. Para corrigir, um administrador do módulo reabre o período no TOPO, com justificativa, e o ERP envia de novo.

Boa prática nas retentativasCopiar link da seção

1. Espere a resposta de uma chamada antes de mandar a mesma de novo. Duas chamadas iguais ao mesmo tempo podem chegar antes de a primeira gravar.
2. Repita só em 429 e 5xx, ou quando a conexão cair sem resposta.
3. Não repita 400, 403, 404 e 409 sem corrigir a causa. Veja erros e códigos.