La API de notificaciones te permite recibir notificaciones en tiempo real de varios eventos de contenido en Prime Video, lo que elimina la necesidad de consultar reiteradamente las API de estado. Configura flujos de trabajo automatizados que respondan al instante a actualizaciones de entrega de recursos y cambios en el estado de las ofertas, lo que te permitirá resolver problemas con mayor rapidez y mantener tu catálogo actualizado.
¿Por qué usar la API de notificaciones?
- Detección de problemas en tiempo real: recibe notificaciones instantáneas cuando fallen las entregas de recursos o cambien los estados de las ofertas, lo que te permite abordar los problemas de inmediato en lugar de descubrirlos horas o días después mediante comprobaciones manuales.
- Reducción de la sobrecarga de la API: elimina la necesidad de consultar continuamente las API de estado, lo que reduce los costos de infraestructura y el volumen de llamadas a las API, sin dejar de mantener la información actualizada.
- Integración de flujo de trabajo automatizado: conecta las notificaciones directamente a tus sistemas existentes (servicios de AWS o webhooks) para activar respuestas automatizadas, creación de tickets o generar flujos de trabajo de alerta sin intervención manual.
- Cobertura integral de eventos: supervisa tanto el estado de entrega de los recursos como la disponibilidad de las ofertas en todos tus títulos y territorios desde un único sistema de notificaciones.
Primeros pasos
Para empezar a usar las notificaciones, solo tienes que seguir tres pasos:
- Registrar un destino: Configura dónde quieres recibir las notificaciones. Puedes elegir entre servicios de AWS (SQS, SNS, EventBridge) o webhooks HTTPS.
- Crear suscripciones: Asigna los eventos que quieres monitorear a tus destinos registrados. Cada suscripción abarca un tema (AssetStatus u OfferStatus), pero puedes suscribirte a varios tipos de eventos dentro de ese tema.
- Recibe notificaciones: Después de la configuración, recibirás automáticamente notificaciones a medida que los eventos ocurran en tiempo real.
Esquemas de solicitud y respuesta
En esta sección se proporcionan las especificaciones técnicas para que los desarrolladores integren la API de notificaciones de socios en tus sistemas. Usa esta referencia para entender el formato de la solicitud, la estructura de las respuestas y los tipos de datos que devuelve la API.
URL base
Todas las solicitudes de la API se envían a la siguiente URL base. Agrega la ruta del punto de conexión correspondiente a esta URL cuando realices solicitudes.
https://partnerapi.primevideo.com/v1
Administración de destinos
Un destino es el lugar donde deseas recibir las notificaciones; puede ser un servicio de AWS (SQS, SNS o EventBridge) o un punto de conexión de webhook HTTPS. Debes registrar al menos un destino antes de crear suscripciones.
Registrar destino
POST /{licensor}/notifications/targets
Crea un nuevo destino de notificaciones donde recibirás las notificaciones de eventos.
Cuerpo de la solicitud:
{
"type": "SQS|SNS|EVENTBRIDGE|WEBHOOK",
"destination": "target-destination",
"auth": { /* varies by type */ }
}
Respuesta:
{
"targetId": "target-id-1",
"status": "ACTIVE"
}
Enumerar todos los destinos
Utiliza este punto de conexión para recuperar una lista completa de los destinos de notificaciones registrados para tu organización. Esto es útil para auditar tu configuración actual o para identificar los ID de destino que se usarán al crear o actualizar suscripciones.
GET /{licensor}/notifications/targets
Recupera todos los destinos registrados de tu organización.
Obtener un destino específico
GET /{licensor}/notifications/targets?targetId={id}
Recupera los detalles de un destino específico.
Actualizar destino
PUT/{licensor}/notifications/targets/{targetId}
Actualiza una configuración de destino existente.
Eliminar destino
DELETE /{licensor}/notifications/targets/{targetId}
Elimina un destino de tu configuración.
Administración de suscripciones
Una suscripción asigna uno o más eventos a un destino registrado, lo que determina qué notificaciones recibes y dónde se entregan. Cada suscripción se limita a un solo tema, pero puedes crear varias suscripciones para cubrir todos los eventos relevantes para tu flujo de trabajo.
Crear suscripción
POST /{licensor}/notifications/subscriptions
Crea una suscripción para asignar eventos a tus destinos.
Cuerpo de la solicitud:{
"topic": "OfferStatus",
"eventTargetMapping": {
"LiveStatusUpdated": ["target-id-1"],
"OfferStatusUpdated": ["target-id-2"]
}
}
Respuesta:{
"subscriptionId": "subscription-id-1",
"status": "ACTIVE"
}
Enumerar todas las suscripciones
GET /{licensor}/notifications/subscriptions
Recupera todas las suscripciones de tu organización.
Actualizar suscripción
PUT /{licensor}/notifications/subscriptions/{id}
Actualiza una configuración de suscripción existente.
Eliminar suscripción
DELETE /{licensor}/notifications/subscriptions/{id}
Elimina una suscripción de tu configuración.
Temas y eventos disponibles
Los temas agrupan los eventos relacionados. Cuando creas una suscripción, seleccionas un tema y especificas qué eventos de ese tema quieres monitorear. Cada tema se asigna a un área específica de seguimiento del estado del contenido.
- LiveStatusUpdated: cuando cambia el estado de disponibilidad
- OfferStatusUpdated: cuando cambia el estado de la oferta (Próximamente)
- AssetStatusUpdated: cuando cambia el estado del recurso (Próximamente)
Tipos de destinos
Los tipos de destino definen cómo Prime Video envía notificaciones a tus sistemas. Puedes elegir entre los servicios gestionados por AWS para una entrega confiable y escalable o configurar un webhook HTTPS para recibir las notificaciones directamente en tu propio punto de conexión.
Destinos de AWS (SQS, SNS, EventBridge) - campos obligatorios:
- destination: ARN del recurso de AWS
- assumeRoleArn: rol de IAM para la entrega
- externalId: identificador de seguridad (opcional, pero recomendado)
Ejemplo de SQS:{
"type": "SQS",
"destination": "arn:aws:sqs:{region}:{account-id}:{queue-name}",
"auth": {
"assumeRoleArn": "arn:aws:iam::{account-id}:role/{role-name}",
"externalId": "{external-id}"
}
}
Ejemplo de SNS:{
"type": "SNS",
"destination": "arn:aws:sns:{region}:{account-id}:{topic-name}",
"auth": {
"assumeRoleArn": "arn:aws:iam::{account-id}:role/{role-name}",
"externalId": "{external-id}"
}
}
Ejemplo de EventBridge:{
"type": "EVENTBRIDGE",
"destination": "arn:aws:events:{region}:{account-id}:event-bus/{bus-name}",
"auth": {
"assumeRoleArn": "arn:aws:iam::{account-id}:role/{role-name}",
"externalId": "{external-id}"
}
}
Destinos de webhook - token portador:{
"type": "WEBHOOK",
"destination": "https://your-api.example.com/webhooks",
"auth": {
"type": "bearer",
"bearerToken": "your-token"
}
}
Destinos de webhook - clave de API:{
"type": "WEBHOOK",
"destination": "https://your-api.example.com/webhooks",
"auth": {
"type": "apiKey",
"apiKey": "your-key",
"apiKeyHeader": "X-API-Key"
}
}
Destinos de webhook - HMAC (recomendado):{
"type": "WEBHOOK",
"destination": "https://your-api.example.com/webhooks",
"auth": {
"type": "hmac",
"hmacSecret": "your-secret",
"hmacAlgorithm": "HmacSHA256",
"hmacHeader": "X-Signature"
}
}
Carga útil
Los webhooks reciben solicitudes HTTP POST con la siguiente carga útil:{
"alid": "partner-listing-id",
"territory": "US",
"marketplace": "US",
"eventType": "LiveStatusUpdated",
"callbackUrl": "https://callback-url.com",
"eventTimestamp": "2024-01-01T00:00:00.000Z"
}
Encabezados de autenticación:
- HMAC: X-Signature: {signature}
- Clave de API: Clave de X-API:{key}
- Portador: Autorización: Portador {token}
Respuestas de error
Cuando no se puede completar una solicitud, la API devuelve una respuesta de error estructurada para ayudarte a identificar y resolver el problema. La respuesta incluye un código de error y un mensaje legible que describe el problema.{
"error": {
"code": "ERROR_CODE",
"message": "Human readable error message"
}
}
Códigos de error comunes:
- BAD_REQUEST: parámetros de solicitud no válidos
- UNAUTHORIZED: error de autenticación
- NOT_FOUND: recurso no encontrado
- CONFLICT: el recurso ya existe
Guía de configuración de destinos de AWS
Si utilizas un servicio de AWS (SQS, SNS o EventBridge) como destino de notificaciones, debes configurar un rol de entrega de IAM para otorgar permiso a Prime Video para entregar notificaciones a tus recursos de AWS. Sigue los pasos que se indican a continuación para configurar el rol de IAM y las políticas de permisos necesarios antes de registrar tu destino.
Requisitos previos
- Recurso de destino de AWS (cola de SQS, tema de SNS o bus de EventBridge)
- Rol de entrega de IAM con políticas de confianza y permisos
Configuración de rol de IAM
1. Crear rol: Consola de AWS → IAM → Roles → Crear rol → Política de confianza personalizada
2. Política de confianza{
"Version": "2012-10-17",
"Statement": [{
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::687801838843:role/PVPartnerApiNotificationP-EcsTaskInstanceRoleE38DB4-qWjKHaQBhouq"
},
"Action": "sts:AssumeRole",
"Condition": {
"StringEquals": {
"sts:ExternalId": "{external-id}"
}
}
}]
}
3. Política de permisos (elige una de las siguientes opciones)
SQS:{
"Version": "2012-10-17",
"Statement": [{
"Effect": "Allow",
"Action": ["sqs:SendMessage", "sqs:GetQueueUrl"],
"Resource": "arn:aws:sqs:{region}:{account-id}:{queue-name}"
}]
}
SNS:{
"Version": "2012-10-17",
"Statement": [{
"Effect": "Allow",
"Action": "sns:Publish",
"Resource": "arn:aws:sns:{region}:{account-id}:{topic-name}"
}]
}
EventBridge: {
"Version": "2012-10-17",
"Statement": [{
"Effect": "Allow",
"Action": "events:PutEvents",
"Resource": "arn:aws:events:{region}:{account-id}:event-bus/{bus-name}"
}]
}
