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 publicación, lo que te permitirá resolver problemas con mayor rapidez y mantener tu catálogo actualizado.
Detección de problemas en tiempo real: recibe notificaciones instantáneas cuando fallen las entregas de recursos o cambien los estados de publicación, 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 el estado de publicación de 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.
- Recibir notificaciones: Después de la configuración, recibirás automáticamente notificaciones a medida que los eventos ocurran en tiempo real.
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.
LiveStatusUpdated
Tema: OfferStatus
Te notifica cuando cambia el estado de publicación de un título en la tienda de Prime Video, es decir, cuando un título se publica o deja de estar publicado.
¿Qué activa esta notificación? Cuando cambia el estado de publicación o de no publicación de un título en la tienda. Usa la callbackUrl en la carga útil para obtener los detalles completos del estado de la oferta mediante la API de Offer Status.
Carga útil:{
"alid": "partner-listing-id",
"territory": "US",
"marketplace": "US",
"partnerAlias": "partner-alias",
"eventType": "LiveStatusUpdated",
"callbackUrl": "https://partnerapi.primevideo.com/v1/avails/{partnerAlias}/status/{alid}?marketplace={marketplace}&territory={territory}",
"eventTimestamp": "2024-01-01T00:00:00.000Z"
}
AssetStatusUpdated
Tema: AssetStatus
Te notifica cuando un recurso alcanza un resultado de entrega final. Se envía una notificación cuando el estado de un recurso pasa a ser:
- Gestionado: el recurso se entregó correctamente, o
- Fallido: el recurso no se pudo entregar o requiere atención.
¿Qué activa esta notificación? Un cambio en el estado de entrega de un recurso (por ejemplo, video, audio, subtítulos o material gráfico). Usa la callbackUrl para obtener el estado de entrega completo del recurso, incluida la información detallada del error cuando corresponda.
Casos de uso:
- Detecta fallas de entrega en tiempo real y activa flujos de trabajo de reentrega automatizados
- Confirma que el procesamiento de recursos se completó sin consultar la API de Asset Status
- Intégrala con sistemas internos de tickets para resolver problemas de inmediato
Carga útil:{
"alid": "partner-listing-id",
"marketplace": "US",
"partnerAlias": "partner-alias",
"eventType": "AssetStatusUpdated",
"callbackUrl": "https://partnerapi.primevideo.com/v1/assets/{partnerAlias}/status/{alid}?marketplace={marketplace}",
"eventTimestamp": "2024-01-01T00:00:00.000Z"
}
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"]
}
}
{
"topic": "AssetStatus",
"eventTargetMapping": {
"AssetStatusUpdated": ["target-id-1"]
}
}
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.
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}"
}
}
Token portador:{
"type": "WEBHOOK",
"destination": "https://your-api.example.com/webhooks",
"auth": {
"type": "bearer",
"bearerToken": "your-token"
}
}
Clave de API:{
"type": "WEBHOOK",
"destination": "https://your-api.example.com/webhooks",
"auth": {
"type": "apiKey",
"apiKey": "your-key",
"apiKeyHeader": "X-API-Key"
}
}
HMAC (recomendado):{
"type": "WEBHOOK",
"destination": "https://your-api.example.com/webhooks",
"auth": {
"type": "hmac",
"hmacSecret": "your-secret",
"hmacAlgorithm": "HmacSHA256",
"hmacHeader": "X-Signature"
}
}
Carga útil
Estructura de carga útil
Todas las cargas útiles de notificaciones siguen una estructura consistente:
Campo |
Descripción |
|---|---|
ALID |
Identificador de listado del socio (identificador del título) |
territory |
Código de territorio (p. ej., EE. UU., GB) |
marketplace |
Código del sitio web |
PartnerAlias |
Identificador de socio |
eventType |
El evento específico que ocurrió |
callbackUrl |
URL para obtener los detalles completos del estado |
eventTimestamp |
Marca de tiempo ISO 8601 del evento |
Los webhooks reciben solicitudes HTTP POST con la siguiente carga útil:{
"alid": "partner-listing-id",
"territory": "US",
"marketplace": "US",
"partnerAlias": "partner-alias",
"eventType": "LiveStatusUpdated",
"callbackUrl": "https://callback-url.com",
"eventTimestamp": "2024-01-01T00:00:00.000Z"
}
Encabezados de autenticación:
- HMAC: X-Signature: {signature}X-Signature: {signature}
- Clave de API: Clave de X-API: {key}Clave de X-API: {key}
- Portador: Autorización {token}del portador: 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:root"
},
"Action": "sts:AssumeRole",
"Condition": {
"StringEquals": {
"sts:ExternalId": "{external-id}"
},
"ArnLike": {
"aws:PrincipalArn": "arn:aws:iam::687801838843:role/PVPartnerApiNPS-ExecutionRole-*"
}
}
}
]
}
3. Política de permisos (elige una):
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}"
}]
}
