Documentação da API SMS

# expected output contract
{
  "action": "send_sms_simple",
  "request": {
    "method": "POST",
    "path": "/v1/messages/send",
    "headers": { "Authorization": "Bearer <token>" },
    "json": {
      "to": "5511999999999",
      "message": "Olá! Seu pedido foi confirmado."
    }
  }
}

# machine-readable links
docs: /api/documentacao
postman: /postman/viasms.postman_collection.json
ai index: /machine/viasms.ai-index.json

# task recipes
recipes:
- auth_login: POST /v1/auth/login
- send_sms_simple: POST /v1/messages/send (to, message)
- send_sms_campaign: POST /v1/messages/send (to, message, campaign)
- campaign_create: POST /v1/campaigns
- contact_create_one: POST /v1/campaigns/{campaign}/contacts
- contact_import: POST /v1/campaigns/{campaign}/contacts/import
- settings_get: GET /v1/settings

# auth
Header obrigatório:
Authorization: Bearer SEU_TOKEN

Regras:
- token expira em 24h
- gere novo token via /v1/auth/login
- sem token ou token inválido => 401

# error format
{
  "error": {
    "code": "validation_error",
    "message": "Payload inválido",
    "details": [
      { "field": "to", "issue": "telefone inválido" }
    ]
  },
  "request": "req_9f13a2d1"
}

# rate limit
Headers de limite:
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 41
X-RateLimit-Reset: 1715301040

Erro 429:
{
  "error": {
    "code": "rate_limited",
    "message": "Muitas requisições, tente novamente."
  },
  "request": "req_f77a1b8c"
}

Retry recomendado: exponential backoff (1s, 2s, 4s, 8s).

# webhook security
Assinatura enviada no header:
X-ViaSMS-Signature: sha256=<hmac_hex>
X-ViaSMS-Timestamp: 1715301012

Assinatura = HMAC_SHA256(webhook_secret, timestamp + "." + raw_body)

Valide:
1) timestamp com janela de até 5 minutos
2) assinatura com comparação segura
3) idempotência por event

# response 200
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI...",
  "token_type": "Bearer",
  "expires_in": 86400,
  "account": "acc_123"
}

# error 401
{
  "error": {
    "code": "invalid_credentials",
    "message": "E-mail ou senha inválidos."
  },
  "request": "req_3fa120bb"
}

# send with campaign
curl -X POST https://api-gateway.apiwhitelabel.com/v1/messages/send \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "5511999999999",
    "message": "Olá! Seu pedido foi confirmado.",
    "campaign": "cmp_123"
  }'

# sms simple
curl -X POST https://api-gateway.apiwhitelabel.com/v1/messages/send \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "5511999999999",
    "message": "Olá! Seu pedido foi confirmado."
  }'

# payload fields
to: string (E.164, ex.: 5511999999999) [obrigatório]
message: string (1..1600 caracteres) [obrigatório]
campaign: string (ID da campanha) [opcional]

# response 202
{
  "message": "msg_89231",
  "status": "queued",
  "to": "5511999999999",
  "campaign": "cmp_123",
  "request": "req_d1aa93bc"
}

# error 422
{
  "error": {
    "code": "validation_error",
    "message": "Campo to inválido",
    "details": [
      { "field": "to", "issue": "must be E.164" }
    ]
  },
  "request": "req_8ab31dc4"
}

# create
curl -X POST https://api-gateway.apiwhitelabel.com/v1/campaigns \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "campanha_boas_vindas",
    "description": "Fluxo inicial para novos contatos",
    "webhook": "https://suaempresa.com/webhook/campaign-events",
    "delay": 60,
    "template": "tpl_boas_vindas"
  }'

# update
curl -X PATCH https://api-gateway.apiwhitelabel.com/v1/campaigns/cmp_123 \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Campanha atualizada para clientes premium",
    "delay": 90,
    "template": "tpl_premium"
  }'

