# API do DoneTalk

A API deixa o seu sistema (ERP, CRM, site, automação) fazer no DoneTalk o que se faz na tela: criar e disparar campanhas de WhatsApp, cadastrar e atualizar contatos, mandar mensagens, acompanhar e concluir atendimentos, marcar horários e receber avisos de tudo o que acontece.

- **Endereço:** `https://api.donetalk.com/v1/c/{empresa}`, onde `{empresa}` é o identificador da sua empresa no DoneTalk.
- **Formato:** JSON, datas em ISO 8601 (UTC), ids em UUID, valores em dinheiro em micros (1.000.000 = 1 unidade da moeda).
- **Especificação completa:** [OpenAPI](https://api.donetalk.com/v1/openapi.json?lang=pt), para gerar código ou importar no Postman.

## Primeiros passos

1. Um administrador cria a chave em **Configurações › API** no DoneTalk e marca o que ela pode fazer. Para começar sem risco, escolha **Teste**: ela simula tudo e não envia nada.
2. Confira a chave:

```bash
curl https://api.donetalk.com/v1/c/{empresa}/me \
  -H "Authorization: Bearer $DONETALK_KEY"
```

3. Crie uma campanha com a lista de contatos na própria chamada, revise o custo e dispare. O guia [Campanhas, do começo ao fim](/desenvolvedores/campanhas/) mostra cada passo.
4. Cadastre um endereço do seu sistema para receber os [avisos](/desenvolvedores/avisos/): entregue, lida, respondida, atendimento concluído com o desfecho.

## Experimente agora, sem conta

A empresa de demonstração `demo` aceita a chave de teste pública abaixo. Tudo é simulado: as respostas têm o formato real, com dados de exemplo, e nada é gravado ou enviado.

```bash
export DONETALK_KEY=dt_test_demo_zRZ6twAhj4u9dZT0hEBrNFzr
curl -X POST https://api.donetalk.com/v1/c/demo/campaigns \
  -H "Authorization: Bearer $DONETALK_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Primeira campanha", "audience": {"kind": "contacts", "people": [{"phone": "+5548999990001", "name": "Ana"}]}}'
```

## O que a API cobre

| Área                                                                                            | O que dá para fazer                                                                                                                           |
| ----------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| [Campanhas](/desenvolvedores/referencia/campaigns/)                                                     | criar, revisar custo e regras, testar, disparar ou agendar, pausar, retomar, cancelar, reenviar falhas, ver cada destinatário e os resultados |
| [Segmentos](/desenvolvedores/referencia/segments/)                                                      | grupos de contatos por condições, contar e buscar                                                                                             |
| [Contatos](/desenvolvedores/referencia/contacts/)                                                       | criar, atualizar ou importar até 1.000 por vez, etiquetas, consentimento, fichas de contexto, apagar a pedido do titular                      |
| [Campos](/desenvolvedores/referencia/contact-fields/)                                                   | ver e criar os campos dos contatos                                                                                                            |
| [Modelos](/desenvolvedores/referencia/templates/)                                                       | os modelos aprovados pela Meta, com variáveis e botões                                                                                        |
| [Mensagens](/desenvolvedores/referencia/messages/) e [atendimentos](/desenvolvedores/referencia/conversations/) | mandar um modelo para um telefone, texto e arquivos na janela de 24 h, concluir com desfecho                                                  |
| [Números, equipes e etiquetas](/desenvolvedores/referencia/numbers-teams-and-tags/)                     | para escolher o número que envia e a equipe que recebe as respostas                                                                           |
| [Agenda](/desenvolvedores/referencia/scheduling/)                                                       | horários livres, marcar, remarcar e cancelar                                                                                                  |
| [Avisos](/desenvolvedores/referencia/webhooks/)                                                         | criar e acompanhar os endereços que recebem os eventos                                                                                        |

## Antes de ir para produção

- Use uma chave por sistema, só com os escopos de que ele precisa ([Chaves e escopos](/desenvolvedores/chaves-e-escopos/)).
- Mande `Idempotency-Key` em criações e envios e respeite o limite de 600 chamadas por minuto ([Erros e limites](/desenvolvedores/erros-e-limites/)).
- Confira a assinatura de cada aviso ([Avisos](/desenvolvedores/avisos/)).