Visão geral

O Planoit é a plataforma interna de mensageria da aviait. Qualquer aplicação do grupo (ou integração de terceiros autorizada) chama uma única API para disparar e-mail, Telegram ou (em breve) WhatsApp, sem precisar falar diretamente com o provedor de cada canal.

Como funciona

1. Sua aplicação envia POST /v1/messages com o canal, o destinatário e o template a usar.
2. O Planoit aceita e enfileira a mensagem — a API não renderiza nem envia de forma síncrona dentro do ciclo da requisição. A resposta 202 só confirma que a mensagem entrou na fila.
3. Um worker separado reivindica a mensagem, renderiza o template com o payload enviado e chama o provedor do canal (SMTP, Bot API do Telegram, etc.).
4. Sucesso ou falha ficam registrados internamente (telemetria de uso); a aplicação que disparou não recebe webhook de status hoje — consulte o painel administrativo (backoffice) se precisar acompanhar.

Aplicações, API keys e templates

• Cada aplicação cadastrada no Planoit tem um ou mais templates por canal (templateSlug + channel), versionados.
• O envio é autenticado por API key — veja Autenticação.
• Templates podem ser específicos da sua aplicação ou globais da plataforma (fallback automático quando a aplicação não tem um template próprio com aquele slug).

Idempotência

Todo POST /v1/messages exige o header Idempotency-Key. Reenviar a mesma chave para a mesma aplicação devolve o mesmo id e status da primeira chamada, sem criar uma segunda mensagem — seguro para retry automático em caso de timeout de rede.

O que a API não faz

• Não é um canal de atendimento/conversa: é disparo avulso (fire-and-forget). Nenhum canal suportado hoje lê resposta do destinatário.
• Não processa envio em lote (lista de destinatários) — cada chamada envia para um destinatário.
• Não reenvia webhooks de status de entrega para quem chamou a API.