> ## Documentation Index
> Fetch the complete documentation index at: https://docs.strattum.ai/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.

## Configuração

**1. Acesse Connections no Console**

No Console strattum.ai, clique em **Connections** e depois em **Nova Conexão**. Selecione **Asaas**.

**2. 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`).

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

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

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

## 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](https://docs.strattum.ai/data-pipelines/sync-frequency.md).

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

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

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

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

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

## Próximos passos

> **[Memory](https://docs.strattum.ai/memory/overview.md)**
>
> Como as cobranças e clientes viram um perfil financeiro unificado no grafo de entidades.

> **[Catálogo de conectores](https://docs.strattum.ai/connectors/overview.md)**
>
> Veja todos os conectores disponíveis na plataforma.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.