Integração de notificações de terceiros

Início rápido

No painel Web, crie um aplicativo de terceiros vinculado à empresa desejada. Copie o App ID e o App Secret e, se precisar do resultado final, configure um Callback URL opcional. O Engine cria uma entrada na central de notificações para cada usuário ativo elegível da empresa e só tenta o Push do sistema em dispositivos registrados elegíveis.

Endpoint e autenticação

Ambientes da API:

• Teste: https://aim-api-test.proton-system.com
• Produção: https://aim-api.proton-system.com

Cada solicitação JSON entre servidores deve incluir Authorization: Basic Base64(KEY:SECRET) por meio de HTTP Basic Authentication, em que KEY é o App ID e SECRET é o App Secret:

Endpoint: POST /openapi/v1/notifications.

curl --request POST 'https://<your-engine-host>/openapi/v1/notifications' \
  --header 'Authorization: Basic <Base64(AppID:AppSecret)>' \
  --header 'Content-Type: application/json' \
  --data '{"requestId":"order-20260819-001","title":"Pedido concluído","body":"Seu pedido foi concluído.","imageUrls":["https://cdn.example.com/order/001-1.webp","https://cdn.example.com/order/001-2.webp"]}'

Contrato da solicitação

O JSON estrito aceita os campos obrigatórios requestId, title e body, além do imageUrls opcional. Omitir imageUrls, ou enviar null ou [], significa que não há imagens; caso contrário, envie 1-9 URLs na ordem de exibição. Cada valor é aparado, deve ser único, precisa ser uma URL HTTPS absoluta sem usuário nem senha e pode ter no máximo 2048 caracteres Unicode. Uma URL inválida rejeita toda a solicitação. O Engine armazena as URLs, mas não busca, verifica, atua como proxy nem mantém as imagens em cache. O corpo completo é limitado a 256 KiB: requestId permite 128 caracteres Unicode, title 100 e body 1000. Cada App ID permite 10 solicitações por minuto e 100 por hora.

Repetir o mesmo requestId com title, body e imageUrls ordenados iguais retorna o resultado original armazenado; depois do processamento, o status pode ser SUCCESS, PARTIAL_SUCCESS ou FAILED em vez de ACCEPTED. Reutilizar o requestId com conteúdo ou ordem de imagens diferente retorna IDEMPOTENCY_CONFLICT.

Resposta de aceitação

Uma solicitação válida retorna HTTP 202:

{
  "requestId": "order-20260819-001",
  "notificationId": "00000000-0000-0000-0000-000000000001",
  "status": "ACCEPTED"
}

ACCEPTED significa apenas que o Engine guardou a solicitação para envio, não que APNs/FCM ou o dispositivo exibiram a notificação.

Resultado do Callback

Com Callback URL configurado, o Engine envia o resultado final:

{
  "requestId": "order-20260819-001",
  "status": "PARTIAL_SUCCESS",
  "recipientCount": 8,
  "pushAcceptedCount": 1,
  "pushFailedCount": 1
}

recipientCount é o número de usuários destinatários da central de notificações. pushAcceptedCount e pushFailedCount são contagens de lotes do Push Outbox, não contagens de usuários ou dispositivos nem prova de entrega do banner do sistema.

Teste de Callback

Cada teste de Callback do painel administrativo envia uma sonda distinta:

{
  "requestId": "callback-test-<unique-id>",
  "status": "SUCCESS",
  "recipientCount": 1,
  "pushAcceptedCount": 1,
  "pushFailedCount": 0,
  "test": true
}

Quando test for true, valide a estrutura e responda com 2xx, mas não associe a sonda a uma solicitação de notificação nem atualize o estado de entrega do negócio. As contagens são valores fixos de teste, não destinatários nem lotes reais do Push Outbox.

O status final é SUCCESS, PARTIAL_SUCCESS ou FAILED. Responda com qualquer 2xx; caso contrário, haverá novas tentativas após 1 minuto, 5 minutos, 30 minutos, 2 horas, 6 horas e 24 horas. Atualmente não existe assinatura HMAC: exija HTTPS, confira o requestId dos resultados que não sejam de teste, restrinja a exposição e processe o Callback de forma idempotente.

Referência de erros

Segurança e escopo de envio

O cliente móvel aceita no máximo 5 MiB por imagem e limita a operação completa de download da imagem a 10 segundos. Ele não segue redirecionamentos 3xx, portanto cada URL deve retornar a imagem diretamente.

App ID e App Secret são credenciais entre servidores. Nunca use navegador, aplicativo móvel, repositório público, URL ou armazenamento do cliente. Redefina o App Secret se houver exposição. Cada usuário ativo elegível da empresa vinculada recebe uma entrada na central de notificações e é contado em recipientCount. O Push do sistema só é tentado em dispositivos com um PushInstallation ativo que permita a categoria BUSINESS, sem garantir um banner em todos os dispositivos. imageUrls aparece somente no detalhe da notificação e não entra nos payloads de Push ou Callback. title e body devem permanecer completos e compreensíveis sem as imagens. Falhas ao baixar ou renderizar imagens não alteram o status de accepted, Callback ou Push. O cliente móvel baixa cada imagem diretamente do CDN público; use URLs sem autenticação nem cookies, mantenha-as disponíveis por pelo menos 90 dias e considere que o CDN recebe o IP, o horário da solicitação e o User-Agent do usuário. Prefira URLs de objetos imutáveis quando a exibição histórica precisar permanecer estável.