A API de Notificações permite receber notificações em tempo real para vários eventos de conteúdo no Prime Video – eliminando a necessidade de consultar continuamente as APIs de status. Configure fluxos de trabalho automatizados que respondam instantaneamente a atualizações de entrega de ativos e a mudanças no status de publicação, o que permite resolver problemas com mais rapidez e manter seu catálogo atualizado.
Detecção de problemas em tempo real – receba notificações instantâneas quando entregas de ativos falharem ou o status de publicação mudar, o que permite resolver os problemas imediatamente, em vez de descobri-los horas ou dias depois em verificações manuais.
Redução de despesas gerais da API – elimine a necessidade de consultar continuamente as APIs de status, reduzindo os custos de infraestrutura e o volume de chamadas da API enquanto mantém as informações atualizadas.
Integração automatizada do fluxo de trabalho – conecte as notificações diretamente aos seus sistemas (serviços da AWS ou webhooks) para acionar respostas automatizadas, criação de tíquetes ou alertas de fluxos de trabalho sem intervenção manual.
Cobertura abrangente de eventos – monitore o status de entrega de ativos e o status de publicação em todos os seus títulos e territórios a partir de um único sistema de notificação.
Introdução
Para começar a usar as notificações, são necessárias três etapas:
- Registre um alvo: Configure onde você deseja receber notificações. Você pode escolher entre os serviços da AWS (SQS, SNS, EventBridge) ou webhooks HTTPS.
- Crie assinaturas: Mapeie os eventos que deseja monitorar de acordo com seus alvos registrados. Cada assinatura abrange um tópico (AssetStatus ou OfferStatus), mas você pode assinar vários tipos de eventos dentro desse tópico.
- Receba notificações: Uma vez configurado, você receberá notificações automaticamente da ocorrência dos eventos 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 os eventos dentro desse tópico que deseja monitorar.
LiveStatusUpdated
Tópico: OfferStatus
Notifica você quando o status de publicação de um título muda na vitrine do Prime Video, ou seja, quando um título fica no ar ou fora do ar.
O que aciona essa notificação? O status no ar/fora do ar de um título muda na vitrine. Use o callbackUrl da carga útil para recuperar todos os detalhes do status da oferta por meio da API se Status da oferta.
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
Tópico: AssetStatus
Notifica você quando um ativo atinge o resultado final da entrega. Uma notificação é enviada quando o status de um ativo se torna:
- Fulfilled — o ativo foi entregue com sucesso, ou
- Failed — 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, arte). Use o callbackUrl para recuperar o status completo de entrega do ativo, incluindo informações detalhadas de erro, quando aplicável.
Casos de uso:
- Detecte falhas de entrega em tempo real e acione fluxos de trabalho automatizados de nova entrega
- Confirme o processamento bem-sucedido de ativos sem consultar a API de Status de ativos
- Integre-se aos sistemas internos de tíquetes 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 consigam integrar a API de Notificações de parceiros em seus sistemas. Use essa referência para entender o formato da solicitação, a estrutura de resposta e os tipos de dados retornados pela API.
URL base
Todas as solicitações de API são feitas na seguinte URL base. Inclua o caminho do endpoint relevante a essa URL ao fazer solicitações.
https://partnerapi.primevideo.com/v1
Gerenciamento de alvos
Um alvo é o destino em que você deseja receber notificações – 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 alvo
POST /{licensor}/notifications/targets
Crie um novo alvo 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 a lista completa dos alvos de notificação registrados da sua organização. Essa lista pode ser útil para auditar sua configuração atual ou identificar IDs de alvos a serem usados ao criar ou atualizar assinaturas.
GET /{licensor}/notifications/targets
Recupere todos os alvos registrados da sua organização.
Obtenha um alvo específico
GET /{licensor}/notifications/targets?targetId={id}
Recupere dados de um alvo específico.
Atualizar alvo
PUT /{licensor}/notifications/targets/{targetId}
Atualize a configuração de um alvo existente.
Excluir alvo
DELETE /{licensor}/notifications/targets/{targetId}
Remova um alvo de sua configuração.
Gerenciamento de assinaturas
Uma assinatura mapeia um ou mais eventos para um alvo registrado, determinando quais notificações você receberá e onde serã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
Crie uma assinatura para mapear eventos para seus alvos.
Corpo da solicitação:
{
"topic": "OfferStatus",
"eventTargetMapping": {
"LiveStatusUpdated": ["target-id-1"]
}
}
{
"topic": "AssetStatus",
"eventTargetMapping": {
"AssetStatusUpdated": ["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 a configuração de uma assinatura existente.
Excluir assinatura
DELETE /{licensor}/notifications/subscriptions/{id}
Remova uma assinatura de sua configuração.
Tipos de alvos
Os tipos de alvo definem como o Prime Video enviará notificações aos 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.
Alvos da AWS (SQS, SNS, EventBridge)
Campos obrigatórios:
- destino – ARN de recurso da AWS
- assumeRoleArn – função IAM de 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 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 do Transmissor:{
"type": "WEBHOOK",
"destination": "https://your-api.example.com/webhooks",
"auth": {
"type": "bearer",
"bearerToken": "your-token"
}
}
Chave da 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
Todas as cargas úteis de notificação seguem uma estrutura consistente:
Campo |
Descrição |
|---|---|
alid |
ID da oferta do parceiro (identificador do título) |
território |
Código do território (por exemplo, US, GB) |
marketplace |
Código do site |
partnerAlias |
Identificador do parceiro |
eventType |
O evento específico que ocorreu |
callbackUrl |
URL para recuperar todos os detalhes do status |
eventTimestamp |
Carimbo de data/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: {signature}Assinatura X: {signature}
- Chave da API: Chave da API X: {key}Chave da API X: {key}
- Transmissor: Autorização do {token}Transmissor: Transmissor {token}
Respostas de erro
Quando uma solicitação não pode ser concluída, a API retorna uma resposta de erro estruturada para ajudá-lo a identificar e resolver o problema. A resposta inclui um código de erro e uma mensagem legível para o usuário 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
- UNAUTHORIZED – Falha na autenticação
- NOT_FOUND – Recurso não encontrado
- CONFLICT – O recurso já existe
Guia de configuração de alvos da AWS
Se estiver usando um serviço da AWS (SQS, SNS ou EventBridge) como alvo de notificação, configure uma função IAM de entrega 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 IAM e as políticas de permissão necessárias antes de registrar seu alvo.
Pré-requisitos
- Recurso de destino da AWS (fila SQS, tópico SNS ou barramento EventBridge)
- Função IAM de entrega com políticas de confiança e permissão
Configuração de função 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}"
}]
}
EventBridge: {
"Version": "2012-10-17",
"Statement": [{
"Effect": "Allow",
"Action": "events:PutEvents",
"Resource": "arn:aws:events:{region}:{account-id}:event-bus/{bus-name}"
}]
}
