O que é a API do Alva Digital Downloads?
A API do Alva Digital Downloads é uma API REST versionada — v1 — que permite a um sistema externo gerenciar downloads digitais em uma loja Shopify sem abrir o admin do Shopify. Por meio dela um desenvolvedor pode criar arquivos, mapeá-los para produtos, consultar pedidos, emitir URLs de download, reenviar e-mails de entrega e verificar o estoque de chaves de licença, tudo por HTTPS padrão.
A API fica ao lado da interface admin do app, em vez de substituí-la. Todo recurso que ela toca — arquivos, mapeamentos de produto, categorias, pedidos, tags de chave de licença — é o mesmo dado que sua equipe edita à mão no Alva, apenas acessível a partir de código. Isso a torna a ponte entre o Alva Digital Downloads e qualquer outra coisa que faça seu negócio funcionar.
O que você pode fazer com a API do Alva
A API do Alva cobre o fluxo de trabalho principal de entrega de ponta a ponta. Ela gerencia arquivos, mapeamentos de produto e categorias, consulta pedidos e emite URLs de download, reenvia e-mails de entrega personalizados e informa o estoque de chaves de licença. Os arquivos podem ser enviados diretamente ou ingeridos a partir de uma URL remota que o Alva transmite direto para o armazenamento em seu nome.
Em termos práticos, uma integração pode:
- Gerenciar arquivos — enviar um arquivo diretamente, ou entregar ao Alva uma URL para que ele transmita o ativo para o armazenamento por você (ingestão por URL remota), de modo que uma biblioteca grande nunca precise passar primeiro pelos seus próprios servidores.
- Mapear produtos e categorias — anexar arquivos, packs, links ou tags de chave de licença a produtos do Shopify usando o mesmo modelo muitos-para-muitos que o admin usa.
- Consultar pedidos e emitir URLs de download — localizar um pedido do Shopify e gerar uma URL de download nova e com tempo limitado para o comprador.
- Reenviar e-mails de entrega — disparar de novo o e-mail de download de um pedido a partir de código, sem editar nada à mão.
- Verificar o estoque de chaves de licença — ler quantas chaves restam para uma tag antes de um grande lançamento, para que você nunca esgote em silêncio.
Os caminhos de endpoint, os corpos de requisição e os formatos de resposta ficam na referência da API. Este post fica no nível do que a API serve; a referência é onde você conecta cada chamada individual.
Como funcionam a autenticação e as chaves de API
A autenticação usa chaves de API por loja. Cada requisição carrega um token Bearer que começa com adk_live_. O Alva Digital Downloads armazena apenas um hash sha256 do segredo — nunca o texto puro — compara-o em tempo constante e falha de forma fechada, então uma chave ausente, malformada, desconhecida ou revogada retornam todas a mesma resposta de não autorizado.
Você cria uma chave dentro do admin do Alva, copia o token uma vez e o guarda em um gerenciador de segredos. O Alva mantém apenas o id público da chave e o hash, então o segredo em texto puro nunca é recuperável a partir da sua conta. Como todo modo de falha retorna uma resposta idêntica, um invasor não consegue sondar sua loja para distinguir uma chave errada de uma revogada.
Emita uma chave separada por sistema e revogue qualquer uma delas no momento em que uma integração for desativada. Uma chave revogada para de funcionar imediatamente em todos os endpoints, o que torna a rotação de credenciais uma ação de um clique, em vez de uma migração coordenada.
Feita para automação em escala
A API do Alva é feita para ser conduzida por máquinas que fazem novas tentativas. As chaves de idempotência são obrigatórias em toda gravação, com uma janela de repetição de 24 horas que transforma uma requisição duplicada na resposta original, em vez de um segundo registro. Um limitador de taxa por token-bucket protege a loja, e toda resposta retorna um request_id para rastreamento.
A idempotência não é opcional nas gravações. Toda requisição que não seja GET precisa enviar um cabeçalho Idempotency-Key; reutilize a mesma chave e o mesmo corpo e o Alva repete com segurança o primeiro resultado, em vez de criar um arquivo, mapeamento ou atribuição duplicado. Uma nova tentativa após uma conexão interrompida é, portanto, inofensiva:
curl https://.../api/v1/mappings \
-H "Authorization: Bearer adk_live_..." \
-H "Idempotency-Key: 2f9c-4b1e-...-e1" \
-H "Content-Type: application/json" \
-d '{ "product_id": "gid://shopify/Product/123", ... }'Além da idempotência, um limitador de taxa por token-bucket limita as rajadas para que um script descontrolado não possa sobrecarregar seu pipeline de entrega, valores sensíveis são ocultados dos logs e a ingestão por URL remota roda atrás de uma proteção contra SSRF que bloqueia requisições dirigidas a endereços internos. O request_id em toda resposta dá a você e ao suporte do Alva uma única string para rastrear uma chamada da requisição ao resultado.
API ou Shopify Flow: qual caminho é o seu?
O Alva Digital Downloads oferece duas formas de automatizar. O Shopify Flow é o caminho sem código — triggers e ações visuais que você monta no editor do Shopify. A API é o caminho de código, para equipes que precisam de controle programático a partir dos próprios sistemas. A maioria das lojas nunca precisa da API; o Flow cobre as automações comuns.
Se seu objetivo é marcar um cliente sinalizado por fraude, revogar o acesso em um reembolso ou recompensar compradores VIP, construa isso visualmente — o guia de automações do Shopify Flow para downloads digitais percorre os triggers e ações do Alva. Recorra à API quando a lógica vive fora do Shopify: um ERP que controla seu catálogo, um LMS que provisiona o acesso a cursos ou um CRM que precisa ficar em sincronia. Por baixo, ambos conduzem o mesmo motor por trás da entrega multicanal de downloads do Alva.
Para quem é a API do Alva
A API do Alva é voltada a três públicos: desenvolvedores que querem automatizar trabalho de arquivos e mapeamentos em massa, agências que constroem vitrines Shopify personalizadas ou headless que entregam bens digitais e equipes de operações que sincronizam downloads com um ERP, LMS ou CRM externo. Lojistas que rodam uma vitrine Shopify padrão raramente precisam dela.
Uma construção headless pode manter o Shopify como fonte da verdade para os pedidos enquanto a API emite URLs de download para um front-end sob medida. Uma equipe de operações pode deixar seu ERP criar arquivos e mapeamentos no momento em que um produto é lançado, para que a vitrine e o back office nunca se descolem. O fio condutor é o controle que precisa se originar fora do admin do Shopify.
Nada disso é um requisito para vender produtos digitais no Shopify — o admin do Alva já cuida disso de ponta a ponta. A API é para a minoria de lojas cuja escala ou arquitetura já superou o clicar por uma interface de usuário.
Como obter acesso à API
O acesso à API é opcional (opt-in) e controlado. Um sinalizador de disponibilidade global mais um botão por loja significam que a API é ativada para uma loja de cada vez sob solicitação, não habilitada para todos por padrão. Entre em contato com o suporte do Alva para ativá-la na sua loja. A API está disponível nos planos pagos e está sendo lançada gradualmente.
Peça ao suporte do Alva para habilitar o acesso à API e depois crie uma chave no admin do Alva. O guia de ajuda para usar a API externa percorre as chaves, a idempotência, a ingestão remota e as atribuições de pedido, e a versão vem com uma referência completa da API, uma especificação OpenAPI para download e uma coleção do Postman. Confira os planos para saber onde a API se encaixa.
Perguntas frequentes
A API do Alva Digital Downloads é uma API REST versionada, v1, que permite a um sistema externo gerenciar downloads digitais em uma loja Shopify sem usar o admin do Shopify. Por meio dela um desenvolvedor pode criar arquivos, mapeá-los para produtos, consultar pedidos, emitir URLs de download, reenviar e-mails de entrega e verificar o estoque de chaves de licença por HTTPS padrão.
Apenas para gravações. Toda requisição que não seja GET precisa incluir um cabeçalho Idempotency-Key, que tem uma janela de repetição de 24 horas, então uma chamada repetida retorna a resposta original em vez de criar um arquivo, mapeamento ou atribuição duplicado. As requisições de leitura não precisam de uma. Isso mantém as automações que fazem novas tentativas após um erro de rede a salvo de fazer mudanças duplicadas.
A API usa chaves de API por loja. Cada requisição envia um token Bearer que começa com adk_live_. O app armazena apenas um hash sha256 do segredo, nunca o texto puro, compara-o em tempo constante e falha de forma fechada, então uma chave ausente, malformada, desconhecida ou revogada retornam todas a mesma resposta de não autorizado e não podem ser distinguidas.
O Shopify Flow é o caminho de automação sem código, construído com triggers e ações visuais dentro do Shopify. A API é o caminho de código, para equipes que precisam de controle programático a partir dos próprios sistemas. Use o Flow para automações que vivem dentro do Shopify, e a API quando a lógica vive em um ERP, LMS ou CRM externo.
O acesso à API é opcional (opt-in) e controlado por loja. Um sinalizador de disponibilidade global mais um botão por loja significam que ele é ativado individualmente sob solicitação, não habilitado para todos por padrão. Entre em contato com o suporte do Alva para ativá-lo na sua loja. A API está disponível nos planos pagos e está sendo lançada gradualmente.