Headless API
Byg din egen butiksfront oven på Shoporama
Base URL
https://din-shop.dk/api
Sælger shoppen i flere lande, kalder du landets adresse, fx https://din-shop.dk/en/api. Så følger sprog, valuta, priser og leveringslande landet.
Session og login
Kurv, checkout og kundelogin følger cookies, præcis som i shoppen. Kald fra browseren med credentials: 'include'. Kunden er logget ind i både API'et og shoppen på samme tid.
Kurv, checkout og login virker kun, når din butiksfront kører på shoppens primære domæne (Webshop → Domæne) eller et lands eget domæne. Domænerne under "Flere domæner" sender alle forespørgsler videre til det primære domæne, også kald til /api. Katalog, sider og menuer kan hentes fra alle domæner.
Svar og fejl
Alle svar har samme form. Ved fejl står årsagen i error.details.reason, så du kan vise din egen tekst til kunden.
{
"success": false,
"error": {
"code": 400,
"message": "Payment method not selected",
"details": { "reason": "payment_missing" }
}
}
Alle fejl har en årsag. Dem du typisk skal håndtere: empty_basket, stock, sold_out, requires_variant, product_unavailable, max_per_order, customer_input, min_order_value, delivery_country, address_missing, shipping_invalid, payment_missing, payment_not_available, payment_link_failed, order_in_progress, voucher_not_found, voucher_expired, points_invalid, login_failed, login_required og not_found.
Grænsen er 300 kald i minuttet pr. session. Derefter svarer API'et 429. Shoppen har desuden en grænse pr. IP-adresse for alle forespørgsler. Overskrides den, afvises IP-adressen i en time med 429 som almindelig tekst og ikke JSON, så cache katalog og indhold, hvis din server henter dem.
API'et har ingen version i adressen. Nye felter kan komme til, så ignorér felter, din kode ikke kender.
Produkter og indhold
Liste produkter
GET /api/products?limit=20&offset=0&category_id=5
Kun varer der er online, og hvis brand kunden må se. Med category_id kommer varerne i kategoriens egen sortering. limit er højst 250, og uden den bruges shoppens sidestørrelse. ?gtin= slår en stregkode op.
{
"success": true,
"data": {
"products": [
{
"id": 232167,
"name": "Terra Nova Etiopien Guji, hele bønner 1 kg",
"price": 249,
"old_price": null,
"buyable": true,
"url": "https://din-shop.dk/terra-nova-etiopien-guji-hele-boenner-1-kg",
"rewrite_url": "terra-nova-etiopien-guji-hele-boenner-1-kg",
"images": [...],
"categories": [...],
"brand": { "id": 445, "name": "Terra Nova", "url": "https://dinbutik.dk/brands/terra-nova" }
}
],
"pagination": {
"total": 32,
"limit": 20,
"offset": 0,
"pages": 2
}
}
}
Priser er inkl. moms. Navne, tekster og adresser følger landets sprog.
brand.url er brandets side (Link til eller brandsiden), når shoppen har slået brandsider til, ellers null.
Enkelt produkt
GET /api/products/232167
{
"success": true,
"data": {
"id": 232167,
"name": "Terra Nova Etiopien Guji, hele bønner 1 kg",
"description": "<p>En let og blomstret kaffe ...</p>",
"sku": "TN-BON-01",
"price": 249,
"vat_rate": 25,
"buyable": true,
"images": [
{
"id": 63924,
"alt": "Pose med Terra Nova Etiopien Guji kaffebønner",
"formats": {
"original": "https://...",
"large": "https://...",
"medium": "https://...",
"small": "https://...",
"thumbnail": "https://..."
}
}
],
"attributes": [...],
"variants": [...],
"meta": { "title": "...", "description": "..." }
}
}
Udsolgte varianter er ikke med i variants. Hver variant har options med attributnavn og værdi på landets sprog, fx {"Farve": "Stål"}. Felter kunden selv skal udfylde (fx en tekst til gravering) står i attributes med "input_mode": "customer".
Varebilleder har fulde adresser. Billeder på kategorier og blogindlæg har en relativ adresse, fx /cache/6/5/…/kaffe-fit-800x800x90.png, så sæt shoppens domæne foran, hvis du viser dem fra et andet domæne.
Slå en adresse op
GET /api/resolve/kaffeboenner
Fortæller hvad en sti i shoppen er, så din butiksfront kan bruge shoppens egne adresser. type er home, category, product, page, blog, blog_list, landing, brand_list, brand, redirect eller not_found.
{
"success": true,
"data": {
"type": "category",
"data": { "id": 19112, "name": "Kaffebønner", ... },
"products": [...],
"pagination": {...},
"blocks": {
"top": "<section ...>...</section>",
"bottom": "..."
}
}
}
brand_list og brand findes, når shoppen har slået brandsider til, og temaet har "supports_brand_pages": true. /brands giver brand_list med brandene (id, name, path, logo, product_count), bogstaverne i letters og brandene pr. bogstav i groups. Ved flere end 24 brands er index sand, og featured har op til 12 brands med logo. Ved flere end 300 er paged sand, og du henter ét bogstav ad gangen med ?letter=a. Uden ?letter= er brands og groups tomme. /brands/<adresse> giver brand med intro (description_a), brødtekst (description_b), meta og breadcrumbs samt varerne i products med ?p= (0 er første side, 1 den anden), ?sort= og ?sort_order=. /brand/<adresse> og et brand med Link til giver redirect. Som i butikken vinder /brands og et brand, der findes, over shoppens egne viderestillinger.
blocks er Sidedesignerens blokke for siden som færdig HTML, renderet med temaets egne skabeloner. Uden blokke er feltet null. Har du allerede siden blokke, så tilføj ?blocks=0.
Menuer
GET /api/menus
{
"menus": [
{
"name": "Hovedmenu",
"location": "top",
"items": [
{
"title": "Kaffe",
"url": "",
"type": "menu",
"children": [
{ "title": "Kaffebønner", "url": "/kaffeboenner", "type": "category", "children": [] }
]
}
]
}
]
}
Et punkt af typen menu er en overskrift for en undermenu og har ingen adresse.
Kurv
Tilføj til kurv
POST /api/basket
attributes (attribut-id → værdi):{
"product_id": 232156,
"amount": 1,
"attributes": { "4301": 33385 }
}
Vis kurv
GET /api/basket
{
"success": true,
"data": {
"items": [
{
"line_id": "232156:4301+33385",
"product_id": "232156",
"name": "Nordic Roast Stempelkande 1 liter",
"variant": "Farve: Stål",
"amount": 1,
"price": 299,
"subtotal": 299,
"in_stock": true,
"image": "https://..."
}
],
"subtotal": 299,
"shipping": 39,
"total": 338,
"vat": 67.6,
"currency": "DKK",
"shipping_chosen": false
}
}
Beløbene er shoppens egne beregninger med kampagner, rabatkode, pant og fragt. Vis dem som de er, så kunden ser den pris, der bliver betalt. Svarene fra checkout og rabatkoder har den opdaterede kurv i basket.
Har en vare pant, står beløbet i deposit_total (og pr. pant-type i deposits). Panten er med i total, men ikke i subtotal, så vis den som en egen linje. På varen står panten pr. stk. i deposit (name, amount).
Ret antal eller fjern en linje
PUT /api/basket/{line_id} DELETE /api/basket/{line_id}
{
"amount": 3
}
Brug linjens line_id, så den rigtige variant rammes. Antal 0 fjerner linjen. Et produkt-id rammer den første linje med varen.
Rabatkode
POST /api/voucher/apply POST /api/voucher/remove
{
"code": "SOMMER10"
}
Svaret har kurven med rabatten. En kode der ikke findes eller er udløbet, giver voucher_not_found eller voucher_expired.
Betal med point
GET /api/points POST /api/points/apply POST /api/points/remove
{
"points": 500
}
Kræver login og et loyalitetsprogram. Har shoppen et, har kurven feltet points:
"points": {
"balance": 1000,
"available": 1000,
"requested": 500,
"used": 500,
"discount": 50,
"earns": 1290,
"rate": { "points": 10, "amount": 1 }
}
balance er kundens saldo, og available de point kurven kan bære efter shoppens regler. For en gæst er de null. discount er trukket fra kurvens total og vat, så vis den som en egen linje. earns er de point ordren optjener, og rate hvor mange point der giver hvilket beløb i kurvens valuta. For mange point giver 400 points_invalid med available.
Pointene klemmes igen til det kurven kan bære, før ordren oprettes, og ordren trækker dem fra saldoen. Optjeningen sker på ordren, når den godkendes eller sendes, som shoppen har valgt.
Checkout
Hent det kunden kan vælge
GET /api/checkout
Giver kurven, fragtmetoderne, betalingsmetoderne og landene i ét kald, plus de adresser kunden allerede har udfyldt. Kun metoder kunden faktisk kan vælge: online betalingsmetoder der må bruges i kundens land, og fragt der passer til kurvens vægt og leveringslandet. Logget ind får kunden også sine B2B-metoder, fx faktura.
Trin 1: Adresse
POST /api/checkout
{
"step": "address",
"email": "kunde@example.com",
"phone": "12345678",
"name": "Karen Holm",
"company_name": "",
"address": "Vestergade 12",
"zipcode": "8000",
"city": "Aarhus C",
"country_id": 188,
"comments": "",
"newsletter": 0
}
Firmakunder kan sende vat_number og ean_number. En anden leveringsadresse sendes som delivery_name, delivery_company, delivery_address, delivery_zipcode, delivery_city og delivery_country_id. Landenes id'er står i GET /api/countries.
Svaret har missing_fields (felter der mangler) og delivers_to_country, så du kan vise det med det samme. Ordren afvises først, når den gennemføres.
Send hele adressen hver gang. Trinnet erstatter alle felter med det, du sender, også dem du udelader. Er kunden logget ind, bruger checkout kontoens adresse og e-mail, og trinnet gemmer først en ny adresse på kontoen, når missing_fields er tom.
Trin 2: Levering
POST /api/checkout
{
"step": "shipping",
"shipping_id": 227,
"delivery_shop_id": "2386"
}
Efter adressetrinnet har fragtmetoder med pakkeshop en liste i delivery_shops (number, name, street, zip, city). Send pakkeshoppens number som delivery_shop_id. En fragtmetode der ikke er på listen, afvises. Sender du ingen pakkeshop, vælger shoppen den første på listen.
Trin 3: Betalingsmetode
POST /api/checkout
{
"step": "payment",
"payment_gateway_id": 258
}
Trin 4: Gennemfør ordren
POST /api/checkout
{
"step": "complete",
"payment_flow": "storefront"
}
Betalingsmetoden er den fra trin 3. Du kan også sende den med her som payment_id. Inden ordren oprettes, tjekker API'et det samme som shoppens egen checkout: lager, mindstebeløb, leveringsland, adresse, fragt og betalingsmetode. Der kommer to slags svar.
{
"success": true,
"data": {
"payment_redirect": true,
"payment_url": "/payment",
"basket_id": 4809
}
}
Send kunden til payment_url. Med "payment_flow": "storefront" er det shoppens egen betalingsside, der sender videre til betalingsvinduet og virker med alle shoppens betalingsmetoder. Uden den giver API'et selve betalingsvinduets adresse for QuickPay, OnPay, Pensopay, Flatpay, Stripe, Mollie og Nets Easy. Andre metoder går altid via shoppens betalingsside. Kunden kommer tilbage til shoppens /thanks.
{
"success": true,
"data": {
"redirect": "/thanks?basket_id=4809&chk=8ab02e10b1a9ec5db4f1fcee7f49fb05",
"order_id": 15505,
"webshop_order_id": 4522,
"chk": "8ab02e10b1a9ec5db4f1fcee7f49fb05",
"payment_info": "<p>Overfør beløbet til ...</p>"
}
}
payment_info er shoppens egen tekst til betalingsmetoden, fx kontonummeret ved bankoverførsel. webshop_order_id er ordrenummeret, kunden ser.
Dobbeltklik og betaling der fejler
- Kalder kunden
completeigen, får du samme svar som første gang. Der oprettes ikke en ny ordre. - Kommer et andet kald, mens ordren oprettes, venter det op til seks sekunder og får så samme svar. Er ordren ikke klar inden da, svarer API'et
409 order_in_progress. - Kan betalingen ikke startes, svarer API'et
502 payment_link_failed, og der oprettes ingen ordre.
Kvittering og ordre
Vis en ordre
GET /api/order?basket_id=4809&chk=8ab02e10b1a9ec5db4f1fcee7f49fb05
Med kvitteringens basket_id eller ordrenummeret (order_id). chk er en MD5-hash af ordrens e-mail, så kun kunden kan se ordren. Svaret har de priser kunden betalte, ikke varernes nuværende priser.
{
"success": true,
"data": {
"order": {
"order_id": "4522",
"status": "new",
"paid": false,
"total": 308,
"currency": "DKK",
"customer": { "name": "Karen Holm", "email": "kunde@example.com" },
"products": [
{ "name": "Terra Nova Etiopien Guji, hele bønner 1 kg", "price": 249, "quantity": 1, "total": 249 }
],
"shipping": { "method": "Postnord omdeling", "price": 59 },
"payment": { "method": "Bankoverførsel", "info": "..." },
"totals": {
"subtotal": 249,
"shipping": 59,
"voucher_discount": 0,
"vat": 61.6,
"total": 308
}
}
}
}
Kundekonto
Log ind og ud
POST /api/auth POST /api/auth/logout
{
"email": "kunde@example.com",
"password": "..."
}
Samme login som i shoppen. Logget ind får kunden sine kundegruppepriser, sine betalingsmetoder og sin adresse udfyldt. Forkert e-mail eller adgangskode giver 401 login_failed.
Den indloggede kunde
GET /api/customer
{
"customer": {
"id": 2224,
"email": "kunde@example.com",
"name": "Karen Holm",
"address": "Vestergade 12",
"zipcode": "8000",
"city": "Aarhus C",
"country_id": 188,
"shipping_address": null,
"points": 120,
"urls": { "profile": "/user-profile", "orders": "/user-orders", "edit": "/user-edit" }
}
}
Uden login er customer null. points er kundens pointsaldo og null, når shoppen ikke har et loyalitetsprogram.
Kundens ordrer
GET /api/orders GET /api/orders/{ordrenummer}
Listen har ordrenummer, dato, status, total, valuta og adressen til ordresiden. Én ordre har samme felter som GET /api/order. Uden login: 401 login_required.
Oprettelse og glemt adgangskode
Link til shoppens egne sider /user-sign-up, /user-reset-password og /user-edit. Så får kunden spamtjek, velkomstmail, point for oprettelse og kontrol af CVR-nummer som i resten af shoppen.
Shop og indstillinger
Handelsbetingelser
GET /api/settings
{
"success": true,
"data": {
"terms": "<p>...</p>",
"has_terms": true
}
}
Bruges typisk i checkout, hvor kunden skal acceptere betingelserne, før ordren gennemføres.
Shoppen
GET /api/shop
Shoppens navn og URL, valuta, sprog, standardland og listen over endpoints.
Alle endpoints
Produkter
GET /api/productsGET /api/products/{id}GET /api/categoriesGET /api/categories/{id}GET /api/frontpageGET /api/search?q={query}Kurv
GET /api/basketPOST /api/basketPUT /api/basket/{line_id}DELETE /api/basket/{line_id}POST /api/voucher/applyPOST /api/voucher/removeGET /api/pointsPOST /api/points/applyPOST /api/points/removeCheckout
GET /api/checkoutPOST /api/checkoutGET /api/shippingGET /api/payment-methodsGET /api/countriesOrdrer og kunde
GET /api/order?basket_id={id}&chk={hash}POST /api/authPOST /api/auth/logoutGET /api/customerGET /api/ordersGET /api/orders/{ordrenummer}Indhold
GET /api/resolve/{sti}GET /api/menusGET /api/pagesGET /api/pages/{id}GET /api/blogGET /api/blog/{id}GET /api/landing-pagesShop
GET /api/shopGET /api/settingsEt færdigt eksempel
Temaet Washington er en komplet butiksfront bygget på dette API, med Sidedesigneren, kundekonto, lande og alle betalingsmetoder. Se Washington