Entidade criada sem vínculo com o registro interno

Esse erro ocorre quando a integração cria uma entidade no Asaas sem manter uma relação estável entre o registro interno e o ID retornado pela API.

Sem essa correlação, localizar, conciliar, auditar ou reprocessar uma operação passa a depender de informações como valor, data ou dados do cliente, que podem se repetir.

Como identificar

• o ID retornado pelo Asaas não é armazenado;
• não existe um identificador interno único para a operação;
• o externalReference não é utilizado quando aplicável;
• a busca depende de CPF, valor, data ou vencimento;
• existem registros semelhantes que não podem ser diferenciados com segurança;
• o vínculo entre o pedido e a entidade foi perdido após migração ou reprocessamento.

Como corrigir

1. Defina um identificador interno único e estável para cada operação.
2. Localize e armazene o ID retornado pelo Asaas.
3. Relacione os dois identificadores no registro interno.
4. Preencha o externalReference quando aplicável.
5. Atualize consultas e logs para utilizarem os identificadores.
6. Revise as operações existentes sem vínculo.
7. Reestabeleça a correlação utilizando respostas, logs e históricos disponíveis.
8. Garanta que o vínculo seja mantido durante retries, migrações e reprocessamentos.

Fluxo recomendado: gerar o ID interno → criar a entidade → armazenar o ID do Asaas → relacionar os identificadores → acompanhar a operação.

Fluxo de diagnóstico

1. Diagnóstico e recuperação do vínculo

%%{init: {"flowchart": {"nodeSpacing": 18,"rankSpacing": 24,"diagramPadding": 4,"padding": 7
}}}%%
flowchart TD
    A["A operação não pode ser localizada com segurança"] --> B{"Existe identificador interno único?"}

    B --> BSim(("Sim"))
    B --> BNao(("Não"))

    BNao --> C["Definir um identificador interno estável"]
    C --> E{"O ID retornado pelo Asaas foi armazenado?"}

    BSim --> E

    E --> ESim(("Sim"))
    E --> ENao(("Não"))
    E --> EDuvida(("Não sabe"))

    ENao --> F["Consultar respostas, logs e dados da operação"]
    EDuvida --> G["Revisar o histórico da criação"]
    G --> F

    ESim --> H{"Os identificadores estão relacionados?"}
    F --> H

    H --> HSim(("Sim"))
    H --> HNao(("Não"))

    HNao --> I["Relacionar o ID interno ao ID do Asaas"]
    HSim --> J["Validar a localização pelos identificadores"]
    I --> J

    J --> K["Atualizar registros, consultas e conciliação"]

    classDef inicio fill:#DBEAFE,stroke:#2563EB,color:#1E3A8A,stroke-width:3px
    classDef decisao fill:#FEF3C7,stroke:#D97706,color:#78350F,stroke-width:3px
    classDef correcao fill:#FFEDD5,stroke:#EA580C,color:#7C2D12,stroke-width:2px
    classDef validacao fill:#E0F2FE,stroke:#0284C7,color:#0C4A6E,stroke-width:2px
    classDef sucesso fill:#DCFCE7,stroke:#16A34A,color:#14532D,stroke-width:3px
    classDef analise fill:#FEE2E2,stroke:#DC2626,color:#7F1D1D,stroke-width:3px

    classDef respostaSim fill:#22C55E,stroke:#15803D,color:#FFFFFF,stroke-width:3px
    classDef respostaNao fill:#EF4444,stroke:#B91C1C,color:#FFFFFF,stroke-width:3px
    classDef respostaDuvida fill:#8B5CF6,stroke:#6D28D9,color:#FFFFFF,stroke-width:3px

    class A inicio
    class B,E,H decisao
    class C,I correcao
    class J validacao
    class K sucesso
    class F,G analise

    class BSim,ESim,HSim respostaSim
    class BNao,ENao,HNao respostaNao
    class EDuvida respostaDuvida

    linkStyle default stroke:#94A3B8,stroke-width:2px

    linkStyle 1,6,14 stroke:#22C55E,stroke-width:4px
    linkStyle 2,7,15 stroke:#EF4444,stroke-width:4px
    linkStyle 8 stroke:#8B5CF6,stroke-width:4px

