API REST

• Base: https://falia.com.br/api/v1
• Autenticação: Authorization: Bearer <API key> (API keys)
• Formato: JSON UTF-8. Datas em milissegundos UTC.
• Contrato: OpenAPI 3.1 · referência navegável

Recursos

Método e caminho	O que faz	Permissão
GET /status	Estado do WhatsApp (open, connecting, close)	conversations:read
GET /conversations	Conversas, da mais recente para a mais antiga	conversations:read
GET /conversations/{id}/messages	Mensagens mais recentes de uma conversa	conversations:read
POST /messages	Envia uma mensagem de texto	messages:send
GET/POST /webhooks, DELETE /webhooks/{id}	Gerencia webhooks	webhooks:manage

Exemplos

# Conversas (paginação por cursor)
curl -s https://falia.com.br/api/v1/conversations?limit=20 \
  -H "Authorization: Bearer $FALIA_KEY"
# → { "data": [{ "id": "5511999990000@s.whatsapp.net", "name": "Ana", "unread": 2, ... }], "next_cursor": "MjA" }

# Próxima página
curl -s "https://falia.com.br/api/v1/conversations?limit=20&cursor=MjA" -H "Authorization: Bearer $FALIA_KEY"

# Enviar mensagem (repetir com a mesma Idempotency-Key não envia de novo; use o id do seu pedido/evento)
curl -s -X POST https://falia.com.br/api/v1/messages \
  -H "Authorization: Bearer $FALIA_KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: $PEDIDO_ID" \
  -d '{ "to": "11999990000", "text": "Seu carro está pronto para retirada!" }'
# → 201 { "id": "3EB0...", "conversation_id": "5511999990000@s.whatsapp.net", "sent_at": 1730000000000 }

to aceita o número com DDD (com ou sem +55, espaços e traços) ou o id de uma conversa.

Erros

Erros vêm em application/problem+json (RFC 9457):

{ "type": "about:blank", "title": "Forbidden", "status": 403, "detail": "a API key não tem o escopo messages:send", "request_id": "9f2c..." }

Status	Quando
400 / 422	Dados inválidos (detail diz o quê)
401	Chave ausente, inválida, revogada ou vencida
403	A chave não tem a permissão
404	Não encontrado
429	Limite atingido (veja Retry-After)
502	O WhatsApp não respondeu — tente de novo

Ao falar com o suporte, informe o request_id.

Rastreamento

Mande o header W3C traceparent e o Falia continua o mesmo trace: ele volta em X-Trace-Id e segue nos webhooks gerados pela operação.

Boas práticas

• Use Idempotency-Key em todo envio feito por automação (vale por 24 h).
• Respeite o 429: espere e tente de novo, com espaçamento.
• Mensagens em massa são o principal motivo de bloqueio de número pelo WhatsApp. Envie só para quem conversa com a empresa.