Introdução

Nuntis

O Nuntis é o serviço de mensageria multicanal da Devari. Ele envia e recebe mensagens por múltiplos canais e múltiplos números, sob um contrato de API estável, para que o seu produto não precise resolver isso por conta própria.

O nome vem do latim nuntius, o mensageiro — aquele que falava em nome de outro, nunca por si. As duas propriedades do cargo são as duas propriedades do serviço, e vale desenhar a sua integração em torno delas:

• Ele fala em nome do seu produto, nunca por si. A mensagem é sua. O Nuntis não decide o que dizer, não guarda a sua regra de negócio e não é dono do conteúdo — ele empresta a voz.
• Ele entrega apesar do entorno. A entrega não pode depender de um canal estar bom ou de um número estar disponível. É daí que vêm multi-canal e multi-número: não são recursos extras, são a razão de existir.

O que dá para fazer

O resto — consultar histórico, parear um número, checar o que cada canal suporta — é apoio para essas três coisas.

Os canais

O canal não é um parâmetro que você passa. Ele é uma propriedade do número que envia: você informa o numberId, e o canal daquele número decide o caminho. O mesmo POST /v1/messages serve a todos.

A lista acima é um retrato. A fonte da verdade é GET /v1/channels, que declara, canal a canal, o que ele sabe fazer: tipos de mídia aceitos, se há janela de resposta, se exige template, e até onde vão os recibos.

O modelo

Cinco conceitos, encaixados. Entender o encaixe evita quase todo erro de integração:

seu produto            ← uma API key, o limite de tudo que você enxerga
   └── clientes        ← os clientes finais do SEU produto
        └── operadores ← quem atende (uma pessoa, um time, um bot)
             └── números  ← as linhas por onde se fala (cada uma tem um canal)
                  └── conversas → mensagens

Uma API key por produto

A key é o seu limite. Todo recurso que você lê ou escreve pertence ao seu produto, e recurso de outro produto responde 404 — nunca 403. Isso é deliberado: um 403 confirmaria que o recurso existe, e IDs adivinháveis transformariam a resposta num enumerador da base alheia.

Corolário prático: não crie uma key por cliente final. A separação entre os seus clientes é feita pelo modelo acima, não por credenciais. Uma key por produto, por ambiente.

Correlacionar com os seus próprios IDs

Todo identificador do Nuntis é opaco: msg_18273, num_4711, conv_991. Não os parseie, não ordene por eles, não infira nada do conteúdo — o formato interno pode mudar sem aviso. Guarde-os como texto.

Para ligar um recurso do Nuntis ao seu próprio registro, cada cliente, operador e número aceita um externalRef: uma string sua, única dentro do seu produto para aquele tipo de recurso. É por ela que você mapeia “o operador op_88 é o usuário 4711 no meu banco” sem manter uma tabela de tradução frágil.

Como começar

1. Receba a sua API key e os identificadores dos seus números.
2. Registre o seu webhook e guarde o segredo em cofre.
3. Implemente o receptor com corpo cru e verificação de assinatura.
4. Leia GET /v1/channels uma vez, no boot, e guarde a capacidade.
5. Envie com Idempotency-Key e guarde o id retornado.
6. Atualize o seu estado a partir dos eventos que chegarem no webhook.

Estabilidade do contrato

O contrato é versionado no caminho (/v1). Duas regras valem sempre:

• Acréscimo é livre. Campo novo, rota nova, código de erro novo e valor novo de enum podem aparecer a qualquer momento. Escreva o seu cliente para ignorar o que não conhece, nunca para quebrar.
• Mudança quebrante exige /v2 e plano de migração. Remover ou renomear campo, mudar o significado de um valor ou apertar uma validação não acontece debaixo de você.

Nuntis — serviço de mensageria multicanal da Devari.