Integración de notificaciones de terceros

Inicio rápido

Crea en la administración web una aplicación vinculada a la empresa de destino. Copia su App ID y App Secret y, si necesitas el resultado final, configura un Callback URL opcional. Engine crea una entrada en el centro de notificaciones para cada usuario activo válido de la empresa y solo intenta el Push del sistema en dispositivos registrados que cumplan los requisitos.

Endpoint y autenticación

Entornos de API:

• Pruebas: https://aim-api-test.proton-system.com
• Producción: https://aim-api.proton-system.com

Cada solicitud JSON de servidor a servidor debe incluir Authorization: Basic Base64(KEY:SECRET) mediante HTTP Basic Authentication, donde KEY es el App ID y SECRET es el 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 completado","body":"Tu pedido se ha completado.","imageUrls":["https://cdn.example.com/order/001-1.webp","https://cdn.example.com/order/001-2.webp"]}'

Contrato de solicitud

El JSON estricto admite los campos obligatorios requestId, title y body, además del campo opcional imageUrls. Omitir imageUrls, o enviar null o [], significa que no hay imágenes; en caso contrario, envía 1-9 URL en el orden de visualización. Cada valor se recorta, debe ser único, debe ser una URL HTTPS absoluta sin usuario ni contraseña y puede tener como máximo 2048 caracteres Unicode. Una URL no válida rechaza toda la solicitud. Engine almacena las URL, pero no obtiene, comprueba, sirve como proxy ni almacena en caché las imágenes. El cuerpo completo está limitado a 256 KiB: requestId admite 128 caracteres Unicode, title 100 y body 1000. Cada App ID permite 10 solicitudes por minuto y 100 por hora.

Repetir el mismo requestId con los mismos title, body e imageUrls ordenados devuelve el resultado original almacenado; después del procesamiento, su status puede ser SUCCESS, PARTIAL_SUCCESS o FAILED en lugar de ACCEPTED. Reutilizar el requestId con contenido u orden de imágenes distinto devuelve IDEMPOTENCY_CONFLICT.

Respuesta de aceptación

Una solicitud válida devuelve HTTP 202:

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

ACCEPTED solo indica que Engine guardó la solicitud para distribuirla; no confirma que APNs/FCM ni el dispositivo hayan mostrado la notificación.

Resultado del Callback

Con Callback URL configurado, Engine envía un resultado terminal:

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

recipientCount es el número de usuarios destinatarios del centro de notificaciones. pushAcceptedCount y pushFailedCount son recuentos de lotes de Push Outbox, no recuentos de usuarios o dispositivos ni prueba de entrega del banner del sistema.

Prueba de Callback

Cada prueba de Callback del panel de administración envía una sonda distinta:

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

Cuando test sea true, valida la estructura y responde con 2xx, pero no relaciones la sonda con una solicitud de notificación ni actualices el estado de entrega del negocio. Sus recuentos son valores fijos de prueba, no destinatarios ni lotes reales de Push Outbox.

El status final es SUCCESS, PARTIAL_SUCCESS o FAILED. Responde con cualquier 2xx; si no, Engine reintenta tras 1 minuto, 5 minutos, 30 minutos, 2 horas, 6 horas y 24 horas. Actualmente no hay firma HMAC: exige HTTPS, valida el requestId de los resultados que no sean de prueba, limita la exposición y procesa cada Callback de forma idempotente.

Referencia de errores

Seguridad y ámbito de envío

El cliente móvil acepta como máximo 5 MiB por imagen y concede 10 segundos a toda la operación de descarga de la imagen. No sigue redirecciones 3xx, por lo que cada URL debe devolver la imagen directamente.

App ID y App Secret son credenciales entre servidores. No las incluyas en navegador, aplicación móvil, repositorio público, URL ni almacenamiento del cliente. Restablece App Secret si se filtra. Cada usuario activo válido de la empresa vinculada recibe una entrada en el centro de notificaciones y se cuenta en recipientCount. El Push del sistema solo se intenta en dispositivos con un PushInstallation activo que permita la categoría BUSINESS, sin garantizar un banner en cada dispositivo. imageUrls solo se muestra en el detalle de la notificación y no se incluye en las cargas de Push ni Callback. title y body deben seguir siendo completos y comprensibles sin las imágenes. Un fallo al descargar o mostrar una imagen no cambia el estado de accepted, Callback ni Push. El cliente móvil descarga cada imagen directamente del CDN público: usa URL sin autenticación ni cookies, mantenlas disponibles al menos 90 días y considera que el CDN recibe la IP, la hora de solicitud y el User-Agent del usuario. Usa URL de objetos inmutables si necesitas una visualización histórica estable.