Comece por aqui
A API do AzChat é REST, recebe e devolve JSON, e usa um header de autenticação simples. Se você já tem uma conta, dá para fazer a primeira chamada em dois minutos.
Endereço da API
Todos os exemplos apontam para a instância padrão:
https://app.azchat.digital
Se você usa uma instância própria (self-hosted ou dedicada), troque o host pelo seu endereço. Em cada endpoint da Referência há um seletor de servidor onde você informa o host — os exemplos de código e o console passam a usar o valor que você escolher.
Gerando uma chave de API
- No AzChat, vá em Configurações → API.
- Clique em Criar nova chave, dê um nome que lembre o uso (ex.:
Integração ERP). - Copie a chave na hora. Por segurança, ela não é exibida de novo.
:::warning Escopos ainda não são aplicados A tela de criação deixa você marcar escopos, mas eles ainda não são verificados pelo servidor: hoje qualquer chave tem acesso total à conta. Trate toda chave como se fosse de acesso total — não distribua uma chave "somente leitura" achando que ela está limitada. :::
Autenticando
Envie a chave no header api_access_token em toda requisição:
curl --request GET \
--url 'https://app.azchat.digital/api/v1/accounts/1/contacts' \
--header 'api_access_token: SUA_CHAVE_AQUI' \
--header 'accept: application/json'
O 1 no caminho é o ID da conta. Você encontra ele em Configurações → API,
logo no topo da página.
Existem três tipos de credencial. A maior parte da API usa a primeira:
| Credencial | Para quê |
|---|---|
userApiKey | Chave de usuário. Cobre quase toda a API, respeitando as permissões do dono da chave. |
agentBotApiKey | Token de bot de atendimento. Acesso restrito aos endpoints de bot. |
platformAppApiKey | Token de platform app. Provisiona contas, usuários e bots. |
Detalhes em Autenticação.
Testando na própria documentação
Cada endpoint da Referência tem um botão Send API Request: você preenche o host, cola a chave e dispara a requisição real, sem escrever código. A resposta aparece ali mesmo, e o exemplo em cURL, Node, Ruby, PHP ou Python é gerado com os valores que você usou.
:::info O console precisa de CORS liberado
A requisição sai do seu navegador direto para a sua instância, então ela precisa
aceitar chamadas de outra origem. Ligue a variável de ambiente
ENABLE_API_CORS=true na instância e reinicie. Sem isso, o navegador bloqueia a
chamada e o console mostra um erro de rede — a API em si continua funcionando
normalmente fora do navegador.
:::
:::danger Não existe sandbox
Diferente de outras APIs, o AzChat não tem um ambiente de testes separado. O que
você disparar pelo console acontece de verdade, nos seus dados de produção —
inclusive DELETE. Para experimentar sem risco, use uma conta de testes.
:::
Sobre a maturidade desta referência
Esta documentação cobre todos os endpoints da API, porque ela é gerada a partir das rotas reais da aplicação. Mas nem todos foram revisados ainda: boa parte traz apenas o caminho, os parâmetros e os campos do corpo derivados automaticamente do código, sem descrição nem exemplo de resposta.
Onde você vir o aviso de campos "derivados automaticamente do código-fonte", trate os tipos como uma dica, não como contrato — eles são inferidos pelo nome do campo. Os endpoints revisados à mão não têm esse aviso.
Próximos passos
- Autenticação — as três credenciais em detalhe
- Paginação — como percorrer listas grandes
- Erros — o que cada código HTTP significa
- Webhooks — receber eventos em vez de ficar consultando
- Referência — todos os endpoints