API pública — organização e campanhas (v1) | Documentações

Visão geral

A API pública /api/v1/campaigns destina-se a integradores (ex.: n8n). O envio real ocorre fora do request HTTP: a aplicação insere linhas na fila Postgres (campaign_send_job) e o processo pnpm worker:campaign consome com SKIP LOCKED.

Autenticação: header Authorization: Bearer <chave> onde a chave é criada em Configurações da organização → Chaves de API (plano Professional).
Identificadores: campanhas e templates usam des_public_uuid (UUID v7) na API; IDs numéricos não são expostos nestes endpoints.
Compliance (MVP): listas, consentimento e base legal ficam no CRM/automação do cliente; o OSBChat expõe apenas o canal técnico de envio.

Documentação relacionada

Campanhas no painel — assistente de nova campanha, agendar, cancelar e ver o envio na conversa (utilizadores do painel).

Idempotência

Nos POST de criar campanha, destinatários e init, envie opcionalmente o header Idempotency-Key. Requisições repetidas com a mesma chave devolvem a mesma resposta gravada (quando já processada).

Endpoints

Método	Caminho	Descrição
`POST`	`/api/v1/campaigns`	Cria campanha (`des_name`, `integration_uuids[]`, opcional `message_template_uuid`, `tis_scheduled`, `des_status`).
`GET`	`/api/v1/campaigns/{campaign_uuid}`	Status e totais.
`PATCH`	`/api/v1/campaigns/{campaign_uuid}`	Edita rascunho/agendada (`des_name`, `tis_scheduled`, `des_status`).
`POST`	`/api/v1/campaigns/{campaign_uuid}/recipients`	Corpo `{ "recipients": [ { "des_phone", "des_name", "des_variables", "id_contact" } ] }` (somente rascunho).
`POST`	`/api/v1/campaigns/{campaign_uuid}/init`	Marca disparo e enfileira jobs na Postgres.
`POST`	`/api/v1/campaigns/{campaign_uuid}/cancel`	Cancela envios ainda não processados.

integration_uuids são os UUID públicos das integrações (mesmo valor exibido na tela da integração).

Agendamento interno

Campanhas com des_status = scheduled e tis_scheduled no futuro são marcadas como running e recebem jobs quando o cron (ou chamada manual) aciona POST /api/campaign/process-scheduled (autenticação de serviço ou sessão).

Worker e e-mail

Rode pnpm worker:campaign em produção (processo separado do worker BullMQ principal).
Integrações cujo tipo é e-mail geram job que falha com mensagem explícita até existir pipeline SMTP (stub).

Anexos e mídia (roadmap)

Para anexos em massa: validar URL (mitigar SSRF), limite de bytes, MIME permitido e, para base64, armazenamento temporário com TTL. Alinhar ao tipo de canal (template documento Meta vs mídia Baileys) antes de expor na API.

Exemplo n8n (curl)

Substitua BASE, OSBC_KEY, INT_UUID e, se houver, TMPL_UUID.

curl -sS -X POST "$BASE/api/v1/campaigns" \
  -H "Authorization: Bearer $OSBC_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: create-demo-001" \
  -d "{\"des_name\":\"Demo API\",\"integration_uuids\":[\"$INT_UUID\"],\"message_template_uuid\":\"$TMPL_UUID\"}"

Resposta inclui campaign_uuid. Em seguida:

curl -sS -X POST "$BASE/api/v1/campaigns/$CAMP_UUID/recipients" \
  -H "Authorization: Bearer $OSBC_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: recipients-demo-001" \
  -d "{\"recipients\":[{\"des_phone\":\"5511999999999\",\"des_name\":\"Teste\",\"des_variables\":{\"nome\":\"Teste\"}}]}"

curl -sS -X POST "$BASE/api/v1/campaigns/$CAMP_UUID/init" \
  -H "Authorization: Bearer $OSBC_KEY" \
  -H "Idempotency-Key: init-demo-001"

Erros comuns

401 Unauthorized: Bearer ausente, chave revogada/expirada ou plano abaixo de Professional.
404: UUID de campanha, integração ou template não pertence à organização da chave.
400: corpo inválido ou operação em campanha que não está em rascunho (ex.: destinatários).

Gateway e rate limit

Rate limiting na borda (Kong ou similar) fica fora do MVP; documente limites no integrador até haver gateway dedicado.