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

# Exportação de dados

> Exporte as conversas, mensagens, contatos e deals do seu workspace na Morada.ai de forma incremental.

## O que é a API de Exportação de Dados

A API de Exportação de Dados permite que você extraia os dados do seu **workspace** na Morada.ai — conversas, mensagens, contatos e deals — para o seu próprio data warehouse, banco de dados ou ferramenta de análise.

Você controla quando e o que exportar. Faça uma carga completa pontual para popular um destino do zero, ou pulls incrementais periódicos para trazer apenas o que mudou desde a última sincronização.

<Info>
  A API expõe somente os dados do seu próprio workspace. Cada linha retornada inclui o campo `workspace_id`, e a chave de acesso limita a exportação ao workspace correspondente.
</Info>

## Autenticação

A API usa uma **workspace API key** no formato `mk_...`, enviada no header `Authorization` como bearer token. A base URL é `https://data-api.morada.ai`.

```bash theme={null}
curl -H "Authorization: Bearer mk_sua_chave_aqui" \
  "https://data-api.morada.ai/v1/export/contacts?limit=100"
```

Para confirmar a qual workspace a sua chave dá acesso, use o endpoint `GET /v1/whoami`.

<Info>
  Você gera a sua workspace API key na própria plataforma, em **Integrações → Configurar API**.
</Info>

<Warning>
  A chave concede acesso de leitura a todos os dados do seu workspace. Trate-a como um segredo: armazene em um cofre de credenciais e nunca a exponha em código cliente ou repositórios públicos.
</Warning>

## Entidades disponíveis

A exportação é feita por entidade, cada uma no seu próprio endpoint:

* [Exportar conversas](/api-reference/export/exportar-conversas) — `GET /v1/export/conversations`
* [Exportar mensagens](/api-reference/export/exportar-mensagens) — `GET /v1/export/messages`
* [Exportar contatos](/api-reference/export/exportar-contatos) — `GET /v1/export/contacts`
* [Exportar deals](/api-reference/export/exportar-deals) — `GET /v1/export/deals`

Todas as linhas, de qualquer entidade, incluem estes campos:

| Campo          | Descrição                                                           |
| -------------- | ------------------------------------------------------------------- |
| `id`           | Identificador único da linha dentro da entidade                     |
| `workspace_id` | Workspace ao qual a linha pertence                                  |
| `cursor_at`    | Momento (ISO 8601) usado como marca-d'água de ordenação e paginação |

Os campos específicos de cada entidade estão detalhados na seção **Response** da referência de cada endpoint acima.

## Exportação incremental e pontual

O endpoint responde sempre com o mesmo envelope:

```json theme={null}
{
  "data": [ { "id": "...", "workspace_id": "...", "cursor_at": "2026-07-20T14:03:00.000Z" } ],
  "next_cursor": "eyJjdXJzb3JfYXQiOiIyMDI2LTA3LTIw...",
  "count": 1
}
```

O comportamento depende do parâmetro `updated_since`:

| Modo               | Como chamar                    | Resultado                                              |
| ------------------ | ------------------------------ | ------------------------------------------------------ |
| Pontual (completo) | Sem `updated_since`            | Retorna tudo que existe na entidade                    |
| Incremental        | Com `updated_since=<ISO 8601>` | Retorna apenas o que mudou desde o timestamp informado |

<Steps>
  <Step title="Faça a primeira chamada">
    Chame o endpoint da entidade (ex.: `GET /v1/export/conversations`). Sem `updated_since` para uma carga completa, ou com `updated_since` para trazer só as mudanças recentes.
  </Step>

  <Step title="Processe a página">
    Grave as linhas de `data` no seu destino. **Faça upsert por `id`**: uma mesma linha pode reaparecer entre pulls (semântica CDC), então atualize a linha existente em vez de duplicar.
  </Step>

  <Step title="Pagine até o fim">
    Se `next_cursor` não for `null`, chame novamente passando `cursor=<next_cursor>`. Repita até `next_cursor` retornar `null`. Ao longo da paginação, guarde o maior `cursor_at` que você processar.
  </Step>

  <Step title="Guarde o ponto de corte">
    Para o próximo pull incremental, use como `updated_since` o **maior `cursor_at` que você já processou** — não o horário do relógio da sua sincronização. Assim você não pula uma mudança cujo `cursor_at` seja anterior ao fim da execução anterior.
  </Step>
</Steps>

## Limites de requisição

Cada workspace pode fazer cerca de **120 requisições por minuto**. Ao ultrapassar o limite, a API responde com `429 Too Many Requests` e um header `Retry-After` indicando quantos segundos aguardar antes de tentar de novo.

<Tip>
  Respeite o header `Retry-After` no seu cliente e prefira páginas maiores (`limit=1000`) para reduzir o número de requisições em cargas grandes.
</Tip>

## Referência e playground

Consulte a referência de cada endpoint — [conversas](/api-reference/export/exportar-conversas), [mensagens](/api-reference/export/exportar-mensagens), [contatos](/api-reference/export/exportar-contatos), [deals](/api-reference/export/exportar-deals) — e [Identificar workspace](/api-reference/export/whoami) para todos os parâmetros, formatos de resposta e códigos de erro, e para testar as chamadas direto no playground.

## Exclusões e re-sincronização

<Warning>
  O feed incremental **não tem evento de deleção**: quando uma linha é excluída (por exemplo, um contato removido), ela simplesmente deixa de aparecer nas chamadas incrementais — nenhum registro sinaliza a remoção.

  Como você faz upsert por `id`, uma exportação completa (sem `updated_since`) **não remove** sozinha as linhas que já estavam no seu destino e sumiram na origem. Para reconciliar, faça um dos dois:

  * **Reconstrua o destino**: trunque a tabela da entidade e recarregue a partir de uma exportação completa; ou
  * **Reconcilie por `id`**: colete os `id` retornados na exportação completa e apague no destino os que não vieram.
</Warning>