# delete
curl -X DELETE https://api-gateway.apiwhitelabel.com/v1/campaigns/cmp_123 \
  -H "Authorization: Bearer SEU_TOKEN"

# payload fields
name: string (nome da campanha)
description: string (descrição interna)
webhook: string (URL para eventos da campanha)
delay: number (atraso em segundos entre lotes)
template: string (ID do template usado no disparo)

# response 201
{
  "campaign": "cmp_123",
  "name": "campanha_boas_vindas",
  "status": "scheduled",
  "created_at": "2026-05-09T03:11:22Z",
  "request": "req_4ec08f1a"
}

# status lifecycle
possible statuses:
- draft
- scheduled
- running
- paused
- finished
- cancelled

# create one
curl -X POST https://api-gateway.apiwhitelabel.com/v1/campaigns/cmp_123/contacts \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "5511999999999",
    "name": "Maria Souza",
    "email": "[email protected]"
  }'

# upload contacts
curl -X POST https://api-gateway.apiwhitelabel.com/v1/campaigns/cmp_123/contacts/import \
  -H "Authorization: Bearer SEU_TOKEN" \
  -F "[email protected]" \
  -F "file_format=csv" \
  -F "phone_column=phone" \
  -F "name_column=name" \
  -F "email_column=email" \
  -F "document_column=document" \
  -F "tags_column=tags" \
  -F "delimiter=," \
  -F "has_header=true"

# response 201
{
  "contact": "ctt_5532",
  "campaign": "cmp_123",
  "phone": "5511999999999",
  "name": "Maria Souza",
  "request": "req_0bce198f"
}

# import response 202
{
  "job": "job_imp_9012",
  "status": "processing",
  "campaign": "cmp_123",
  "received_file": "contatos.csv",
  "request": "req_6d311be2"
}

# import rules
Regras de importação:
- formatos: csv, xlsx
- tamanho máximo: 10 MB
- até 100.000 linhas por arquivo
- duplicados por phone são ignorados
- encoding recomendado: UTF-8

# create
curl -X POST https://api-gateway.apiwhitelabel.com/v1/templates \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"boas_vindas","content":"Olá {{nome}}, bem-vindo!"}'

# update
curl -X PATCH https://api-gateway.apiwhitelabel.com/v1/templates/tpl_123 \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"content":"Novo conteúdo do template"}'

# delete
curl -X DELETE https://api-gateway.apiwhitelabel.com/v1/templates/tpl_123 \
  -H "Authorization: Bearer SEU_TOKEN"

# response get
{
  "data": [
    { "template": "tpl_123", "name": "boas_vindas", "content": "Olá {{nome}}" }
  ],
  "page": 1,
  "per_page": 20,
  "total": 1,
  "request": "req_aa12fd73"
}

# payload fields
name: string (3..80) [obrigatório em create]
content: string (1..1600) [obrigatório em create/update]

# example de callback
{
  "event": "message.delivered",
  "message": "msg_89231",
  "to": "5511999999999",
  "status": "delivered",
  "delivered_at": "2026-05-09T02:58:40Z"
}

# signature validation
Validação recomendada:
1) leia X-ViaSMS-Timestamp e X-ViaSMS-Signature
2) gere HMAC com webhook_secret
3) compare assinatura em tempo constante
4) rejeite callback com timestamp antigo

# retry policy
Política de retry do callback:
- timeout de resposta: 10s
- tentativas: 5
- intervalo: exponential backoff
- qualquer status 2xx confirma recebimento

# get
curl -X GET https://api-gateway.apiwhitelabel.com/v1/settings \
  -H "Authorization: Bearer SEU_TOKEN"

# response 200
{
  "account": "acc_123",
  "timezone": "America/Sao_Paulo",
  "default_sender": "Whitelabel",
  "two_factor_enabled": true,
  "request": "req_12ca02f2"
}