Koble nettsiden og systemene dine til vbeslag

1. Lag en testnøkkel

   Verkstedet lager den under Innstillinger › Koblinger (API) og velger «Test». Den begynner med vb_test_. Hold den på serveren, aldri i nettleseren.

2. Sjekk at nøkkelen virker

   GET /me viser verkstedet, nøkkelen og hva den har lov til.

   GET /meKopier

   curl https://vbeslag.com/api/v1/me \
     -H "Authorization: Bearer $VBESLAG_KEY"

   Svaret du fårKopier

   {
     "organization": { "name": "Nordvik Blikk AS", "shopSlug": "nordvik" },
     "key": { "name": "Prøve", "environment": "test", "purpose": "nettside", … },
     "features": { "api": true, "webhooks": true, … },
     "apiVersion": "v1"
   }

3. Send din første forespørsel

   Med en testnøkkel får den nummer T-000001 og vises ikke i verkstedets lister. Idempotency-Key gjør det trygt å prøve igjen: samme nøkkel og samme innhold gir samme svar, aldri to ordre.

   POST /ordersKopier

   curl https://vbeslag.com/api/v1/orders \
     -H "Authorization: Bearer $VBESLAG_KEY" \
     -H "Content-Type: application/json" \
     -H "Idempotency-Key: 6f1c2e9a-0d5b-4a7e-9f31-2b8c4d7e1a90" \
     -d '{
       "intent": "request",
       "contact": { "name": "Kari Nordmann", "email": "kari@example.no", "mobile": "+4791234567" },
       "title": "Pipebeslag",
       "note": "Se bilde av skissen",
       "lines": [{ "kind": "text", "description": "Pipebeslag 600x600, stål sort", "quantity": 1, "unit": "stk" }],
       "externalRef": "skjema-1042"
     }'

   Svaret du fårKopier

   HTTP/1.1 201 Created
   Location: /api/v1/orders/T-000001
   
   {
     "number": 1, "numberDisplay": "T-000001", "isTest": true,
     "status": "forespurt", "statusLabel": "Forespørsel",
     "lines": [{ "lineNo": 1, "kind": "text", "priceStatus": "pending", … }],
     "totals": { "netOre": null, "currency": "NOK", "priceStatus": "partial" },
     "version": 1, …
   }

   Det samme fra din egen server, med fetch

   fetchKopier

   // På serveren din (aldri i nettleseren: nøkkelen er hemmelig)
   const res = await fetch('https://vbeslag.com/api/v1/orders', {
     method: 'POST',
     headers: {
       Authorization: `Bearer ${process.env.VBESLAG_KEY}`,
       'Content-Type': 'application/json',
       'Idempotency-Key': crypto.randomUUID(),
     },
     body: JSON.stringify({
       intent: 'request',
       contact: { name: form.name, email: form.email, mobile: form.mobile },
       note: form.message,
       lines: [{ kind: 'text', description: form.what, quantity: 1, unit: 'stk' }],
     }),
   })
   const order = await res.json() // order.numberDisplay: «004712»

4. Legg ved et bilde av skissen

   JPEG, PNG, WebP, HEIC eller PDF, høyst 15 MB per fil og 10 filer per ordre.

   POST /orders/{number}/attachmentsKopier

   curl https://vbeslag.com/api/v1/orders/T-000001/attachments \
     -H "Authorization: Bearer $VBESLAG_KEY" \
     -F fil=@skisse.jpg \
     -F type=foto

5. Få beskjed når noe skjer

   Verkstedet legger inn adressen din under Koblinger (API) › Webhooks og trykker «Send testhendelse». Sjekk signaturen som vist under.

   Hendelser (webhooks)Kopier

   POST /din-adresse HTTP/1.1
   Content-Type: application/json
   User-Agent: vbeslag-webhooks/1
   Vbeslag-Event-Id: evt_01JEX4Q7R2M9T5V8W0Y3Z6A1B4
   Vbeslag-Event-Type: order.ready
   Vbeslag-Delivery-Attempt: 1
   Vbeslag-Signature: t=1797590527,v1=5f2b…c9e1

