API v1.3.0 Stable

Documentação da API

A API RESTful da SendSync permite orquestrar comunicações multicanal (WhatsApp e Email) com filas inteligentes, validação automática de destinatários, suporte a anexos e priorização por tipo de mensagem.

Alta Performance

Projetada para suportar +1000 RPM (requisições por minuto) com processamento assíncrono via Redis.

Webhooks (Em Breve)

Receba atualizações em tempo real sobre entrega, leitura e respostas dos clientes.

Documentação Interativa (Swagger)

Teste a API diretamente no navegador com nossa documentação Swagger/OpenAPI interativa. Veja todos os endpoints, parâmetros, exemplos e teste requisições em tempo real.

Abrir Swagger UI

Acessando: http://localhost:3000/api/docs

Autenticação

A SendSync oferece duas formas de autenticação para suas requisições:

Chave de API Permanente

Recomendado para integrações backend estáveis. A chave nunca expira até ser revogada.

X-API-Key: sk_live_...

Bearer Token (JWT)

Gerado ao fazer login no painel. Expira periodicamente por segurança.

Authorization: Bearer eyJ...

Você pode gerar e gerenciar suas chaves de API permanentes no menu Dados da API do seu painel.

Segurança Crítica

Nunca exponha sua chave secreta em código client-side (navegador). Realize chamadas apenas do seu servidor backend.

Authorization: Bearer sk_live_51M3...

Base URL

Todos os endpoints são relativos à URL base abaixo:

https://sendsync.com.br

POST/api/queue/send

Enviar Mensagem Unitária

Adiciona uma mensagem à fila de processamento. Este endpoint é ideal para notificações transacionais (OTP, confirmação de pedido). Nota: Se for enviar anexos, utilize o formato multipart/form-data. Para mensagens simples apenas de texto, você pode usar application/json.

Parâmetros do Body

connectorIdstringOBRIGATÓRIO

ID do conector (instância WhatsApp) que realizará o envio.

tostringOBRIGATÓRIO

Destinatário da mensagem. Para WhatsApp: número completo (DDI + DDD + Número) apenas dígitos. Para Email: endereço de email válido. O sistema valida automaticamente baseado no tipo de conector.

Ex: 5511999998888 ou email@exemplo.com

messagestringOBRIGATÓRIO

Conteúdo da mensagem. Suporta formatação Markdown do WhatsApp.

contactNamestring

Nome da pessoa ou empresa. Será usado para atualizar o cadastro mestre e ficará registrado no histórico da mensagem.

Ex: João Silva

messageTypestring

Tipo/categoria da mensagem. Valores: GERAL (padrão), NOTIFICATION, MARKETING, TRANSACTIONAL, SUPPORT, REMINDER.

Ex: TRANSACTIONAL

forceDirectboolean

Opte por true para pular a fila de prioridade normal (use com cautela).

externalIdstring

ID de referência do seu sistema. Útil para conciliação e consulta posterior.

Ex: PEDIDO-12345

attachmentsfile[]

Arquivos para anexar à mensagem. Requer envio via multipart/form-data. Limite: 50MB por arquivo. Suportado para WhatsApp e Email.

attachmentUrlstring

URL pública de um arquivo PDF para download e anexo automático. Útil para boletos e documentos. O sistema baixa e anexa automaticamente.

Ex: https://exemplo.com/boleto.pdf

Exemplo de Requisição

curl -X POST https://sendsync.com.br/api/queue/send \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "connectorId": "con_123456",
    "to": "5511999998888",
    "message": "Olá *Cliente*, seu pedido foi confirmado!",
    "contactName": "João Silva",
    "notes": "Mensagem de confirmação de pedido #12345",
    "messageType": "TRANSACTIONAL",
    "externalId": "REF-123"
  }'

# --- ALTERNATIVA: Chave de API Permanente ---
curl -X POST https://sendsync.com.br/api/queue/send \
  -H "X-API-Key: SUA_API_KEY_PERMANENTE" \
  -H "Content-Type: application/json" \
  -d '{
    "connectorId": "con_123456",
    "to": "5511999998888",
    "contactName": "Maria Oliveira",
    "message": "Sua chave de acesso é 1234",
    "externalId": "REF-456"
  }'

# Exemplo com Email
curl -X POST https://sendsync.com.br/api/queue/send \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type": application/json" \
  -d '{
    "connectorId": "con_email_123",
    "to": "cliente@exemplo.com",
    "message": "Seu pedido foi confirmado!",
    "messageType": "TRANSACTIONAL"
  }'

