# Sender — API de marketing

> Plataforma de mensagens da Ferreira Korp. Negócios enviam mensagens (SMS ou nativas Sender) a
> clientes com consentimento, de forma automática ou via agente de IA. Autenticação por API key.

Base URL: https://sender.ferreirakorp.com

## Obter uma API key
1. Cria conta em https://sender.ferreirakorp.com/app (email/telefone, sem password).
2. Ativa negócio em https://sender.ferreirakorp.com/negocio — copia a API key mostrada (só aparece uma vez).

## Autenticação
Todos os endpoints abaixo levam `Authorization: Bearer <api_key>`.

## Endpoints REST

### POST /api/v1/sms/enviar
Envia SMS em massa. Body: {"numeros": ["+244912345678"], "texto": "...", "confirmoConsentimento": true}
Limite: 300 destinos/pedido, 640 caracteres.

### POST /api/v1/gatilhos
Cria um webhook que dispara uma campanha ao ser chamado. Body: {"nome":"...", "template":"Olá {{nome}}...", "destinos":["+244..."]}
Devolve {"chave":"...", "urlDisparo":"/api/v1/gatilho/<chave>"}.

### POST /api/v1/gatilho/{chave}
Dispara o gatilho, preenchendo {{campos}} do template com o body JSON enviado. Sem autenticação
adicional — a própria chave (imprevisível, UUID) é o segredo.

### POST /api/v1/negocio/mensagem
Envia uma mensagem a quem segue o teu negócio DENTRO da app (canal nativo, tempo real). Body:
{"texto":"...", "emailsExtra":["opcional@exemplo.com"]}. O campo emailsExtra é a metade
"email-como-mensagem": a mesma mensagem sai também por email a quem ainda não está na Sender
(até 100 endereços). Exige que o destinatário siga o teu negócio para receber pelo canal nativo
— o email extra não depende disso.

### POST /api/v1/negocio/copy
Gera texto de campanha com o modelo de IA interno. Body: {"instrucao":"...", "tom":"casual|formal"}.
Devolve {"texto":"..."}. Se tiveres uma chave BYOM configurada em /negocio, usa o teu modelo em vez do interno.

### POST /api/v1/negocio/cobranca
Cria um link de pagamento hospedado pelo PayApp (a Sender nunca processa pagamentos
diretamente — só cria a cobrança e recebe a confirmação). Body: {"valorKz": 5000, "descricao":"...", "compradorEmail":"opcional"}.
Devolve {"id":"...", "url":"https://pay.ferreirakorp.com/checkout/...", "expira": 1234567890}.
Envia esse "url" ao teu cliente (por mensagem nativa, SMS, o que for). Quando pago, o negócio
é notificado dentro da app em tempo real — nada a fazer do lado da integração.

## Servidor MCP (para agentes de IA)
POST https://sender.ferreirakorp.com/mcp — JSON-RPC 2.0, mesma API key no header Authorization.
Ferramentas disponíveis: enviar_sms_em_massa, criar_gatilho_sms, disparar_gatilho,
enviar_mensagem_negocio, gerar_copy_campanha, criar_cobranca.

Exemplo de configuração MCP (Claude Desktop, Cursor, etc.):
{"mcpServers":{"sender":{"url":"https://sender.ferreirakorp.com/mcp","headers":{"Authorization":"Bearer sk_sender_..."}}}}

## Regras
- Consentimento é obrigatório e não é validado automaticamente — a responsabilidade é de quem
  ativa o negócio. Falso consentimento é motivo de suspensão da conta.
- Mensagens nativas Sender (negócio) e SMS são canais separados; escolhe o que fizer sentido —
  SMS chega a qualquer telemóvel, mensagem nativa só chega a quem já tem Sender instalada.