Nødsituation

Ved akutte situationer eller nedbrud kan du sende en SMS til vores vagttelefon

Vagttelefon (kun SMS)

+45 29 70 15 95

Send en SMS med følgende information:

  • Dit navn og webshop
  • Beskrivelse af problemet

Bemærk: Denne service er kun til kritiske situationer hvor din webshop er nede eller har alvorlige problemer. For almindelig support, brug venligst vores normale supportkanaler.

Headless API

Byg din egen butiksfront oven på Shoporama

Katalog, kurv, rabatkoder, checkout, betaling og kundekonto. Shoppens egne regler for priser, lager, fragt og betaling gælder hele vejen.

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
Request body. Varianter og kundens egne felter sendes i 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.

Betaling med det samme (kort, MobilePay m.fl.):
{
  "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.

Ordren er oprettet (bankoverførsel og faktura, og uden storefront-flowet også en gratis ordre):
{
  "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 complete igen, 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/products
GET /api/products/{id}
GET /api/categories
GET /api/categories/{id}
GET /api/frontpage
GET /api/search?q={query}

Kurv

GET /api/basket
POST /api/basket
PUT /api/basket/{line_id}
DELETE /api/basket/{line_id}
POST /api/voucher/apply
POST /api/voucher/remove
GET /api/points
POST /api/points/apply
POST /api/points/remove

Checkout

GET /api/checkout
POST /api/checkout
GET /api/shipping
GET /api/payment-methods
GET /api/countries

Ordrer og kunde

GET /api/order?basket_id={id}&chk={hash}
POST /api/auth
POST /api/auth/logout
GET /api/customer
GET /api/orders
GET /api/orders/{ordrenummer}

Indhold

GET /api/resolve/{sti}
GET /api/menus
GET /api/pages
GET /api/pages/{id}
GET /api/blog
GET /api/blog/{id}
GET /api/landing-pages

Shop

GET /api/shop
GET /api/settings

Et færdigt eksempel

Temaet Washington er en komplet butiksfront bygget på dette API, med Sidedesigneren, kundekonto, lande og alle betalingsmetoder. Se Washington