Hoppa till huvudinnehållet

Utvecklare

Merchant-API

Ett read-only REST-API för din VeeBoost-butik: en publicerad spec, nyckelbaserad autentisering och förutsägbar sidnumrering — byggt för integrationer som håller sig synkroniserade.

En spec, publicerad som enda sanningskälla

Din butik publicerar det kompletta maskinläsbara kontraktet (OpenAPI 3.1): varje endpoint, parameter, svar och felkod i merchant-API:et. Den här sidan länkar till det och upprepar aldrig endpointtabellerna — kontraktet kan inte glida, och det kan inte din integration heller.

Publicerat kontraktGET /openapi/v1.json

Snabbstart

Tre steg till din första katalogläsning:

  1. Skapa en API-nyckel i ditt adminavsnitt Utvecklare med de read-scopes du behöver. Den börjar med vbk_ och visas bara en gång.
  2. Skicka den i headern X-Api-Key på varje förfrågan — din tenant avgörs från nyckeln, aldrig från värden.
  3. Anropa din första endpoint, till exempel GET /products, följ sedan kontraktet för allt annat.

Autentisering

Varje förfrågan bär din nyckel i headern X-Api-Key. v1 levererar exakt fyra read-scopes — produkter, beställningar, kunder och webhooks-leveranser. En saknad scope svarar 403; en återkallad nyckel avslås omedelbart. Förvara nycklar på serversidan: de hör aldrig hemma i en webbläsare eller ett offentligt repo.

products:readorders:readcustomers:readwebhooks:read

Sidnumrering

List-endpoints paginerar: gå igenom dem med parametern page och läs kuvertet som följer med varje samling — det visar var du är så att din integration kan synkronisera om utan att gissa. Varje endpoints exakta parametrar står i kontraktet.

Fel och hastighetsgränser

Fel returnerar en strukturerad JSON-kropp du kan parsa, aldrig ett stycke att skrapa. Ett 429-svar är ett stabilt kontrakt: samma kropp varje gång, med headrarna X-RateLimit-* och en Retry-After som säger exakt när du ska komma tillbaka. Att trycka på låser inte upp data — backa av.

Sandbox-nycklar

Under förhandslanschen utfärdas sandbox-nycklar efter validering av vårt team och körs med en egen hastighetsbudget, separat från produktionsnycklar — utforska API:et mot din butik utan att röra levande trafik eller kvoter.

Exempel per språk

Ett utdrag per plattform, endast read-scopes: varje hämtar din produktkatalog. Ersätt <api-base> med din butiks API-värd från adminavsnittet Utvecklare.

curl

curl -H "X-Api-Key: vbk_your_key" \
  "https://<api-base>/products?page=1"

JavaScript

async function listProducts(page = 1) {
  const res = await fetch("https://<api-base>/products?page=" + page, {
    headers: { "X-Api-Key": "vbk_your_key" },
  });
  if (res.status === 429) {
    // Structured contract: honor Retry-After, never screen-scrape.
    const wait = Number(res.headers.get("Retry-After")) * 1000;
    await new Promise((done) => setTimeout(done, wait));
    return listProducts(page);
  }
  if (!res.ok) throw new Error("products:read failed with " + res.status);
  return res.json();
}

Python

import requests

def list_products(page=1):
    res = requests.get(
        "https://<api-base>/products",
        params={"page": page},
        headers={"X-Api-Key": "vbk_your_key"},
        timeout=10,
    )
    res.raise_for_status()
    return res.json()

v1 är read-only av design: products:read, orders:read, customers:read och webhooks:read är de enda scopes som finns. Write-scopes vore ett explicit dokumenterat v1.x-beslut — inget planeras i tysthet.