API do Notifica WS Órbita

Como funciona

O Notifica é um serviço com um número compartilhado por várias lojas e um catálogo fechado de avisos utilitários de pedido. Você não escreve o texto da mensagem: escolhe, na adesão, quais eventos do catálogo a sua loja emite, e manda os dados de cada um. O nome da sua loja entra em toda mensagem.

Exemplo do que o cliente recebe: "Olá Ana! Seu pedido 1234 na Loja Exemplo foi enviado por Correios. Rastreio: AA123456789BR."

Endereço e autenticação

https://notifica.wsorbita.com/v1

A credencial vai no cabeçalho:

Authorization: Bearer wso_live_a1b2c3d4_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Credenciais começam com wso_test_ ou wso_live_. A de teste valida tudo, não gasta mensagem e não chega em ninguém: use ela durante a integração inteira. Os webhooks saem normalmente, marcados com "mode": "test".

Catálogo de eventos

Todo evento recebe nome e pedido em data; loja vem do seu cadastro. A tabela mostra os campos extras e o texto exato que o cliente recebe (*asteriscos* viram negrito no WhatsApp). Nos eventos com link opcional, mandar um link (https) acrescenta o botão "Acompanhar entrega"; sem ele, sai a versão sem botão. GET /v1/events devolve só os que estão ligados para a sua loja.

Os campos são texto livre, do jeito que o cliente deve ler ("total": "R$ 150,00", "previsao": "hoje até 18h"). Não interpretamos nem formatamos. Precisa de um evento que não está aqui? Fale conosco: o catálogo cresce, e o evento novo fica disponível para todas as lojas.

Enviar

POST /v1/notify

curl -X POST https://notifica.wsorbita.com/v1/notify \
  -H "Authorization: Bearer $NOTIFICA_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-1234-enviado-5541988721661" \
  -d '{
    "event": "pedido_enviado",
    "to": "5541988721661",
    "data": { "nome": "Ana", "pedido": "1234",
              "transportadora": "Correios", "rastreio": "AA123456789BR" },
    "reference": "pedido:1234",
    "consent": {
      "granted_at": "2026-08-29T12:00:00Z",
      "source": "checkout",
      "text": "Quero receber avisos deste pedido no WhatsApp pelo Notifica WS Órbita"
    }
  }'

Resposta 202:

{ "id": "msg_8842", "status": "queued", "to": "5541988721661",
  "event": "pedido_enviado", "reference": "pedido:1234", "mode": "live" }

Idempotência

Mande o cabeçalho Idempotency-Key com um valor estável e com o telefone dentro: pedido-1234-enviado-5541988721661. Mesma chave e mesmo corpo em até 24 horas devolvem a resposta original sem enviar de novo; mesma chave com corpo diferente devolve 409. Sem o cabeçalho, um retry de rede vira uma segunda mensagem.

Os eventos pagamento_pendente_pix e pagamento_pendente_boleto têm uma trava a mais: saem uma única vez por pedido (reference), independentemente do cabeçalho. Repetição devolve 409 already_sent.

Consentimento

O consentimento é por loja: quem aceitou avisos da sua loja não aceitou da loja ao lado, mesmo que o número de envio seja o mesmo. Registre no momento em que a pessoa aceita:

POST /v1/consent
{ "to": "5541988721661", "status": "granted",
  "source": "checkout", "text": "Quero receber avisos no WhatsApp pelo Notifica WS Órbita" }

Quem responder PARAR ao número é removido de todas as lojas de uma vez: a pessoa está bloqueando o número, não a sua loja. Tentar enviar depois devolve 403 recipient_opted_out. Se ela voltar a aceitar no seu checkout, um novo granted reabre só para a sua loja.

Respostas do cliente

O número do Notifica não é atendido. Quem responde recebe, uma vez por dia, uma mensagem automática dizendo isso e apontando o contato da sua loja (o que você informou na adesão). A resposta chega para você no webhook message.inbound, com o texto: se houver algo a fazer, é do seu lado.

Receber de volta (webhooks)

Registramos a sua URL na adesão (ou depois, a pedido). Enviamos POST com JSON e assinatura:

{ "event": "message.delivered", "at": "2026-08-29T12:00:03Z",
  "id": "msg_8842", "reference": "pedido:1234",
  "to": "5541988721661", "mode": "live" }

Como conferir a assinatura

Cabeçalhos: X-Orbita-Event, X-Orbita-Delivery, X-Orbita-Timestamp e X-Orbita-Signature. A assinatura é HMAC-SHA256 de timestamp + "." + corpo, com o segredo do webhook, em hexadecimal:

const assinatura = crypto
  .createHmac('sha256', SEGREDO)
  .update(`${timestamp}.${corpoBruto}`)
  .digest('hex')
// compare com o header, sem o prefixo "sha256="

Responda 2xx rápido. Outro código conta como falha e tentamos de novo em 1, 5, 15, 60 e 360 minutos. Depois de 20 falhas seguidas o endpoint é desligado e avisamos você.

Consultar

Erros

{ "error": { "code": "consent_required", "message": "..." } }

Pacote de mensagens

O serviço é pré-pago: sua loja contrata um pacote de N mensagens por mês fechado (1 a 30/31). Pacotes contratados no mesmo mês somam; o que não for usado não passa para o mês seguinte. Conta mensagem aceita (202) de credencial de produção; a credencial de teste não consome. Esgotou, a API devolve 403 package_exhausted e a mensagem não sai nem fica em fila. GET /v1/health mostra o consumo (package: contratado, usado, restante) para o seu sistema acompanhar.

Limites e boas práticas

• Cada loja tem limite por minuto e cota diária, somando todas as suas credenciais. Começam baixos e sobem conforme a qualidade dos envios.
• O número é compartilhado, e a reputação dele na Meta é uma só. Uma loja com muitas falhas (número inexistente, telefone fixo) ou muitos pedidos de saída é pausada automaticamente para não prejudicar as outras. Valide o telefone no seu checkout.
• Existe um teto por destinatário, somando todas as lojas. Um número não pode virar alvo só porque o formulário que colhe telefone é aberto.
• Consentimento e opt-out são checados antes dos tetos. 403 é proibição, não fila.
• Só sai o que está no catálogo. Não há texto livre, não há promoção: promoção é marketing e tem outro regime.
• Mande sempre reference. É o que torna o webhook útil sem você guardar os nossos ids.