<!-- Source: https://docs.sendeasy.app/server/api-publica -->

# API Pública (Server)

Guia técnico para consumir as rotas públicas da Sendeasy via backend.

## Base URL

```txt
https://backend.sendeasy.app
```

## Autenticação

Existem 3 modelos principais:

1. **API Token** (`Authorization: Bearer <api_token>`) — WABA API e Bots API
2. **Token do canal** (`Authorization: Bearer <token_do_canal>`) — WhatsApp em `/api/messages/send`, e-mail em `/api/v1/email/*`
3. **Token de integração** (`/api/integration/generic`)

## Endpoints públicos principais

### 1) Mensageria simples

| Método | Endpoint             | Auth           |
| ------ | -------------------- | -------------- |
| `POST` | `/api/messages/send` | Token do canal |

Payload base:

```json
{
  "name": "Lead Exemplo",
  "email": "lead@exemplo.com",
  "number": "5511999999999",
  "body": "Olá! Quero saber mais.",
  "sector": "12",
  "files": ["https://meusite.com/arquivo.pdf"]
}
```

### 2) Integrações públicas

| Método | Endpoint                   | Auth          |
| ------ | -------------------------- | ------------- |
| `POST` | `/api/integration/generic` | Token Generic |

### 3) WABA API

Prefixo:

```txt
/api/v1/waba/:whatsappId
```

Detalhes completos em [/server/waba](https://docs.sendeasy.app/server/waba.md).

### 4) E-mail API

| Método | Endpoint               | Auth                    |
| ------ | ---------------------- | ----------------------- |
| `POST` | `/api/v1/email/send`   | Token do e-mail (canal) |
| `GET`  | `/api/v1/email/health` | Token do e-mail (canal) |

Envio transacional pelo e-mail dono do token (cada e-mail do projeto tem o seu, em Canais → E-mail), 1 crédito de e-mail por envio. Detalhes completos em [/server/email](https://docs.sendeasy.app/server/email.md).

### 5) Bots API

| Método | Endpoint                | Auth      |
| ------ | ----------------------- | --------- |
| `POST` | `/api/v1/ai/completion` | API Token |
| `POST` | `/api/v1/ai/extract`    | API Token |
| `POST` | `/api/v1/ai/search`     | API Token |
| `GET`  | `/api/v1/ai/health`     | API Token |

Geração de texto, extração de PDF e busca na base de conhecimento do bot, 1 crédito de bot por geração (`search` e `health` não consomem). Detalhes completos em [/server/bots](https://docs.sendeasy.app/server/bots.md).

### 6) Submissões de Diagnóstico

| Método | Endpoint                         | Auth      |
| ------ | -------------------------------- | --------- |
| `POST` | `/api/v1/diagnostic-submissions` | API Token |

Registra as tentativas de envio dos seus formulários de diagnóstico (quiz/avaliação) para acompanhar em Leads → Submissões de Diagnóstico. Não consome créditos. Detalhes completos em [/server/diagnosticos](https://docs.sendeasy.app/server/diagnosticos.md).

## Exemplo cURL (`/api/messages/send`)

```bash
curl --location 'https://backend.sendeasy.app/api/messages/send' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer SEU_TOKEN_DO_CANAL' \
  --data '{
    "name": "Lead Exemplo",
    "number": "5511999999999",
    "body": "Mensagem enviada por integração"
  }'
```

## Respostas e contratos

### Sucesso típico

```json
{
  "message": "Message queued successfully"
}
```

### Erro típico

```json
{
  "error": "ERR_NO_PERMISSION"
}
```

### Traduções (padrão frontend)

Para aplicações multilíngues, traduza o `error` no client usando catálogo
`backendErrors` com `pt`, `en` e `es`.

Exemplo:

```js
const i18nError = backendErrors[locale]?.[response.error] || response.error
```

Em integrações de produção, normalize sua leitura de erros pelo campo
error e não por textos literais.