• Nøkkelen sendes i Authorization: Bearer <nøkkel>, aldri i adressen.
• POST /orders og POST /customers krever Idempotency-Key. Bruk en ny UUID per handling, og den samme når du prøver igjen.
• PATCH krever If-Match med versjonen du så ("v3"). En gammel versjon svarer 409 stale_version.
• Felt vi ikke kjenner i det du sender, gir 400 invalid_request med feltet. Svarene kan få nye felt: les bare de du kjenner.
• Lister svarer { data, nextCursor }. Synkroniser med sort=updatedAt, updatedSince og cursor, eller bruk webhooks og GET /events.
• v1 endres ikke uten varsel. Nye felt, operasjoner og hendelser kan komme; noe som fjernes eller endres, kommer først i v2.

Grenser

Hvert svar har X-RateLimit-Limit, X-RateLimit-Remaining og X-RateLimit-Reset. Over grensen svarer vi 429 rate_limited med Retry-After.

Feil

Alle feil har samme form. Velg handling etter code, aldri etter message: teksten kan endres. requestId står også i X-Request-Id; oppgi den hvis du spør om hjelp.

HTTP/1.1 422 Unprocessable Entity
X-Request-Id: req_8f2KQx7Lp0aZtR4mWc1V

{
  "error": {
    "code": "customer_required",
    "message": "Ordren må ha en kunde. …",
    "requestId": "req_8f2KQx7Lp0aZtR4mWc1V",
    "docs": "https://vbeslag.com/utviklere/referanse#feil-customer_required"
  }
}

Alle feilkodene

Verkstedet legger inn en adresse (https) og velger hva den skal få beskjed om. Hver beskjed er en POST med hele objektet slik det var da, og med version, så du ser om du allerede har noe nyere: rekkefølgen er ikke garantert.

Hendelsene

• order.requested · Ny forespørsel
  Virker
• order.received · Ordre mottatt
  Virker
• order.declined · Forespørsel avvist
  Virker
• order.cancelled · Ordre avbrutt
  Virker
• order.in_work · I arbeid
  Virker
• order.ready · Ordre klar
  Virker
• order.ready_undone · Klar angret
  Virker
• order.delivered · Levert eller hentet
  Virker
• order.updated · Ordre endret
  Virker
• order.invoiced · Fakturert
  Virker
• order.invoice_undone · Faktura angret
  Virker
• order.paid · Betalt
  Virker
• order.sms_failed · SMS ikke sendt
  Virker
• order.rework_marked · Merket som omarbeid
  Virker
• order.forwarded · Sendt videre
  Virker
• order.prepaid · Betalt på nett
  Virker
• order.refunded · Refundert
  Virker
• agreement.sent · Avtale sendt
  Virker
• agreement.accepted · Avtale godtatt
  Virker
• agreement.rejected · Avtale avslått
  Virker
• invoice.issued · Faktura sendt
  Virker
• invoice.paid · Faktura betalt
  Virker
• customer.created · Ny kunde
  Virker
• customer.updated · Kunde endret
  Virker
• bending_sheet.sent_for_approval · Bøyeark sendt til kunden
  Virker
• bending_sheet.approved · Godkjent for bukk
  Virker
• bending_sheet.change_requested · Kunden vil endre
  Virker
• bending_sheet.bent · Bøyd
  Virker

POST /din-adresse HTTP/1.1
Content-Type: application/json
User-Agent: vbeslag-webhooks/1
Vbeslag-Event-Id: evt_01JEX4Q7R2M9T5V8W0Y3Z6A1B4
Vbeslag-Event-Type: order.ready
Vbeslag-Delivery-Attempt: 1
Vbeslag-Signature: t=1797590527,v1=5f2b…c9e1

Sjekk signaturen

Vbeslag-Signature er t=<unix-tid>,v1=<hex HMAC-SHA256 av "t.rå-body" med hemmeligheten>. Avvis beskjeder som er eldre enn 5 minutter. Når verkstedet bytter hemmelighet, kommer to v1 i 24 timer: godta den som stemmer.

import crypto from 'node:crypto'