# Exemplo com Anexo via URL (Boleto)
curl -X POST https://sendsync.com.br/api/queue/send \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "connectorId": "con_whatsapp_123",
    "to": "5511999998888",
    "message": "Segue o boleto em anexo",
    "attachmentUrl": "https://api.asaas.com/boleto.pdf"
  }'

# Exemplo com Anexo (Multipart)
curl -X POST https://sendsync.com.br/api/queue/send \
  -H "Authorization: Bearer SEU_TOKEN" \
  -F "connectorId=con_123456" \
  -F "to=5511999998888" \
  -F "message=Segue o comprovante" \
  -F "attachments=@/caminho/do/arquivo.pdf"

Resposta de Sucesso (201 Created)

{
  "id": "msg_01HQ...",
  "status": "queued",
  "priority": 1,
  "queuePosition": 42
}

POST/api/queue/bulk

Envio em Massa

Permite enviar até 1000 mensagens em uma única requisição HTTP. Altamente recomendado para campanhas de marketing para reduzir overhead de rede.

curl -X POST https://sendsync.com.br/api/queue/bulk \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      { "connectorId": "c1", "to": "5511999...", "message": "Msg 1", "messageType": "MARKETING" },
      { "connectorId": "c1", "to": "5511988...", "message": "Msg 2", "messageType": "MARKETING" }
    ]
  }'

GET/api/queue/list

Listar Fila de Mensagens

Retorna as últimas 100 mensagens da fila. Útil para monitorar o status de envios ou construir um dashboard personalizado.

Query params

statusenum

Filtra mensagens pelo status atual. Se omitido, retorna todos.

Ex: PENDING, WAITING, PROCESSING, SENT, FAILED, CANCELED

pageinteger

Número da página para paginação. Padrão: 1

Ex: 1

limitinteger

Quantidade de itens por página. Padrão: 250

Ex: 250

externalIdstring

Filtra mensagens pelo seu ID de referência externo.

Ex: PEDIDO-12345

Exemplo de Requisição

curl -X GET "https://sendsync.com.br/api/queue/list?externalId=PEDIDO-12345" \
  -H "Authorization: Bearer TOKEN"

Exemplo de Resposta

{
  "data": [
    {
      "id": "...",
      "to": "5511...",
      "attachments": [
        {
           "url": "https://api.../uploads/file.pdf"
        }
      ]
    }
  ],
  "meta": {
    "total": 1050,
    "page": 1,
    "limit": 250,
    "pages": 5
  }
}

GET/api/connectors

Listar Conectores

Retorna todos os conectores configurados (WhatsApp, Email, Telegram) com informações essenciais. Por segurança, credenciais e configurações sensíveis não são incluídas na resposta.

Exemplo de Requisição

curl -X GET "https://sendsync.com.br/api/connectors" \
  -H "X-API-Key: sk_live_..."

Exemplo de Resposta

[
  {
    "id": "5806e15b-3c25-4fc7-9654-e434ceab6ad1",
    "name": "WhatsApp Principal",
    "type": "WHATSAPP",
    "companyId": "5ead4a6a-8558-4750-b772-9bf40e66981d"
  },
  {
    "id": "7a92f3c1-4d5e-6f8a-9b0c-1d2e3f4a5b6c",
    "name": "Email Transacional",
    "type": "EMAIL",
    "companyId": "5ead4a6a-8558-4750-b772-9bf40e66981d"
  }
]

POST/whatsapp/connect/:connectorId

Conectar Sessão WhatsApp

Inicia o processo de conexão e retorna o QR Code (em base64) para ser escaneado pelo aplicativo.

curl -X POST https://sendsync.com.br/whatsapp/connect/con_123 \
  -H "Authorization: Bearer TOKEN"

Guia: Prevenção de Bloqueios

Spintax & Variáveis

Jamais envie o mesmo texto hash idêntico para milhares de pessoas. Use variações como 'Olá', 'Oi', 'Tudo bem' e inclua o nome do cliente.

Limitadores de Velocidade

Comece devagar. O sistema aplica delay aleatório (min-max) entre mensagens, mas respeite o limite de aquecimento do chip.

Saúde do Chip (Health Score)

O WhatsApp monitora interações. Se você envia 1000 msgs e recebe 0 respostas (ou muitos bloqueios), seu score cai.

Warm-up Gradual

Dia 1: 50 msgs. Dia 2: 100 msgs. Dia 3: 200 msgs. Aumente 30-50% ao dia até o volume desejado.