> ## Documentation Index
> Fetch the complete documentation index at: https://strattumai.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Asaas

> Configure o conector Asaas para sincronizar clientes, cobranças, assinaturas e transferências do gateway de pagamentos com a plataforma strattum.ai.

O conector Asaas extrai dados do gateway de pagamentos Asaas e os sincroniza com a infraestrutura strattum.ai. Clientes, cobranças, assinaturas e transferências entram no Data Catalog e alimentam o grafo de entidades do Memory, unificando o histórico financeiro de cada cliente.

## Capacidades

* Sincronizar clientes, cobranças (boleto, PIX, cartão), assinaturas e transferências.
* Ingestão incremental de cobranças pela data de criação.
* Ambientes de produção e sandbox, selecionáveis na configuração.
* Unificação com CRM e suporte: clientes do Asaas compartilham email e CPF/CNPJ com contatos de HubSpot e Zendesk, formando um perfil Customer 360.

## Objetos suportados

| Objeto         | Recurso         | Modo de sync                  |
| -------------- | --------------- | ----------------------------- |
| Clientes       | `customers`     | Full refresh                  |
| Cobranças      | `payments`      | Incremental por `dateCreated` |
| Assinaturas    | `subscriptions` | Full refresh                  |
| Transferências | `transfers`     | Full refresh                  |

## Pré-requisitos

* [ ] Conta Asaas ativa (produção ou sandbox).
* [ ] Chave de API do Asaas com permissão de leitura.
* [ ] Acesso de administrador ao workspace strattum.ai.

<Tip>
  Gere a chave de API no painel do Asaas em **Configurações → Integrações → API**. Use uma chave de leitura dedicada à integração.
</Tip>

## Configuração

<Steps>
  <Step title="Acesse Connections no Console">
    No Console strattum.ai, clique em **Connections** e depois em **Nova Conexão**. Selecione **Asaas**.
  </Step>

  <Step title="Preencha as credenciais">
    * **API Key** — Obrigatório. A chave de API da sua conta Asaas.
    * **Environment** — Obrigatório. `production` ou `sandbox`. Define a URL base (`api.asaas.com` ou `sandbox.asaas.com`).
  </Step>

  <Step title="Selecione os objetos">
    Escolha entre `customers`, `payments`, `subscriptions` e `transfers`. Para o perfil financeiro do cliente no Memory, `customers` e `payments` são o mínimo.
  </Step>

  <Step title="Teste e ative">
    Clique em **Testar Conexão** para validar a chave antes de salvar. Após salvar, o conector inicia a primeira sincronização automaticamente.
  </Step>
</Steps>

## Autenticação e escopos

| Item              | Valor                                                                                      |
| ----------------- | ------------------------------------------------------------------------------------------ |
| Método            | Chave de API (header `access_token`)                                                       |
| Campo obrigatório | `api_key`                                                                                  |
| Ambiente          | `production` → `https://api.asaas.com/v3` · `sandbox` → `https://sandbox.asaas.com/api/v3` |
| Permissão         | Leitura de clientes, cobranças, assinaturas e transferências                               |

<Warning>
  A chave de API do Asaas dá acesso à conta financeira. Use uma chave com o menor escopo possível e nunca a exponha em código ou logs. A plataforma guarda a chave no secrets manager da instalação.
</Warning>

## Frequência de sync

A frequência é escolhida por conector na tela de configuração: 15 minutos, horário, 6 horas, diário, semanal ou cron. Para conciliação financeira, horário ou 6 horas costuma ser suficiente. Ver [Frequência de sync](/data-pipelines/sync-frequency).

## Limitações conhecidas

* O conector ingere `customers`, `payments`, `subscriptions` e `transfers`. Outros objetos do Asaas (notas fiscais, splits, antecipações): \[verificar].
* Apenas `payments` é incremental (por `dateCreated`). Clientes, assinaturas e transferências são recarregados por full refresh a cada ciclo.
* A API do Asaas tem limite de requisições por período. Volumes altos com frequência agressiva podem esbarrar no rate limit. \[verificar]

## Troubleshooting

<AccordionGroup>
  <Accordion title="Teste de conexão falha com 401">
    A chave de API está incorreta ou é de outro ambiente. Confirme que a chave corresponde ao **Environment** selecionado (uma chave de sandbox não autentica em produção).
  </Accordion>

  <Accordion title="Cobranças novas não aparecem">
    `payments` é incremental por `dateCreated`. Cobranças com data anterior ao último watermark não voltam. Verifique o horário do último sync no card do conector.
  </Accordion>

  <Accordion title="Sync lento na primeira carga">
    A primeira carga percorre todo o histórico com paginação de 100 registros por página. Contas com muitas cobranças levam mais tempo. Acompanhe o progresso em **Observability → Pipelines**.
  </Accordion>
</AccordionGroup>

Para ver o erro específico de um sync, abra o card do conector, clique em `···` e selecione **Ver logs**.

## Próximos passos

<CardGroup cols={2}>
  <Card title="Memory" icon="brain" href="/memory/overview">
    Como as cobranças e clientes viram um perfil financeiro unificado no grafo de entidades.
  </Card>

  <Card title="Catálogo de conectores" icon="plug" href="/connectors/overview">
    Veja todos os conectores disponíveis na plataforma.
  </Card>
</CardGroup>