---
updatedAt: 2026-09-01T13:50:42.000Z
agentTools:
  projectIndex: https://docs.asaas.com/llms.txt
---

# 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

```mermaid
%%{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
```

<br />

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

```mermaid
%%{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
```

<br />

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

<br />

### 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.**

<br />

# Sibling pages

* [Webhook recebido, mas não persistido](https://docs.asaas.com/docs/webhook-recebido-mas-não-persistido.md)
* [Webhook com timeout ou resposta demorada](https://docs.asaas.com/docs/webhook-não-processado-dentro-do-tempo-esperado.md)
* [API Key usada no ambiente errado](https://docs.asaas.com/docs/api-key-de-sandbox-usada-em-produção.md)
* [Sistema dependente apenas da resposta síncrona](https://docs.asaas.com/docs/sistema-dependente-apenas-da-resposta-síncrona.md)
* [Cobrança duplicada após retry sem idempotência](https://docs.asaas.com/docs/cobrança-duplicada-após-retry-sem-idempotência.md)
* [Status local divergente do Asaas](https://docs.asaas.com/docs/status-local-divergente-do-asaas.md)
* [Requisições bloqueadas por ausência de controle de limites](https://docs.asaas.com/docs/requisições-bloqueadas-por-ausência-de-controle-de-limites.md)
* [Listagem incompleta por ausência de paginação](https://docs.asaas.com/docs/listagem-incompleta-por-ausência-de-paginação.md)
* [Webhook duplicado processado sem idempotência](https://docs.asaas.com/docs/webhook-duplicado-processado-sem-idempotência.md)