Wat is de Alva Digital Downloads API?
De Alva Digital Downloads API is een geversioneerde REST-API — v1 — waarmee een extern systeem digitale downloads op een Shopify-winkel kan beheren zonder de Shopify-beheeromgeving te openen. Via de API kan een ontwikkelaar bestanden aanmaken, ze aan producten koppelen, bestellingen opzoeken, download-URL's uitgeven, leveringsmails opnieuw versturen en de licentiesleutelvoorraad controleren, allemaal via standaard-HTTPS.
De API staat naast de beheerinterface van de app in plaats van deze te vervangen. Elke resource die de API aanraakt — bestanden, productkoppelingen, categorieën, bestellingen, licentiesleuteltags — is dezelfde data die je team handmatig in Alva bewerkt, alleen bereikbaar vanuit code. Dat maakt het de brug tussen Alva Digital Downloads en wat je bedrijf verder ook aanstuurt.
Wat je met de Alva API kunt doen
De Alva API dekt de kern-leveringsworkflow van begin tot eind. Deze beheert bestanden, productkoppelingen en categorieën, zoekt bestellingen op en geeft download-URL's uit, verstuurt gebrande leveringsmails opnieuw en rapporteert de licentiesleutelvoorraad. Bestanden kunnen rechtstreeks worden geüpload, of worden opgehaald vanaf een externe URL die Alva namens jou rechtstreeks naar de opslag streamt.
In de praktijk kan een integratie:
- Bestanden beheren — upload een bestand rechtstreeks, of geef Alva een URL en het streamt het asset voor je naar de opslag (remote-URL-ingest), zodat een grote bibliotheek nooit eerst via je eigen servers hoeft te lopen.
- Producten en categorieën koppelen — voeg bestanden, pakketten, links of licentiesleuteltags toe aan Shopify-producten met hetzelfde many-to-many-model dat de beheeromgeving gebruikt.
- Bestellingen opzoeken en download-URL's uitgeven — zoek een Shopify-bestelling op en genereer een verse, tijdgebonden download-URL voor de koper.
- Leveringsmails opnieuw versturen — activeer de leveringsmail voor een bestelling opnieuw vanuit code, zonder iets handmatig te bewerken.
- Licentiesleutelvoorraad controleren — lees af hoeveel sleutels er voor een tag resteren vóór een grote lancering, zodat je nooit stilletjes uitverkocht raakt.
Endpoint-paden, request-bodies en responsvormen staan in de API-referentie. Dit artikel blijft op het niveau van waar de API voor is; de referentie is waar je elke afzonderlijke aanroep aansluit.
Hoe authenticatie en API-sleutels werken
Authenticatie verloopt via API-sleutels per winkel. Elk verzoek draagt een Bearer-token dat begint met adk_live_. Alva Digital Downloads slaat alleen een sha256-hash van het geheim op — nooit de platte tekst — vergelijkt deze in constante tijd en faalt gesloten, zodat een ontbrekende, misvormde, onbekende of ingetrokken sleutel allemaal dezelfde ongeautoriseerde respons teruggeven.
Je maakt een sleutel aan in de Alva-beheeromgeving, kopieert de token één keer en slaat deze op in een secret manager. Alva bewaart alleen de publieke sleutel-id en de hash, zodat het platte-tekstgeheim nooit uit je account te herstellen is. Omdat elk faalscenario een identieke respons teruggeeft, kan een aanvaller je winkel niet aftasten om een verkeerde sleutel van een ingetrokken sleutel te onderscheiden.
Geef een aparte sleutel uit per systeem en trek elke sleutel in op het moment dat een integratie wordt uitgefaseerd. Een ingetrokken sleutel stopt onmiddellijk met werken op elk endpoint, wat het roteren van inloggegevens een handeling met één klik maakt in plaats van een gecoördineerde migratie.
Gebouwd voor automatisering op schaal
De Alva API is gebouwd om te worden aangestuurd door machines die opnieuw proberen. Idempotentiesleutels zijn vereist bij elke schrijfactie, met een replay-venster van 24 uur dat een gedupliceerd verzoek omzet in de oorspronkelijke respons in plaats van een tweede record. Een token-bucket-ratelimiter beschermt de winkel, en elke respons geeft een request_id terug voor tracering.
Idempotentie is niet optioneel bij schrijfacties. Elk niet-GET-verzoek moet een Idempotency-Key-header meesturen; hergebruik dezelfde sleutel en body en Alva speelt veilig het eerste resultaat opnieuw af in plaats van een dubbel bestand, koppeling of toewijzing aan te maken. Een nieuwe poging na een verbroken verbinding is daarom onschadelijk:
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", ... }'Naast idempotentie beperkt een token-bucket-ratelimiter pieken zodat één op hol geslagen script je leveringspijplijn niet kan overspoelen, worden gevoelige waarden uit logs geredigeerd, en draait remote-URL-ingest achter een SSRF-beveiliging die verzoeken naar interne adressen blokkeert. De request_id op elke respons geeft jou en de Alva-support één string om één aanroep van verzoek tot resultaat te traceren.
API of Shopify Flow: welk pad is het jouwe?
Alva Digital Downloads geeft je twee manieren om te automatiseren. Shopify Flow is het no-code-pad — visuele triggers en acties die je samenstelt in Shopify's editor. De API is het code-pad, voor teams die programmatische controle vanuit hun eigen systemen nodig hebben. De meeste winkels hebben de API nooit nodig; Flow dekt de gebruikelijke automatiseringen.
Als je doel is om een als frauduleus gemarkeerde klant te taggen, toegang bij een terugbetaling in te trekken of VIP-kopers te belonen, bouw het dan visueel — de gids over Shopify Flow-automatiseringen voor digitale downloads loopt Alva's triggers en acties door. Grijp naar de API wanneer de logica buiten Shopify leeft: een ERP dat je catalogus beheert, een LMS dat cursustoegang levert, of een CRM dat synchroon moet blijven. Onder de motorkap sturen beide dezelfde engine aan achter Alva's multi-channel downloadlevering.
Voor wie de Alva API bedoeld is
De Alva API richt zich op drie doelgroepen: ontwikkelaars die bulk-bestands- en koppelwerk willen scripten, bureaus die aangepaste of headless Shopify-storefronts bouwen die digitale goederen leveren, en operationele teams die downloads synchroniseren met een externe ERP, LMS of CRM. Merchants met een standaard Shopify-storefront hebben deze zelden nodig.
Een headless build kan Shopify als bron van waarheid voor bestellingen behouden terwijl de API download-URL's uitgeeft aan een op maat gemaakte front-end. Een operationeel team kan zijn ERP bestanden en koppelingen laten aanmaken op het moment dat een product wordt verzonden, zodat de storefront en de backoffice nooit uit elkaar lopen. De rode draad is controle die buiten de Shopify-beheeromgeving moet ontstaan.
Niets hiervan is een vereiste om digitale producten op Shopify te verkopen — de Alva-beheeromgeving handelt dat al van begin tot eind af. De API is voor de minderheid van winkels waarvan de schaal of architectuur is ontgroeid aan het doorklikken van een gebruikersinterface.
Hoe je toegang krijgt tot de API
API-toegang is opt-in en afgeschermd. Een globale beschikbaarheidsvlag plus een schakelaar per winkel betekenen dat de API op verzoek voor één winkel tegelijk wordt ingeschakeld, niet standaard voor iedereen. Neem contact op met de Alva-support om deze voor je winkel in te schakelen. De API is beschikbaar op betaalde plannen en wordt geleidelijk uitgerold.
Vraag de Alva-support om API-toegang in te schakelen en maak vervolgens een sleutel aan vanuit de Alva-beheeromgeving. De helpgids voor het gebruik van de externe API loopt sleutels, idempotentie, remote ingest en besteltoewijzingen door, en de build wordt geleverd met een volledige API-referentie, een downloadbare OpenAPI-spec en een Postman-collectie. Bekijk de plannen voor waar de API zich bevindt.
Veelgestelde vragen
De Alva Digital Downloads API is een geversioneerde REST-API, v1, waarmee een extern systeem digitale downloads op een Shopify-winkel kan beheren zonder de Shopify-beheeromgeving te gebruiken. Via de API kan een ontwikkelaar bestanden aanmaken, ze aan producten koppelen, bestellingen opzoeken, download-URL's uitgeven, leveringsmails opnieuw versturen en de licentiesleutelvoorraad controleren via standaard-HTTPS.
Alleen voor schrijfacties. Elk niet-GET-verzoek moet een Idempotency-Key-header bevatten, die een replay-venster van 24 uur heeft, zodat een opnieuw geprobeerde aanroep de oorspronkelijke respons teruggeeft in plaats van een dubbel bestand, koppeling of toewijzing aan te maken. Leesverzoeken hebben er geen nodig. Dit houdt automatiseringen die na een netwerkfout opnieuw proberen veilig voor het maken van dubbele wijzigingen.
De API gebruikt API-sleutels per winkel. Elk verzoek verstuurt een Bearer-token dat begint met adk_live_. De app slaat alleen een sha256-hash van het geheim op, nooit de platte tekst, vergelijkt deze in constante tijd en faalt gesloten, zodat een ontbrekende, misvormde, onbekende of ingetrokken sleutel allemaal dezelfde ongeautoriseerde respons teruggeven en niet van elkaar te onderscheiden zijn.
Shopify Flow is het no-code-automatiseringspad, opgebouwd uit visuele triggers en acties binnen Shopify. De API is het code-pad, voor teams die programmatische controle vanuit hun eigen systemen nodig hebben. Gebruik Flow voor automatiseringen die binnen Shopify leven, en de API wanneer de logica in een externe ERP, LMS of CRM leeft.
API-toegang is opt-in en per winkel afgeschermd. Een globale beschikbaarheidsvlag plus een schakelaar per winkel betekenen dat deze op verzoek individueel wordt ingeschakeld, niet standaard voor iedereen. Neem contact op met de Alva-support om deze voor je winkel in te schakelen. De API is beschikbaar op betaalde plannen en wordt geleidelijk uitgerold.