export function verifyVbeslag(rawBody, header, secret, toleranceSec = 300) {
  const parts = header.split(',').map((p) => p.trim().split('='))
  const t = Number(parts.find(([k]) => k === 't')?.[1])
  if (!t || Math.abs(Date.now() / 1000 - t) > toleranceSec) return false
  const expected = crypto.createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex')
  return parts.some(([k, v]) => k === 'v1' && v.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(v), Buffer.from(expected)))
}

function vbeslag_verify(string $rawBody, string $header, string $secret, int $tolerance = 300): bool {
    $t = 0; $sigs = [];
    foreach (explode(',', $header) as $part) {
        [$k, $v] = array_pad(explode('=', trim($part), 2), 2, '');
        if ($k === 't') { $t = (int) $v; }
        if ($k === 'v1') { $sigs[] = $v; }
    }
    if ($t === 0 || abs(time() - $t) > $tolerance) { return false; }
    $expected = hash_hmac('sha256', $t . '.' . $rawBody, $secret);
    foreach ($sigs as $s) { if (hash_equals($expected, $s)) { return true; } }
    return false;
}

Nye forsøk

Svar med en 2xx innen 10 sekunder. Ellers prøver vi igjen i omtrent 45 timer, med lengre pauser for hver gang. 410 Gone slår adressen av med en gang; 50 feil på rad gjør det samme, og verkstedet får beskjed. Vi følger aldri en omdirigering, og vi sender bare til offentlige adresser.

Gikk du glipp av noe?

GET /events gir de samme beskjedene 30 dager tilbake, eldste først etter den siste id-en du har.

curl "https://vbeslag.com/api/v1/events?after=evt_01JEX4Q7R2M9T5V8W0Y3Z6A1B4&types=order.ready" \
  -H "Authorization: Bearer $VBESLAG_KEY"

Noen moduler gir API-et mer. Hver har sin egen del under, og den virker når verkstedet har modulen slått på.

Bygger dere en egen butikk? Send bestillingen som en forespørsel med POST /orders. Når dere har bekreftet den, lager dere en betalingslenke og sender kunden dit. Betalingssiden er vår, så vilkårene og knappen alltid er riktige.

Leveringen regnes av den samme regelen som kassen i butikken, så prisen blir den samme.

• Hent butikken: adressen, måtene å bestille på, leveringsvalgene og vilkårene

  Virker

• Regn ut leveringen til et postnummer

  Virker

• Betal etter bekreftelse: en betalingslenke for en mottatt ordre

  Virker

• Se betalingene på en ordre: betalt, venter på betaling, refundert

  Virker

• Vipps på betalingssiden

  Kommer

Har dere en kantbenk med eget program, eller et planleggingsprogram? Lag en nøkkel med formålet «Maskinen eller planleggingsprogrammet henter dagens bøyeliste». Den kan lese bøyearkene og dagens liste, og merke et ark som bøyd.

Bare verkstedets egne nøkler, og bare når Produksjon er slått på. En kundenøkkel får aldri se bøyearkene.

Dagens bøyeliste kommer som CSV med Accept: text/csv, så den åpnes som kolonner i Excel.

• Dagens bøyeliste, for alle kantbenker eller en, som JSON eller CSV

  Virker

• Kantbenkene i verkstedet

  Virker

• Ett bøyeark: mål, vinkler, utbrett og fradrag

  Virker

• Alle bøyearkene på en ordre

  Virker

• Bøyearket som PDF, med QR-koden pressen leser

  Virker

• Den flate platen som DXF, for klippebord og kappemaskiner

  Virker

• Merk et bøyeark som bøyd

  Virker

• Filer i maskinprodusentenes egne formater

  Kommer

En betalt ordre i WooCommerce blir en forespørsel i vbeslag. Hver vare blir en linje i ord, externalRef er woo-<nummer>, og samme ordre to ganger blir aldri to.

