Entity created without a link to the internal record

This error occurs when the integration creates an entity in Asaas without maintaining a stable relationship between the internal record and the ID returned by the API.

Without this correlation, locating, reconciling, auditing, or reprocessing an operation ends up depending on information such as amount, date, or customer data, which can repeat.

How to identify

• the ID returned by Asaas is not stored;
• there is no unique internal identifier for the operation;
• externalReference is not used when applicable;
• searching depends on CPF, amount, date, or due date;
• there are similar records that cannot be safely told apart;
• the link between the order and the entity was lost after a migration or reprocessing.

How to fix

1. Define a unique and stable internal identifier for each operation.
2. Locate and store the ID returned by Asaas.
3. Link both identifiers in the internal record.
4. Fill in externalReference when applicable.
5. Update queries and logs to use the identifiers.
6. Review existing operations that have no link.
7. Re-establish the correlation using the available responses, logs, and history.
8. Ensure the link is kept during retries, migrations, and reprocessing.

Recommended flow: generate the internal ID → create the entity → store the Asaas ID → link the identifiers → track the operation.

Diagnostic flow

1. Diagnosing and recovering the link

%%{init: {"flowchart": {"nodeSpacing": 18,"rankSpacing": 24,"diagramPadding": 4,"padding": 7
}}}%%
flowchart TD
    A["The operation cannot be located reliably"] --> B{"Is there a unique internal identifier?"}

    B --> BSim(("Yes"))
    B --> BNao(("No"))

    BNao --> C["Define a stable internal identifier"]
    C --> E{"Was the ID returned by Asaas stored?"}

    BSim --> E

    E --> ESim(("Yes"))
    E --> ENao(("No"))
    E --> EDuvida(("Not sure"))

    ENao --> F["Check responses, logs, and operation data"]
    EDuvida --> G["Review the creation history"]
    G --> F

    ESim --> H{"Are the identifiers linked?"}
    F --> H

    H --> HSim(("Yes"))
    H --> HNao(("No"))

    HNao --> I["Link the internal ID to the Asaas ID"]
    HSim --> J["Validate lookup by the identifiers"]
    I --> J

    J --> K["Update records, queries, and reconciliation"]

    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. Identifying new operations

%%{init: {"flowchart": {"nodeSpacing": 18,"rankSpacing": 24,"diagramPadding": 4,"padding": 7
}}}%%
flowchart TD
    A["Before creating a new entity"] --> B{"Is there a unique internal identifier?"}

    B --> BSim(("Yes"))
    B --> BNao(("No"))

    BNao --> C["Generate a unique and stable identifier"]

    BSim --> D{"Will externalReference be used when applicable?"}
    C --> D

    D --> DSim(("Yes"))
    D --> DNao(("No"))
    D --> DDuvida(("Not sure"))

    DNao --> E["Define the correlation strategy"]
    DDuvida --> F["Check the fields accepted by the endpoint"]
    F --> E

    DSim --> G["Send the identifier on creation"]
    E --> G

    G --> H{"Was the ID returned by Asaas stored?"}

    H --> HSim(("Yes"))
    H --> HNao(("No"))

    HNao --> I["Save the ID and link it to the internal record"]
    HSim --> J{"Do the IDs appear in logs and reconciliation?"}
    I --> J

    J --> JSim(("Yes"))
    J --> JNao(("No"))

    JNao --> K["Update logs, queries, and routines"]
    JSim --> L["Track the operation with traceability"]
    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

The first flow explains how to recover the link for existing operations, while the second shows how to ensure traceability for new entities.

How to prevent

Define the identification strategy before implementation. Use a unique and stable internal identifier, store the ID returned by Asaas, and include both identifiers in logs, queries, retries, and reconciliation processes.

externalReference helps with correlation when available, but it does not replace storing the ID returned by Asaas.

Each operation must be linked to its internal identifier and to the ID returned by Asaas.