Changelog da API

Notificações de atualização de produto - outubro de 2026

Envie por e-mail aos compradores de um produto o aviso de que ele foi atualizado — a campanha que um lojista inicia com Notificar clientes na página de um produto — a partir do seu próprio sistema. Aditivo ao contrato da v1. Disponível em todos os planos pagos.

• Novo POST /products/{shopify_product_id}/notifications: coloca na fila uma campanha (202) para todos os compradores dos mapeamentos baixáveis do produto ou, com variant_ids, dos mapeamentos que atendem a essas variantes. message opcional em texto simples de até 2.000 caracteres com {customer.first_name}, {shop.name}, {product.title} e {product.metafields.<namespace>.<key>}; sem links. dry_run executa todas as verificações e retorna os números, o assunto e a observação renderizada sem enviar (200; use uma Idempotency-Key nova para cada dry run). Custa 10 tokens de limite de taxa.
• Novo GET /notifications/{notificationId}: o status da campanha, os números, waiting_for_archive e um vocabulário fechado de error; completed com partial: true quando alguns envios falharam. Campanhas iniciadas no aplicativo também aparecem.
• Novo POST /notifications/{notificationId}/cancel: cancela uma campanha na fila (200). Ele mantém o limite de 7 dias do produto, exatamente como o cancelamento no aplicativo.
• Novo objeto opcional notify_customers em POST /mappings e PUT /mappings/{id}: coloca na fila uma notificação para os compradores do mapeamento escrito depois que a escrita é confirmada. Uma observação que quebra uma regra sobre o próprio texto (em branco, longa demais, uma variável inválida, mais de cinco metacampos, um link no texto) é 422 invalid_message sem nada escrito; um problema de metacampo e toda outra recusa são informados no novo campo data.notification (created: false, error), nunca como um 4xx. data.notification só está presente quando o sinalizador foi enviado; as respostas existentes não mudam.
• Uma campanha por produto a cada 7 dias, em todas as suas variantes e em todas as origens, e nenhuma enquanto uma ainda está na fila ou enviando: 429 notification_cooldown com Retry-After (até sete dias) e error.details.next_available_at. Não é o token bucket — não tente de novo automaticamente; agende a próxima chamada para next_available_at.
• No máximo 5 campanhas por loja na fila ou enviando ao mesmo tempo, somando todos os produtos e todas as origens: a sexta campanha é 429 too_many_active_notifications com error.details.limit e error.details.active_notification_ids, e sem Retry-After. Tente de novo quando uma delas terminar. Um dry run é recusado da mesma forma; em uma escrita de mapeamento, isso é informado em data.notification.
• Um e-mail de atualização de produto por comprador por loja a cada 24 horas, somando todas as campanhas: um comprador que já recebeu um é pulado quando a campanha envia. Compradores pulados não entram em sent_count, failed_count nem suppressed_count. Uma campanha que pulou todos os compradores termina failed com error: recipients_recently_notified e não consome os 7 dias do produto.
• Antes de cada lote de até 500 e-mails, a campanha verifica a loja de novo e é interrompida se a assinatura ou o plano pago expirou, se os e-mails para clientes foram desativados, se o envio foi suspenso ou se o Alva desativou as notificações. Interrompida antes de alguém receber e-mail, ela fica failed (plan_required, email_disabled, notifications_suspended ou notifications_switched_off) e libera os 7 dias; interrompida depois, fica completed com partial: true. Uma campanha em que todos os envios falharam fica failed com nothing_sent e também libera os 7 dias, e uma que, no momento do envio, não tinha mais ninguém para quem enviar fica failed com no_eligible_recipients e os libera igualmente.
• Uma campanha cujo mapeamento alvo tem uma geração de ZIP em andamento espera por ela (waiting_for_archive: true; apenas um mapeamento que entrega um arquivo ZIP faz uma campanha esperar); uma geração que falha, ou que fica 60 minutos sem progresso enquanto está em execução (6 horas enquanto ainda aguarda para começar ou por uma nova tentativa), contados a partir da geração, não da criação da campanha, faz a campanha falhar com zero envios e libera o limite.
• Oito novos códigos de erro: 403 notifications_suspended, 404 notification_not_found, 409 notification_not_cancellable, 422 invalid_message, 422 no_downloadable_content, 422 no_eligible_recipients, 429 notification_cooldown, 429 too_many_active_notifications. mapping_not_found e multiple_mappings_match ganham error.details.unresolved_variant_ids / ambiguous_variant_ids neste endpoint.

Atualização de acesso - setembro de 2026

O acesso à API não depende mais de aprovação.

• Todos os planos pagos (Basic, Pro e Enterprise) podem usar a API. Crie chaves no aplicativo em Configurações → API keys; não há nada a solicitar.
• No plano Free, a aba API keys fica oculta e as chaves existentes retornam 402 plan_required até que a loja mude para um plano pago.

Atualização da v1 - julho de 2026

Adições aditivas de códigos de erro e campos de resposta ao contrato v1 existente.

• Novo erro 422 withdrawal_consent_required no endpoint de download-urls de pedidos: retornado quando a loja tem o consentimento do direito de arrependimento da UE ativado e o pedido ainda não tem um registro de consentimento; as URLs de download são emitidas assim que o cliente consente.
• Novo erro 422 key_limit_reached ao criar chaves de API: uma loja pode ter no máximo 25 chaves de API ativas; revogue uma primeiro.
• Novo erro 409 delivery_not_yet_released nos endpoints download-urls e resend de pedidos: retornado quando o produto tem um atraso na entrega do download configurado e os arquivos do comprador ainda não foram liberados. Nenhuma URL de download é emitida e nenhum e-mail é enviado até o atraso terminar.
• Novo objeto error.details no envelope de erro: presente apenas nos códigos que carregam contexto seguro para quem chama. Hoje delivery_not_yet_released é o único produtor, e ele carrega release_at, o instante ISO 8601 em que os downloads são liberados. Trate o objeto como aberto: novas chaves podem aparecer sem uma mudança de versão maior.
• Novos campos delivery_pending e release_at no objeto de compra do status do pedido: delivery_pending é true enquanto uma compra ainda está retida por um atraso na entrega do download, e release_at é o instante ISO 8601 da liberação, ou null quando não há nada pendente.
• O endpoint grant-downloads agora libera imediatamente as compras retidas do pedido, permitindo que o lojista substitua um atraso na entrega do download pela API.

v1.0.0 - junho de 2026

Superfície inicial da API em piloto, com acesso somente mediante aprovação.

• Chaves de API para lojas aprovadas.
• Chaves de idempotência obrigatórias em requisições de escrita.
• Importação de ativos por URL remota, uploads diretos, listagem de ativos, atualizações de ativos e exclusão de ativos.
• Categorias planas, mapeamentos de produtos, pacotes e tags de chaves de licença.
• Atribuições de pedidos que tornam os downloads mapeados visíveis nas contas de cliente do Shopify.
• Controles de acesso ao pedido: revogar, restaurar, conceder downloads e reenviar e-mail.
• Endpoints de status de jobs e pedidos.
• Downloads da especificação OpenAPI e da coleção Postman.

Política de versionamento

O contrato da v1 é apenas aditivo: novos endpoints, campos opcionais e novos códigos de erro podem ser adicionados. Mudanças incompatíveis usarão um futuro caminho /api/v2.