Set up API access
1. Confirme que a loja tem um plano pago
A API funciona em todos os planos pagos. No plano Free, a aba API keys fica oculta e as chaves existentes retornam plan_required; mude para um plano pago para usar a API.
2. Crie uma chave de API
Abra as Configurações do Alva, escolha API keys e crie uma chave para a integração. Copie o token uma única vez e armazene-o em um gerenciador de segredos. O Alva armazena apenas um id de chave pública e um hash do segredo. Assim que a chave existir, essa mesma aba mostra a URL base da sua API — o endereço para onde vai cada solicitação.
3. Envie o token como cabeçalho Bearer
Envie cada requisição com Authorization: Bearer adk_live_.... Uma chave ausente, malformada, desconhecida ou revogada retorna a mesma resposta de não autorizado, para que invasores não consigam enumerar chaves válidas.
4. Inclua chaves de idempotência nas gravações
Toda requisição que não seja GET deve incluir um cabeçalho Idempotency-Key. Reutilizar a mesma chave e o mesmo corpo repete com segurança uma resposta bem-sucedida em vez de criar um recurso, mapeamento, atribuição ou alteração de acesso duplicados.
Criar recursos e mapear produtos
Use POST /api/v1/assets para importar um arquivo remoto de um host permitido, ou use os endpoints de upload direto quando sua integração faz o upload diretamente para o armazenamento da Alva. Consulte GET /api/v1/jobs/{job_id} até que a importação remota seja concluída.
Depois que o recurso existir, crie ou atualize um mapeamento com POST /api/v1/mappings. Os ids de produto devem usar o formato GID da Shopify. A API restringe cada mapeamento à loja associada à chave de API.
Atribuir downloads a pedidos
Use POST /api/v1/orders/{shopify_order_id}/assignments quando um sistema externo precisar dar a um cliente acesso a produtos digitais mapeados. A atribuição pode criar o registro do cliente, criar a compra e, opcionalmente, enviar o e-mail de entrega.
Use os endpoints de acesso a pedidos para revogar o acesso, restaurá-lo, conceder downloads extras ou reenviar o e-mail de entrega. Essas ações são restritas à loja e não aceitam ids de loja no corpo da requisição.
Leia a documentação da API
Use o guia de início rápido, a referência de endpoints, o guia de erros e a especificação OpenAPI para download ao criar uma integração.
FAQ
Todo comerciante pode usar a API externa?
Todo comerciante com um plano pago (Basic, Pro ou Enterprise) pode usá-la. O plano Free não inclui acesso à API.
Do write requests need idempotency keys?
Sim. Toda requisição que não seja GET deve incluir um cabeçalho Idempotency-Key para que novas tentativas não criem recursos, mapeamentos, atribuições ou alterações de acesso duplicados.
See also
Isto foi útil?
Última atualização 2026-10-05