add_action('woocommerce_order_status_processing', function ($order_id) {
    $o = wc_get_order($order_id);
    $lines = [];
    foreach ($o->get_items() as $item) {
        $lines[] = ['kind' => 'text', 'description' => $item->get_name(), 'quantity' => (int) $item->get_quantity(), 'unit' => 'stk'];
    }
    wp_remote_post('https://vbeslag.com/api/v1/orders', [
        'headers' => [
            'Authorization'   => 'Bearer ' . VBESLAG_API_KEY,   // i wp-config.php, aldri i en temafil
            'Content-Type'    => 'application/json',
            'Idempotency-Key' => sha1('woo-' . $order_id),
        ],
        'body'    => wp_json_encode([
            'intent'      => 'request',
            'contact'     => ['name' => $o->get_formatted_billing_full_name(), 'email' => $o->get_billing_email(), 'mobile' => $o->get_billing_phone()],
            'note'        => $o->get_customer_note() ?: 'Fra nettbutikken',
            'lines'       => $lines,
            'externalRef' => 'woo-' . $order_id,
        ]),
        'timeout' => 15,
    ]);
});

Endringslisten under er den samme som i OpenAPI-dokumentet. v1 lever i minst tolv måneder etter at v2 kommer.

• 2026-10-05: Første versjon: nøkler, GET /me, ordre (lese, sende inn, endre, bekrefte, avbryte, status, filer, tidslinje), kunder og prosjekter, GET /events og webhooks med signatur.
• 2026-10-06: Webhooks for avtaler (sendt, godtatt, avslått), fakturaer (sendt, betalt), kunder (ny, endret) og «Merk som omarbeid». Hendelsene har avtalen, fakturaen eller kunden slik den var da hendelsen ble sendt.
• 2026-10-06: Nye tilganger for verkstedets nøkler: production:read, production:status og reports:read. Nye formål på nøkkelen: maskin, regneark og leverandor. En kundenøkkel kan nå ha invoices:read. GET /me kan vise modulene som er slått på og avdelingene.
• 2026-10-06: En ordre kan nå komme fra Min side (source «portal») og fra Beslagsnettet (source «nettverk»). Feltet source kan derfor ha to nye verdier i listOrders og getOrder.
• 2026-10-06: Sju nye webhooks (28 i alt): order.prepaid (betalt på nett, med payment) og order.refunded (med refund) fra Nettbutikk, order.forwarded fra Beslagsnettet, og bending_sheet.sent_for_approval, bending_sheet.approved, bending_sheet.change_requested og bending_sheet.bent fra Produksjon, med gruppen bending_sheet.*. Et bøyeark i en hendelse er WebhookBendingSheet; hele arket får du med GET /bending-sheets/{id}. En kundenøkkels adresse får betalingen, refusjonen og bøyearkene til godkjenning for sin egen kunde, aldri «Bøyd».
• 2026-10-06: Webhooks for avtaler og fakturaer sender nå det samme objektet som GET /agreements/{number} og GET /invoices/{id} (Agreement og Invoice; WebhookAgreement og WebhookInvoice er borte): en avslått avtale har status avvist, en utløpt utlopt, og validUntil og leadDays kan være null; et utkast og «Fakturert i regnskapet» har ingen forfallsdag eller KID, currency er alltid NOK, og en fakturalinjes unit er alltid null.
• 2026-10-06: «Send videre»: en ordre verkstedet sender videre til et annet verksted i Beslagsnettet, får hendelsen order.forwarded, ikke order.cancelled. Lytter du etter order.cancelled for å se at en ordre går ut av listen, lytt også etter order.forwarded.
• 2026-10-06: En kundenøkkel med invoices:read kan nå lese sin egen kundes sendte fakturaer: GET /invoices, GET /invoices/{id} og PDF-en. Aldri et utkast, og en annen kundes faktura svarer 404.
• 2026-10-06: Avrop med POST /orders: agreementNumber og linjer av typen position (positionId, lengthMm, quantity) gir en ordre som er Mottatt, med avtalens priser og source: "avrop". Nye feilkoder: agreement_not_active, position_not_in_agreement, length_over_max og delivery_date_not_allowed (med nextPossibleDate). GET /orders?agreementNumber= lister avropene på en avtale. GET /agreements og GET /invoices tar limit og cursor som alle lister.
• 2026-10-06: Katalog og priser er åpne: GET /catalog/library (beslagsbiblioteket verkstedet kan selge), GET /catalog/products og GET /catalog/products/{id} (beslagene i nettbutikken, med ETag) og POST /prices (pris fra den samme prismotoren som butikken og kalkylen, opptil 50 linjer, ingenting lagres).
• 2026-10-06: POST /prices tar discountCode og deliveryOptionId og regner rabatten og frakten som kassen i nettbutikken: shippingOre er frakten, den nye discountOre er rabatten, og grossOre blir det samme som en bestilling i butikken. En linje som ikke kan prises, svarer med sin egen kode: params_invalid, params_impossible, material_not_offered og price_unavailable (422) og prices_hidden (403). Product og ProductList har fått navn i dokumentet. drawingUrl og 3D-modellen i media kommer.
• 2026-10-06: Avtaler i API-et: GET /agreements og GET /agreements/{number} viser avtalene med posisjoner, leveringsdager og pristabell (pris per stykk ved hver platelengde). Aldri et utkast. En kundenøkkel ser bare sin egen kundes avtaler. Et avrop er en ordre.
• 2026-10-06: Fakturaer: GET /invoices (sendte fakturaer, kreditnotaer og «Fakturert i regnskapet»; utkast bare med includeDrafts=true), GET /invoices/{id} med linjer, KID og ordrene den dekker, og GET /invoices/{id}/pdf, laget på serveren av den utstedte fakturaen. Krever invoices:read og Kontor. Status på bokmål; beløp i hele øre.
• 2026-10-06: Nytt: GET /reports/months/{month} gir tallene for en måned (ordrer, fakturert, betalt og utestående) som summer, aldri kundenavn. Krever reports:read og en nøkkel for verkstedet, ikke en kundenøkkel. GET /me viser nå modulene som er slått på, og avdelingene når verkstedet har to eller flere.
• 2026-10-06: Nettbutikken i API-et: GET /shop (adresse, kassen, leveringsvalg og vilkår), POST /delivery-quotes (leveringen regnet som i kassen), POST /orders/{number}/payment-link (betalingslenke for en mottatt ordre, bare verkstedets nøkler) og GET /orders/{number}/payments (betalingene, aldri en id hos Stripe). Ingen nye tilganger.
• 2026-10-06: De fire operasjonene for nettbutikken står nå under «Nettbutikk» i referansen. POST /delivery-quotes tar subtotalOre, summen av handlekurven i øre, så prisen blir den samme som i kassen når et leveringsvalg er gratis over en sum; uten den regnes leveringen som før. POST /orders/{number}/payment-link krever at kortbetaling er slått på i tillegg til nettbutikken: ellers svarer den 403 feature_not_in_plan med feature: "shop_payments".
• 2026-10-06: Produksjon i API-et: hent et bøyeark med profil, utbrett og godkjenning, som PDF eller som DXF av platen; dagens bøyeliste som JSON eller CSV, for alle kantbenker eller en; kantbenkene; og «Bøyd» fra maskinen eller planleggingsprogrammet. For verkstedets nøkler med production:read og production:status, når Produksjon er slått på.
• 2026-10-06: GET /orders/{number}/bending-sheets gir gjeldende versjon av hvert bøyeark på en ordre, etter arknummer. Alle sju operasjonene for Produksjon står nå under «Produksjon» i referansen. Et verksted uten Produksjon får 403 feature_not_in_plan med feature: "produksjon" før noe leses.
• 2026-10-06: En ordre har nå production: hvor mange bøyeark den har (bendingSheets), hvor mange som er bøyd (bent) og hvor mange som venter på at kunden godkjenner (waitingForCustomer). Feltet er null når verkstedet ikke har Produksjon, og for en kundenøkkel. Det følger ordren i svarene fra ordreoperasjonene, ikke i webhooks eller GET /events.

Hver operasjon med rettigheter, felt, svar, feilkoder og eksempel.

OpenAPI-dokumentet kan importeres i Postman, Insomnia eller Swagger UI.

Skriv til oss, og ta med requestId fra svaret.