API pública

Autenticação e chaves

Um Proprietário ou Administrador da organização emite, rotaciona e revoga as chaves em Configurações → API. Cada chave nova é exibida uma única vez. Envie-a no cabeçalho Authorization.

Authorization: Bearer adc_<id>.<secret>

A chave pertence a uma loja e só acessa os dados dessa loja. Um identificador de outra loja responde 404, como um identificador inexistente; se o produto exigido pelo endpoint (PIM ou DAM) não estiver liberado para a loja, a resposta é 403 not_contracted. O contrato OpenAPI e a coleção do Postman são públicos e dispensam chave.

As chaves valem por 90 dias. A rotação cria uma chave nova e mantém a anterior funcionando por até 7 dias, sem estender o vencimento original. Troque a chave na sua integração durante essa sobreposição; enquanto ela durar, uma nova rotação é recusada. A revogação tem efeito imediato.

Limites, paginação e busca por SKU

Cada chave permite 120 chamadas a cada 60 segundos. O IP de origem permite 600 chamadas na mesma janela, contadas antes da autenticação. Uma página contém até 100 itens.

Use limit e offset para produtos. A ordem acompanha o updatedAt do registro do produto, não cada edição de atributo ou variante. Os eventos usam cursor; guarde o nextCursor da resposta para a próxima chamada.

Busque pelo código SKU do catálogo com o parâmetro sku, repetido para até 100 códigos. Maiúsculas e minúsculas são equivalentes, exceto que um código guardado com ß pode não ser encontrado se a busca trouxer SS; envie sem espaços nas pontas, ou a resposta será 400. Os resultados trazem requestedSku; um código pode corresponder a várias variantes. Códigos ausentes aparecem em notFound, e um código SKU repetido na mesma consulta é processado uma só vez. Produtos de variante única seguem a regra de código SKU da loja quando configurada.

/api/v1/variants?sku=SKU-1001&sku=SKU-1002

Endpoints

Como tratar recusas

400

Há parâmetros ausentes, repetidos ou inválidos, ou a resposta solicitada excede o limite de tamanho. Confira os parâmetros e os limites no contrato OpenAPI e ajuste a chamada.

401

A chave está ausente, inválida, vencida ou revogada, ou a loja está inativa. A resposta é unauthorized com WWW-Authenticate: Bearer e não revela o motivo interno. Confira a chave. Se precisar de outra, peça a um Proprietário ou Administrador da organização para emitir uma chave, quando não houver nenhuma ativa, ou rotacionar a ativa. Com a loja inativa, não é possível emitir nem rotacionar até ela ser reativada.

403

A chave é válida, mas não pode executar esta operação. insufficient_scope: os endpoints desta página são de leitura, então use a chave de leitura, não a de escrita. not_contracted: o produto que o endpoint exige (PIM ou DAM) não está liberado para a loja. datalake_disabled: o Data Lake não está habilitado para a loja. Repetir com a mesma chave não resolve essas recusas.

404

O recurso ou snapshot solicitado não está disponível para esta loja. Confira o identificador e, para snapshots, o formato e a data. O código export_not_ready indica que não há snapshot completo disponível para essa seleção.

429

O limite da chave ou do IP foi atingido. Aguarde os segundos de Retry-After antes de repetir. Os cabeçalhos X-RateLimit-* vêm em toda resposta 200 dos endpoints que exigem chave e, na resposta 429, só quando o limite esgotado é o da chave.

500

Não foi possível concluir a chamada por um erro interno. Tente novamente mais tarde. Se o erro persistir, entre em contato com o suporte.

Eventos

Consulte GET /api/v1/events com cursor e elimine duplicações pelo id estável do evento. Cada evento fica disponível 120 segundos depois de registrado. A consulta traz só os tipos de evento liberados para a loja. Ela e os webhooks usam os mesmos ids.

• product.published
• asset.changed

A consulta não é um histórico completo de mudanças. Eventos de ativos cobrem alterações concluídas e registradas na auditoria do DAM; ligações automáticas feitas pela importação, cópias entre variantes irmãs, reversões de importação e tarefas de mídia não os emitem. O evento product.published só cobre publicações na VTEX concluídas e com histórico gravado. Releia produtos e ativos para reconciliar os dados.

Webhooks

O destino HTTPS é cadastrado pela equipe responsável pelo serviço ou, quando a tela estiver habilitada, por um Proprietário ou Administrador da organização em Configurações → Webhooks. A entrega começa depois que essa equipe habilitar o envio para a sua loja. A partir daí, a entrega a um destino recém-cadastrado começa em até uma hora e só inclui eventos posteriores ao cadastro. Se a entrega parar por falha do serviço, a retomada cabe à mesma equipe. A consulta de eventos continua disponível antes de a entrega começar e durante uma interrupção.

Verifique a assinatura HMAC e o horário usando o segredo do webhook antes de aceitar uma entrega. Depois de gerar um segredo novo, aceite também o anterior por alguns minutos: um lote em andamento pode terminar assinado com ele. A seção webhooks do OpenAPI define os cabeçalhos de assinatura, o conteúdo, as tentativas e a confirmação de recebimento. Use o id estável do evento para tratar entregas repetidas com segurança.