# 4send

> API do 4send: WhatsApp + e-mail transacional, contatos, tags, campos personalizados e fluxos (jornadas automáticas). Base URL: https://api.4send.me/v1 · Auth: cabeçalho `Authorization: Bearer <api_key>` (chaves 4s_test_ = sandbox, 4s_live_ = produção). Envio é assíncrono (202 + status; resultado por webhook ou GET /messages/{id}). **API servidor-a-servidor: chame do backend, nunca do navegador — a key é um segredo e chamada com 4s_live_ vinda do navegador é recusada com 403.**

## Documentação
- [Documentação completa (um arquivo, para IA)](https://docs.4send.me/llms-full.txt): toda a referência da API num arquivo só.
- [Especificação OpenAPI 3.1](https://docs.4send.me/claude-skill/openapi.yaml): spec da API para ferramentas.
- [Contexto Claude Code — SKILL.md](https://docs.4send.me/claude-skill/SKILL.md): pacote pra contextualizar o Claude Code sobre a API.
- [Exemplos de código](https://docs.4send.me/claude-skill/examples.md): curl, Node.js e Python.
- [Webhooks e verificação de assinatura](https://docs.4send.me/claude-skill/webhooks.md): eventos e HMAC.

## Endpoints (base: https://api.4send.me/v1)
- POST /messages: enviar WhatsApp ou e-mail (transacional).
- GET /messages/{id}: status de uma mensagem (queued/sent/delivered/read/failed).
- POST /contacts: criar/atualizar contato (dedup por telefone, depois e-mail).
- GET /contacts, GET /contacts/{id}: buscar contatos.
- POST /flows/{flow_id}/enroll: colocar um contato num fluxo.
- POST /flows/{flow_id}/unenroll: tirar um contato do fluxo (para de receber o resto). `flow_id: all` tira de TODAS as jornadas — é o caso "comprou, para tudo". Idempotente.
- GET /flows: listar fluxos ativos.
- POST /tags, GET /tags: tags.
- POST /custom-fields, GET /custom-fields: campos personalizados (viram {{variaveis}}).
- GET /usage: consumo do mês.

## Notas
- **Onde chamar:** só do servidor (backend). A key é um segredo — no navegador ela fica visível pra qualquer visitante da página. `4s_live_` vindo do navegador é recusado com 403 (detectado pelo cabeçalho `Origin`); `4s_test_` é liberado no navegador por ser sandbox. Montando um conector dentro de um produto: guarde a key no seu backend e chame de lá.
- Idempotência: cabeçalho `Idempotency-Key` em POST /messages e /flows/{id}/enroll (retenção 24h).
- Erros: `{ "error": { "type", "message", "param", "doc_url" } }` com o status HTTP correto.
- Limite: ~120 req/min por chave (429 com cabeçalhos RateLimit-*).
- Webhooks assinados em `X-4send-Signature: t=<ts>,v1=<hmac_sha256(ts + "." + corpo_cru)>`.