Skip to main content

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

​
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.
Para confirmar a qual workspace a sua chave dá acesso, use o endpoint GET /v1/whoami.
Você gera a sua workspace API key na própria plataforma, em Integrações → Configurar API.
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.

​
Entidades disponíveis

A exportação é feita por entidade, cada uma no seu próprio endpoint: Todas as linhas, de qualquer entidade, incluem estes campos: 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:
O comportamento depende do parâmetro updated_since:
1

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

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

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

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.

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

​
Referência e playground

Consulte a referência de cada endpoint — conversas, mensagens, contatos, deals — e Identificar workspace 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

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.