Referência Técnica

Página pensada para quem vai integrar de verdade: endpoint, payload, retorno, erro e comportamento assíncrono.

TL;DR técnico

  • Base URL: https://server.sendeasy.app
  • Auth: Authorization: Bearer <token>
  • Formatos: application/json e multipart/form-data
  • Processamento: vários fluxos são enfileirados (resposta HTTP confirma recebimento, não entrega final)
  • Erros: trate error como contrato estável

1) Matriz de autenticação

ContextoEndpointToken
Mensageria simples/api/messages/sendToken do canal
WABA API/api/v1/waba/:whatsappId/*API Token
Integrações públicas/api/integration/*Token da integração

Header padrão:

Authorization: Bearer SEU_TOKEN

2) Endpoint principal para integração (/api/messages/send)

Use quando você quer enviar mensagem e/ou registrar lead rapidamente.

Request

POST /api/messages/send

Campos de body (JSON)

  • Name
    number
    Type
    string
    Description

    Obrigatório. Número no formato internacional (ex.: 5511999999999).

  • Name
    body
    Type
    string
    Description

    Texto da mensagem.

  • Name
    name
    Type
    string
    Description

    Nome do contato.

  • Name
    email
    Type
    string
    Description

    Email do contato.

  • Name
    sector
    Type
    string
    Description

    ID da fila/setor de destino.

  • Name
    files
    Type
    array[string]
    Description

    Lista de URLs de mídia/arquivo.

Fluxo backend (resumido)

  1. Valida campos obrigatórios.
  2. Resolve canal pelo token.
  3. Sincroniza contato.
  4. Publica job na fila de envio.
  5. Retorna resposta HTTP.

Request

POST
/api/messages/send
curl --location 'https://server.sendeasy.app/api/messages/send' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer TOKEN_DO_CANAL' \
  --data '{
    "name": "Lead Exemplo",
    "email": "lead@empresa.com",
    "number": "5511999999999",
    "body": "Quero atendimento comercial",
    "sector": "12",
    "files": ["https://meusite.com/apresentacao.pdf"]
  }'

Response (mensagem enfileirada)

{
  "mensagem": "Mensagem enviada"
}

Response (sem body/files, só cadastro de contato)

{
  "mensagem": "Contato cadastrado com sucesso"
}

3) WABA API (baseada na coleção Postman)

Fonte: [SENDEASY] WABA Integration API.postman_collection.json

Prefixo:

/api/v1/waba/:whatsappId

Templates

MétodoEndpoint
GET/templates
POST/templates
PUT/templates/:templateId
DELETE/templates/:templateName

Mensagens

MétodoEndpointObservação
POST/sendTemplate (inclui variação "template simples")
POST/send-textTexto
POST/send-imageImagem
POST/send-videoVídeo
POST/send-audioÁudio
POST/send-documentDocumento
POST/marketing-lite/sendMensagem marketing (Marketing Messages Lite API)

Exemplo send-text:

curl --location 'https://server.sendeasy.app/api/v1/waba/WHATSAPP_ID/send-text' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer API_TOKEN' \
  --data '{
    "to": "5511999999999",
    "text": "Olá! Mensagem enviada pela WABA API."
  }'

Response típico:

{
  "messaging_product": "whatsapp",
  "contacts": [
    { "input": "5511999999999", "wa_id": "5511999999999" }
  ],
  "messages": [
    { "id": "wamid.HBg..." }
  ]
}

4) Webhooks (entrada e repasse)

Fonte: webhook-eventos.md

Endpoint principal (Evolution)

POST /webhook/connections

Payload mínimo:

{
  "event": "connection.update",
  "data": { "state": "open" },
  "instance": "uuid-da-instancia"
}

Eventos relevantes

  • connection.update
  • messages.upsert
  • messages.set
  • send.message
  • messages.update
  • messages.delete
  • call

Exemplo completo (messages.upsert)

{
  "event": "messages.upsert",
  "data": {
    "key": {
      "remoteJid": "5511999999999@s.whatsapp.net",
      "fromMe": false,
      "id": "3EB0XXXXXX"
    },
    "message": {
      "conversation": "Olá!"
    },
    "messageTimestamp": "1634567890",
    "pushName": "Cliente"
  },
  "instance": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Response esperado

{
  "message": "Webhook recebido com sucesso"
}

Repasse para webhook do projeto

Quando configurado, o backend pode repassar:

{
  "event": "messages.upsert",
  "channel": "whatsapp",
  "data": {},
  "channelId": "uuid-do-canal"
}

5) Traduções para dev (mesma ideia do frontend)

Para UX multilíngue, siga o mesmo padrão do frontend:

  • use error como chave de tradução
  • mantenha um catálogo local backendErrors por idioma (pt, en, es)

Exemplo:

const backendErrors = {
  pt: { ERR_NO_PERMISSION: 'Você não tem permissão para acessar este recurso.' },
  en: { ERR_NO_PERMISSION: 'You do not have permission to access this resource.' },
  es: { ERR_NO_PERMISSION: 'No tienes permiso para acceder a este recurso.' },
}

function resolveBackendError(errorCode, locale = 'pt') {
  return backendErrors?.[locale]?.[errorCode] || errorCode
}

Erros comuns em integração pública:

  • ERR_NO_PERMISSION
  • ERR_SESSION_EXPIRED
  • ERR_API_TOKEN_NOT_PROVIDED
  • ERR_API_TOKEN_INVALID
  • ERR_SENDING_TEMPLATE
  • ERR_TRY_AGAIN_LATER

6) Estratégia de erro e retry

Parse recomendado

function normalizeApiError(status, body) {
  return {
    status,
    code: body?.error || 'UNKNOWN_ERROR',
    message: body?.message || null,
    details: body?.details || null,
  }
}

Retry policy

  1. Retry com backoff para 429 e 5xx.
  2. Não fazer retry cego para 4xx de validação.
  3. Use idempotência por messageId/eventId nos webhooks.

7) Checklist de produção

  1. Separar tokens por ambiente.
  2. Configurar timeout no client.
  3. Logar request/response com correlação.
  4. Monitorar taxa de erro por endpoint.
  5. Implementar alertas para falhas de webhook.

Quer onboarding rápido de squad? Use esta página como "contract first" e derive SDK interno em cima dos exemplos de request/response.

Essa informação foi útil?