A API de notificações permite que você receba notificações em tempo real para vários eventos de conteúdo no Prime Video, eliminando a necessidade de pesquisar repetidamente as APIs de status. Configure fluxos de trabalho automatizados que respondam instantaneamente às atualizações de entrega de ativos e às mudanças de status em tempo real, permitindo que você resolva problemas com mais rapidez e mantenha seu catálogo atualizado.
Detecção de problemas em tempo real — Receba notificações instantâneas quando as entregas de ativos falharem ou os status ao vivo mudarem, permitindo que você resolva os problemas imediatamente, em vez de descobri-los horas ou dias depois por meio de verificações manuais.
Redução da sobrecarga da API — Elimine a necessidade de pesquisa contínua das APIs de status, reduzindo seus custos de infraestrutura e o volume de chamadas de API e, ao mesmo tempo, mantendo as informações atualizadas.
Integração automatizada do fluxo de trabalho — conecte notificações diretamente aos seus sistemas existentes (serviços da AWS ou webhooks) para acionar respostas automatizadas, criação de tickets ou fluxos de trabalho de alertas sem intervenção manual.
Cobertura abrangente de eventos — monitore o status de entrega de ativos e o status ao vivo em todos os seus títulos e territórios a partir de um único sistema de notificação.
Começar a usar as notificações requer três etapas:
- Registre um alvo: configure onde você deseja receber notificações. Você pode escolher entre serviços da AWS (SQS, SNS, EventBridge) ou webhooks HTTPS.
- Criar assinaturas: mapeie os eventos que você deseja monitorar de acordo com suas metas registradas. Cada assinatura abrange um tópico (assetStatus ou offerStatus), mas você pode se inscrever em vários tipos de eventos dentro desse tópico.
- Receba notificações: depois de configurado, você receberá notificações automaticamente à medida que os eventos ocorrerem em tempo real.
Tópicos e eventos disponíveis
Os tópicos agrupam eventos relacionados. Ao criar uma assinatura, você seleciona um tópico e especifica quais eventos dentro desse tópico você deseja monitorar.
Tópico atualizado do LiveStatus: OfferStatus
Notifica você quando o status ao vivo de um título muda na vitrine do Prime Video, ou seja, quando um título é publicado ou não.
O que aciona essa notificação? O status ativo/não ativo de um livro muda na vitrine. Use o callbackURL na carga para recuperar os detalhes completos do status da oferta por meio da API 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"
}
Tópico atualizado do status do ativo
:AssetStatus
Notifica você quando um ativo atinge o resultado final da entrega. Uma notificação é enviada quando o status de um ativo se torna:
- Cumprido — o ativo foi entregue com sucesso ou
- Falha — o ativo não pôde ser entregue ou precisa de atenção.
O que aciona essa notificação? Uma alteração no status de entrega de um ativo (por exemplo, vídeo, áudio, legenda, ilustração). Use o callbackURL para recuperar o status completo da entrega do ativo, incluindo informações detalhadas sobre erros, quando aplicável.
Casos de uso:
- Detecte falhas na entrega em tempo real e acione fluxos de trabalho automatizados de reentrega
- Confirme o sucesso do processamento de ativos sem consultar a API Asset Status
- Integre-se com sistemas internos de emissão de bilhetes para resolução imediata de problemas
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 solicitação e resposta
Esta seção fornece especificações técnicas para que os desenvolvedores integrem a API de notificação de parceiros em seus sistemas. Use essa referência para entender o formato da solicitação, a estrutura da resposta e os tipos de dados retornados pela API.
URL base
Todos os pedidos de API são feitos para o seguinte URL base. Anexe o caminho do endpoint relevante a esse URL ao fazer solicitações.
https://partnerapi.primevideo.com/v1
Gerenciamento de metas
Um destino é o destino em que você deseja receber notificações — isso pode ser um serviço da AWS (SQS, SNS ou EventBridge) ou um endpoint de webhook HTTPS. Você deve registrar pelo menos um alvo antes de criar assinaturas.
Registrar o alvo
POST /{licensor}/notifications/targets
Criar um novo alvo de notificação onde você receberá notificações de eventos.
Corpo da solicitação:
{
"type": "SQS|SNS|EVENTBRIDGE|WEBHOOK",
"destination": "target-destination",
"auth": { /* varies by type */ }
}
Resposta:
{
"targetId": "target-id-1",
"status": "ACTIVE"
}
Listar todos os alvos
Use esse endpoint para recuperar uma lista completa dos alvos de notificação registrados para sua organização. Isso é útil para auditar sua configuração atual ou identificar IDs de destino a serem usadas ao criar ou atualizar assinaturas.
GET /{licensor}/notifications/targets
Recupere todas as metas registradas da sua organização.
Obtenha um alvo específico
GET /{licensor}/notifications/targets?targetId={id}
Recupere detalhes de um alvo específico.
Atualizar destino
PUT /{licensor}/notifications/targets/{targetId}
Atualize uma configuração de destino existente.
Excluir alvo
DELETE /{licensor}/notifications/targets/{targetId}
Remova um alvo da sua configuração.
Gerenciamento de assinaturas
Uma assinatura mapeia um ou mais eventos para um alvo registrado, determinando quais notificações você recebe e onde elas são entregues. Cada assinatura tem como escopo um único tópico, mas você pode criar várias assinaturas para cobrir todos os eventos relevantes ao seu fluxo de trabalho.
Criar assinatura
POST /{licensor}/notifications/subscriptions
Criar uma assinatura para mapear eventos de acordo com seus alvos.
Corpo da solicitação:
{
"topic": "OfferStatus",
"eventTargetMapping": {
"LiveStatusUpdated": ["target-id-1"]
}
}
Resposta:
{
"subscriptionId": "subscription-id-1",
"status": "ACTIVE"
}
Listar todas as assinaturas
GET /{licensor}/notifications/subscriptions
Recupere todas as assinaturas da sua organização.
Atualizar assinatura
PUT /{licensor}/notifications/subscriptions/{id}
Atualize uma configuração de assinatura existente.
Excluir assinatura
DELETE /{licensor}/notifications/subscriptions/{id}
Remova uma assinatura da sua configuração.
Tipos de alvo
Os tipos de destino definem como o Prime Video envia notificações para seus sistemas. Você pode escolher entre serviços gerenciados pela AWS para entrega confiável e escalável ou configurar um webhook HTTPS para receber notificações diretamente em seu próprio endpoint.
Destinos da AWS (SQS, SNS, EventBridge)
Campos obrigatórios:
- destino — ARN do recurso da AWS
- AssumeRoLearn — função do IAM para entrega
- ExternalID — Identificador de segurança (opcional, mas recomendado)
Exemplo 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}"
}
}
Exemplo 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}"
}
}
Exemplo do 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 do portador: {
"type": "WEBHOOK",
"destination": "https://your-api.example.com/webhooks",
"auth": {
"type": "bearer",
"bearerToken": "your-token"
}
}
Chave 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
Estrutura da carga útil
Todos os payloads de notificação seguem uma estrutura consistente:
Campo |
Description |
|---|---|
válido |
ID do anúncio do parceiro (identificador do título) |
território |
Código do Território (por exemplo, EUA, GB) |
mercado |
Código do Marketplace |
Alias de parceiro |
Identificador do parceiro |
Tipo de evento |
O evento específico que ocorreu |
URL de retorno de chamada |
URL para recuperar os detalhes completos do status |
Carimbo de data e hora do evento |
Registro de data e hora ISO 8601 do evento |
Os webhooks recebem solicitações HTTP POST com a seguinte 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"
}
Cabeçalhos de autenticação:
- HMAC: Assinatura X: {assinatura} Assinatura X: {assinatura}
- Chave da API: Chave da API: {chave} Chave da API X: {chave}
- Portador: Portador {token} Autorização: Portador {token}
Respostas de erro
Quando uma solicitação não pode ser concluída, a API retorna uma resposta de erro estruturada para ajudar você a identificar e resolver o problema. A resposta inclui um código de erro e uma mensagem que pode ser lida por humanos descrevendo o problema.
{
"error": {
"code": "ERROR_CODE",
"message": "Human readable error message"
}
}
Códigos de erro comuns:
- BAD_REQUEST — Parâmetros de solicitação inválidos
- NÃO AUTORIZADO — Falha na autenticação
- NOT_FOUND — Recurso não encontrado
- CONFLITO — O recurso já existe
Guia de configuração do AWS Target
Se você estiver usando um serviço da AWS (SQS, SNS ou EventBridge) como alvo de notificação, deverá configurar uma função de entrega do IAM para conceder permissão ao Prime Video para entregar notificações aos seus recursos da AWS. Siga as etapas abaixo para configurar a função e as políticas de permissão necessárias do IAM antes de registrar seu alvo.
Pré-requisitos
- Recurso de destino da AWS (SQS Queue, SNS Topic ou EventBridge Bus)
- Função de entrega do IAM com políticas de confiança e permissão
Configuração da função do IAM
1. Criar função: Console da AWS → IAM → Funções → Criar função → Política de confiança personalizada 2. Política de confiança {
"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 permissão (escolha uma):
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}"
}]
}
Ponte de eventos: {
"Version": "2012-10-17",
"Statement": [{
"Effect": "Allow",
"Action": "events:PutEvents",
"Resource": "arn:aws:events:{region}:{account-id}:event-bus/{bus-name}"
}]
}