2. Identificação de novas operações

%%{init: {"flowchart": {"nodeSpacing": 18,"rankSpacing": 24,"diagramPadding": 4,"padding": 7
}}}%%
flowchart TD
    A["Antes de criar uma nova entidade"] --> B{"Existe identificador interno único?"}

    B --> BSim(("Sim"))
    B --> BNao(("Não"))

    BNao --> C["Gerar um identificador único e estável"]

    BSim --> D{"O externalReference será usado quando aplicável?"}
    C --> D

    D --> DSim(("Sim"))
    D --> DNao(("Não"))
    D --> DDuvida(("Não sabe"))

    DNao --> E["Definir a estratégia de correlação"]
    DDuvida --> F["Verificar os campos aceitos pelo endpoint"]
    F --> E

    DSim --> G["Enviar o identificador na criação"]
    E --> G

    G --> H{"O ID retornado pelo Asaas foi armazenado?"}

    H --> HSim(("Sim"))
    H --> HNao(("Não"))

    HNao --> I["Salvar o ID e vinculá-lo ao registro interno"]
    HSim --> J{"Os IDs aparecem nos logs e na conciliação?"}
    I --> J

    J --> JSim(("Sim"))
    J --> JNao(("Não"))

    JNao --> K["Atualizar logs, consultas e rotinas"]
    JSim --> L["Acompanhar a operação com rastreabilidade"]
    K --> L

    classDef inicio fill:#DBEAFE,stroke:#2563EB,color:#1E3A8A,stroke-width:3px
    classDef decisao fill:#FEF3C7,stroke:#D97706,color:#78350F,stroke-width:3px
    classDef correcao fill:#FFEDD5,stroke:#EA580C,color:#7C2D12,stroke-width:2px
    classDef validacao fill:#E0F2FE,stroke:#0284C7,color:#0C4A6E,stroke-width:2px
    classDef sucesso fill:#DCFCE7,stroke:#16A34A,color:#14532D,stroke-width:3px
    classDef analise fill:#FEE2E2,stroke:#DC2626,color:#7F1D1D,stroke-width:3px

    classDef respostaSim fill:#22C55E,stroke:#15803D,color:#FFFFFF,stroke-width:3px
    classDef respostaNao fill:#EF4444,stroke:#B91C1C,color:#FFFFFF,stroke-width:3px
    classDef respostaDuvida fill:#8B5CF6,stroke:#6D28D9,color:#FFFFFF,stroke-width:3px

    class A inicio
    class B,D,H,J decisao
    class C,E,G,I,K correcao
    class F validacao
    class L sucesso

    class BSim,DSim,HSim,JSim respostaSim
    class BNao,DNao,HNao,JNao respostaNao
    class DDuvida respostaDuvida

    linkStyle default stroke:#94A3B8,stroke-width:2px

    linkStyle 1,6,15,20 stroke:#22C55E,stroke-width:4px
    linkStyle 2,7,16,21 stroke:#EF4444,stroke-width:4px
    linkStyle 8 stroke:#8B5CF6,stroke-width:4px

O primeiro fluxo orienta como recuperar o vínculo de operações existentes, enquanto o segundo mostra como garantir a rastreabilidade das novas entidades.

Como prevenir

Defina a estratégia de identificação antes da implementação. Utilize um identificador interno único e estável, armazene o ID retornado pelo Asaas e inclua os dois identificadores em logs, consultas, retries e processos de conciliação.

O externalReference ajuda na correlação quando disponível, mas não substitui o armazenamento do ID retornado pelo Asaas.

Cada operação deve estar vinculada ao seu identificador interno e ao ID retornado pelo Asaas.