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.

Fluxo de uso recomendado

Autenticação

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

Você pode gerar e gerenciar suas chaves de API permanentes no menu Dados da API do painel (após login).

Obter token JWT (login)

Para usar Authorization: Bearer <token>, faça login com email e senha do painel:

curl -X POST https://sendsync.com.br/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"seu@email.com","password":"sua_senha"}'

Resposta: { "access_token": "eyJ...", "user": { ... } }. Use access_token no header Authorization: Bearer <access_token>.

Authorization: Bearer sk_live_51M3...

Respostas de erro comuns

• 401 Unauthorized — Token inválido ou expirado; chave de API inválida.
• 400 Bad Request — Dados inválidos (ex.: connectorId, to ou message ausentes ou formato incorreto).
• 404 — Recurso não encontrado (ex.: conector ou mensagem inexistente).

URL base

Todos os endpoints da API estão sob o prefixo /api. Use a URL base:

Exemplo: enviar mensagem = https://sendsync.com.br/api/queue/send

Enviar mensagem unitária

Adiciona uma mensagem à fila de processamento. Ideal para notificações transacionais (OTP, confirmação de pedido). A mensagem é processada de forma assíncrona conforme a fila e os limites do conector.

Formato: Para mensagens só de texto use Content-Type: application/json. Para anexos use multipart/form-data e envie os arquivos no campo attachments. Limite por arquivo: 50MB.

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"

{
  "id": "uuid-da-mensagem",
  "status": "PENDING",
  "to": "5511999998888",
  "message": "Olá! Seu pedido foi confirmado.",
  "priority": 5,
  "connectorId": "uuid-do-conector",
  "messageType": "TRANSACTIONAL",
  "createdAt": "2024-01-22T14:30:00.000Z",
  "externalId": "REF-123"
}

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" }
    ]
  }'

Listar Fila de Mensagens

Retorna mensagens da fila com paginação e filtros. Ordenação: mais recentes primeiro. Útil para monitorar envios e consultar status por externalId.

curl -X GET "https://sendsync.com.br/api/queue/list?status=SENT&page=1&limit=50&externalId=PEDIDO-12345" \
  -H "Authorization: Bearer SEU_TOKEN"

{
  "data": [
    {
      "id": "uuid",
      "to": "5511999998888",
      "message": "Texto da mensagem",
      "status": "SENT",
      "priority": 5,
      "messageType": "TRANSACTIONAL",
      "connectorId": "uuid-conector",
      "createdAt": "2024-01-22T14:30:00.000Z",
      "sentAt": "2024-01-22T14:30:05.000Z",
      "externalId": "PEDIDO-12345",
      "attachments": [{ "id": "...", "url": "...", "originalFileName": "file.pdf" }]
    }
  ],
  "meta": { "total": 100, "page": 1, "limit": 50, "pages": 2 }
}

Listar conectores

Retorna os conectores da sua empresa (WhatsApp, E-mail). Use o id em POST /api/queue/send e em POST /api/whatsapp/connect/:connectorId. Credenciais e config sensíveis não são retornadas.

curl -X GET "https://sendsync.com.br/api/connectors" \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "X-API-Key: SUA_API_KEY"

Resposta: array de objetos com id, name, type (WHATSAPP, EMAIL), status (ACTIVE, PAUSED, DISCONNECTED), companyId.

Conectar sessão WhatsApp

Inicia a conexão do conector WhatsApp e retorna o QR Code (em base64) para ser escaneado no aplicativo WhatsApp do celular. O connectorId é o ID do conector retornado em GET /api/connectors.

Resposta: { status, qrCode? } — quando status for QR_CODE, use o qrCode (data URL) para exibir a imagem e o usuário escaneia no WhatsApp.

curl -X POST https://sendsync.com.br/api/whatsapp/connect/SEU_CONNECTOR_ID \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "X-API-Key: SUA_API_KEY"

WhatsApp — Status e desconexão

Contatos (CRM)

Endpoints para manter um cadastro de contatos (identificador + tipo WHATSAPP/EMAIL + nome). Útil para atualizar o nome ao enviar mensagem e para listar/inativar contatos.

• GET /api/contacts — Lista todos os contatos da empresa.
• POST /api/contacts — Cria ou atualiza contato (body: identifier, type, name?).
• PATCH /api/contacts/:id/status — Ativa/inativa (body: active, reason?).
• DELETE /api/contacts/:id — Remove o contato.

Todos exigem autenticação (JWT ou X-API-Key).

Baixar template Excel

Retorna um arquivo Excel (.xlsx) com o formato esperado para importação em massa de mensagens (usado junto ao fluxo de importação do painel). Requer autenticação.

curl -X GET "https://sendsync.com.br/api/queue/template" \
  -H "Authorization: Bearer SEU_TOKEN" \
  -o template_mensagens.xlsx