Send inn en ordre eller en forespørsel

POST/api/v1/orders

Virker

Blir en ordre i verkstedets liste med neste nummer, akkurat som en lapp, en ordre fra disken eller fra nettbutikken. En forespørsel (intent: request) venter på at verkstedet bekrefter. Et avrop på en godtatt avtale (agreementNumber og position-linjer, modulen Avtaler) blir Mottatt med avtalens priser; en kundenøkkel når bare sin egen kundes avtaler. Idempotency-Key gjør det trygt å prøve igjen.

Rettigheter: orders:write
Kundenøkkel: Ja, for sine egne
Grense: skriving, 30 i minuttet
Siden: 5. oktober 2026

Parametre

Overskrifter

Idempotency-KeystringMå med8–255 tegn
8–255 tegn. Bruk en UUID per forsøk på en handling; samme nøkkel og samme innhold gir samme svar igjen.

Det du sender

application/jsonCreateOrderRequestMå med

intentstringMå med
request: en Forespørsel verkstedet bekrefter («Ingenting er avtalt før du har bekreftet»). order: rett inn som Mottatt (bare verkstedets egne nøkler, med kunde).
Verdierorderrequest
customer{ id } | { number } | { orgNr }kan være null
Kunden: { "id" }, { "number" } (kundenummeret i registeret) eller { "orgNr" }.
Vis 3 varianterSkjul 3 varianter
1. 1{ id }
  - idstring · uuidMå med
    UUID
2. 2{ number }
  - numberintegerMå medminst 1
3. 3{ orgNr }
  - orgNrstringMå medmønster ^\d{3} ?\d{3} ?\d{3}$
contactContactInputkan være null
Vis 5 feltSkjul 5 felt
- namestringMå med1–200 tegn
- companystringkan være nullhøyst 200 tegn
- orgNrstringkan være nullhøyst 20 tegn
- emailstringkan være nullhøyst 300 tegn
- mobilestringkan være nullhøyst 30 tegn
  Norsk mobilnummer; sendes som +47…
createCustomerboolean
Lag kunden i registeret fra contact (bare med en ekte nøkkel som er verkstedets egen).
agreementNumberintegerkan være nullminst 1
Et avrop på en godtatt avtale (intent: "order", bare position-linjer). Kunden, prosjektet og prisene er avtalens; en kundenøkkel når bare sin egen kundes avtaler. Ordren får source: "avrop".
projectNostringkan være nullhøyst 60 tegn
ordererstringkan være nullhøyst 100 tegn
customerPostringkan være nullhøyst 100 tegn
titlestringkan være nullhøyst 200 tegn
notestringkan være nullhøyst 2000 tegn
deliveryobjectkan være null
Vis 3 feltSkjul 3 felt
- modestringkan være null
  Verdierhentinglevering
- requestedDatestring · datekan være nulleks. 2026-12-18
  Dato på Oslo-kalenderen, ÅÅÅÅ-MM-DD
- addressobjectkan være null
  Vis 3 feltSkjul 3 felt
  - linestringMå med1–300 tegn
  - postalCodestringkan være nullhøyst 10 tegn
  - citystringkan være nullhøyst 100 tegn
lines(TextLineInput | PositionLineInput)[]høyst 1000
Vis 2 varianterSkjul 2 varianter
1. 1TextLineInput
  - kindstringMå med
    Alltid "text"
  - descriptionstringMå med1–2000 tegn
  - quantitynumberMå med
    1–500
  - unitstring
    Verdierstkmm2
2. 2PositionLineInput
  - kindstringMå med
    Alltid "position"
  - positionIdstring · uuidMå med
    Posisjonen fra GET /agreements/{number} (positions[].id).
  - lengthMmintegerMå med
    Platelengden i mm. Høyst avtalens maxLengthMm.
  - quantityintegerMå med
    Antall stykk.
externalRefstringkan være nullhøyst 100 tegn
Din egen id (for eksempel woo-18822). Unik per nøkkel: samme id igjen gir 409 med ordrenummeret.

Svaret

201CreatedOrdren er lagret. Location peker på den.

Overskrifter

Locationstring
/api/v1/orders/<nummer>

application/jsonOrder

Vis alle 39 feltSkjul de 39 feltene

idstring · uuidMå med
UUID
numberintegerMå med
Ordrenummeret i verkstedets serie (testordre har sin egen serie).
numberDisplaystringMå med
«004711», eller «T-000012» for en testordre.
isTestbooleanMå med
sourcestringMå med
Hvor ordren kom fra (lapp, manuell, tilbud, avrop, nettbutikk, api, import). Kan få nye verdier: les en ukjent verdi som «annet».
Verdierlappmanuelltilbudavropnettbutikkapiimportportalnettverk
channelstringMå medkan være null
Navnet på nøkkelen eller butikkens «kilde»: der ordren kom fra.
statusstringMå med
Lagret status: forespurt, mottatt, i_arbeid, klar, levert, fakturert, betalt, avbrutt. Stigen får aldri et nytt trinn uten v2.
Verdierforespurtmottatti_arbeidklarlevertfakturertbetaltavbrutt
statusLabelstringMå med
Statusen med appens ord: Forespørsel, Mottatt, I arbeid, Klar, Levert/Hentet, Fakturert, Betalt, Avbrutt/Avvist.
statusChangedAtstring · date-timeMå medeks. 2026-12-14T09:03:00.000Z
Tidspunkt, ISO 8601 i UTC
customerobjectMå medkan være null
Vis 3 feltSkjul 3 felt
- idstring · uuidMå med
  UUID
- numberintegerMå medkan være null
- namestringMå med
contactobjectMå medkan være null
Bare så lenge ordren ikke har en kunde (en forespørsel).
Vis 5 feltSkjul 5 felt
- namestringMå med
- companystringMå medkan være null
- orgNrstringMå medkan være null
- emailstringMå medkan være null
- mobilestringMå medkan være null
projectNostringMå medkan være null
ordererstringMå medkan være null
customerPostringMå medkan være null
titlestringMå medkan være null
notestringMå medkan være null
agreementobjectMå medkan være null
Vis 1 feltSkjul 1 felt
- idstring · uuidMå med
  UUID
deliveryobjectMå med
Vis 4 feltSkjul 4 felt
- modestringMå medkan være null
  Verdierhentinglevering
- requestedDatestring · dateMå medkan være nulleks. 2026-12-18
  Dato på Oslo-kalenderen, ÅÅÅÅ-MM-DD
- deliveryDatestring · dateMå medkan være nulleks. 2026-12-18
  Dato på Oslo-kalenderen, ÅÅÅÅ-MM-DD
- addressobjectMå medkan være null
  Vis 3 feltSkjul 3 felt
  - linestringMå med
  - postalCodestringMå medkan være null
  - citystringMå medkan være null
linesOrderLine[]Må med
Vis 13 feltSkjul 13 felt
- lineNointegerMå med
- kindstringMå med
  product (et beslag fra butikken), position (en avtaleposisjon), text (en linje i ord), fee (frakt, emballasje, gebyr). Kan få nye verdier.
  Verdierproductpositiontextfee
- descriptionstringMå med
- quantitynumberMå med
- unitstringMå med
  Verdierstkmm2time
- lengthMmintegerMå medkan være null
- productIdstring · uuidMå medkan være null
  UUID
- agreementPositionIdstring · uuidMå medkan være null
  UUID
- profileobjectMå medkan være null
  Vis 5 feltSkjul 5 felt
  - familystringMå medkan være null
  - paramsRecord<string, number>Må mednøklene er tekst
  - materialstringMå medkan være null
  - colourstringMå medkan være null
  - colourSidestringMå medkan være null
- priceStatusstringMå med
  pending: «Pris kommer»; hidden: en kundenøkkel og en butikk som skjuler prisene.
  Verdierpricedpendinghidden
- unitPriceOreintegerMå medkan være null
  Hele øre (1 kr = 100 øre)
- netOreintegerMå medkan være null
  Hele øre (1 kr = 100 øre)
- vatBpintegerMå medkan være null0–10000
  Moms i basispunkter: 2500 = 25 %
totalsobjectMå med
Vis 5 feltSkjul 5 felt
- netOreintegerMå medkan være null
  Hele øre (1 kr = 100 øre)
- vatOreintegerMå medkan være null
  Hele øre (1 kr = 100 øre)
- grossOreintegerMå medkan være null
  Hele øre (1 kr = 100 øre)
- currencystringMå med
  Alltid "NOK"
- priceStatusstringMå med
  priced: alle linjer har pris; partial: noen linjer venter på pris; in_kalkyle: prisen står i kalkylen; hidden: skjult for en kundenøkkel. Beløpene er null når de ikke er kjent.
  Verdierpricedpartialin_kalkylehidden
hasKalkylebooleanMå medkan være null
Om ordren er priset i en kalkyle; null for en kundenøkkel.
stickerNumbersinteger[]Må med
Lappnumrene som er knyttet til ordren.
readyWithoutReceiptbooleanMå med
«Klar uten mottak».
readySmsobjectMå medkan være null
Klar-SMS-en: status og tider, aldri nummer eller tekst. Null for en kundenøkkel.
Vis 3 feltSkjul 3 felt
- statusstringMå med
  Verdierqueuedcancelledsendingsentdeliveredfailed
- sendAfterstring · date-timeMå medkan være nulleks. 2026-12-14T09:03:00.000Z
  Tidspunkt, ISO 8601 i UTC
- sentAtstring · date-timeMå medkan være nulleks. 2026-12-14T09:03:00.000Z
  Tidspunkt, ISO 8601 i UTC
invoiceobjectMå medkan være null
Vis 5 feltSkjul 5 felt
- idstring · uuidMå med
  UUID
- kindstringMå med
  Verdierinvoicecredit_noteerp_mark
- numberstringMå medkan være null
- issuedAtstring · date-timeMå medkan være nulleks. 2026-12-14T09:03:00.000Z
  Tidspunkt, ISO 8601 i UTC
- erpNostringMå medkan være null
attachmentsAttachment[]Må med
Vis 5 feltSkjul 5 felt
- idstring · uuidMå med
  UUID
- kindstringMå med
  Verdierfototegningpdf
- contentTypestringMå med
- bytesintegerMå med
- createdAtstring · date-timeMå medeks. 2026-12-14T09:03:00.000Z
  Tidspunkt, ISO 8601 i UTC
externalRefstringMå medkan være null
Din egen id for ordren, unik per nøkkel.
createdAtstring · date-timeMå medeks. 2026-12-14T09:03:00.000Z
Tidspunkt, ISO 8601 i UTC
receivedAtstring · date-timeMå medkan være nulleks. 2026-12-14T09:03:00.000Z
Tidspunkt, ISO 8601 i UTC
inWorkAtstring · date-timeMå medkan være nulleks. 2026-12-14T09:03:00.000Z
Tidspunkt, ISO 8601 i UTC
readyAtstring · date-timeMå medkan være nulleks. 2026-12-14T09:03:00.000Z
Tidspunkt, ISO 8601 i UTC
deliveredAtstring · date-timeMå medkan være nulleks. 2026-12-14T09:03:00.000Z
Tidspunkt, ISO 8601 i UTC
invoicedAtstring · date-timeMå medkan være nulleks. 2026-12-14T09:03:00.000Z
Tidspunkt, ISO 8601 i UTC
paidAtstring · date-timeMå medkan være nulleks. 2026-12-14T09:03:00.000Z
Tidspunkt, ISO 8601 i UTC
cancelledAtstring · date-timeMå medkan være nulleks. 2026-12-14T09:03:00.000Z
Tidspunkt, ISO 8601 i UTC
cancelReasonstringMå medkan være null
updatedAtstring · date-timeMå medeks. 2026-12-14T09:03:00.000Z
Tidspunkt, ISO 8601 i UTC
versionintegerMå med
Øker ved hver endring. Send den tilbake i If-Match: "v<version>".
productionOrderProductionkan være null
Bøyearkene på ordren, når verkstedet har Produksjon; null uten Produksjon og for en kundenøkkel. Med i svarene fra ordreoperasjonene, ikke i webhooks og GET /events. Et bøyd ark endrer ikke version, så når production ikke er null, svarer If-None-Match aldri 304.
Vis 3 feltSkjul 3 felt
- bendingSheetsintegerMå medminst 0
  Bøyearkene på ordren: den gjeldende versjonen av hvert, uten de avbrutte.
- bentintegerMå medminst 0
  Hvor mange av dem som er bøyd.
- waitingForCustomerintegerMå medminst 0
  Hvor mange som venter på at kunden godkjenner («Venter på kunden»).

Feilkoder

Alle feil har samme form. Velg handling etter code, aldri etter message. Les mer under Feil.

400Bad Request

invalid_jsonInnholdet er ikke gyldig JSON.
invalid_requestNoe i forespørselen er feil eller ukjent. fields sier hva.

401Unauthorized

unauthorizedNøkkelen mangler, er feil, er slått av eller har gått ut. En nøkkel som slås av, slutter å virke innen 1 minutt.

403Forbidden

account_closedVerkstedet er stengt.
customer_key_not_allowedEn kundenøkkel kan ikke gjøre dette.
dpa_requiredVerkstedet må godta databehandleravtalen før koblinger kan brukes.
feature_not_in_planVerkstedet har ikke slått på delen dette trenger. feature sier hvilken.
insufficient_scopeNøkkelen har ikke lov til dette. requiredScope sier hvilken rett som mangler.
test_key_not_allowedEn testnøkkel kan ikke dette: den endrer aldri kunderegisteret, og et avrop er alltid en ekte ordre.

409Conflict

duplicate_external_refDu har allerede sendt en ordre med denne externalRef. existingNumber er ordrenummeret.
idempotency_in_progressEn forespørsel med samme Idempotency-Key holder på. Prøv igjen om litt.
key_owner_missingBrukeren som laget nøkkelen finnes ikke lenger. Lag en ny nøkkel.

422Unprocessable Entity

agreement_not_activeAvtalen tar ikke imot avrop: den er ikke godtatt, er utløpt eller erstattet, eller finnes ikke for denne nøkkelen. reason sier hvorfor.
contact_invalidKontakten trenger et navn og en e-post eller et norsk mobilnummer.
content_requiredOrdren må ha minst en linje eller en merknad (note) på minst 3 tegn.
customer_fixed_by_keyDenne nøkkelen hører til en kunde, og ordren må være for den kunden.
customer_invalidNoe i kundefeltene er feil. fields sier hva.
customer_requiredOrdren må ha en kunde. Send customer, eller contact med createCustomer: true.
date_invalidDatoen er ikke en gyldig dag (ÅÅÅÅ-MM-DD).
delivery_date_not_allowedAvtalen leverer ikke den dagen. nextPossibleDate er den første dagen som går.
idempotency_key_reusedDenne Idempotency-Key ble brukt på en annen forespørsel. Bruk en ny nøkkel for ny handling.
intent_not_allowedEn kundenøkkel sender forespørsler ("intent": "request"), eller avrop på en godtatt avtale (agreementNumber).
length_over_maxLengden er over det avtalen tillater (maxLengthMm). fields sier hvilken linje.
orderer_requiredDenne kunden krever bestiller (orderer).
position_not_in_agreementPosisjonen hører ikke til denne avtalen. Hent posisjonene med GET /agreements/{number}. fields sier hvilken linje.
project_no_requiredDenne kunden krever prosjektnummer (projectNo).
quantity_invalidAntallet må være mellom 1 og 500.
too_many_linesOrdren kan ha høyst 100 linjer.

428Precondition Required

idempotency_key_requiredSend Idempotency-Key med denne forespørselen.

429Too Many Requests

rate_limitedFor mange kall. Vent retryAfterSeconds sekunder.

500Internal Server Error

internalNoe gikk galt hos oss. Feilen er meldt. Oppgi requestId hvis du spør.

POST/orders

curl https://vbeslag.com/api/v1/orders \
  -H "Authorization: Bearer vb_test_…" \
  -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 600×600, stål sort",
        "quantity": 1,
        "unit": "stk"
      }
    ],
    "externalRef": "woo-18822"
  }'

const res = await fetch('https://vbeslag.com/api/v1/orders', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer vb_test_…',
    'Content-Type': 'application/json',
    'Idempotency-Key': crypto.randomUUID(),
  },
  body: JSON.stringify({
    intent: 'request',
    contact: {
      name: 'Kari Nordmann',
      email: 'kari@example.no',
      mobile: '+4791234567',
    },
    title: 'Pipebeslag',
    note: 'Se bilde av skissen',
    lines: [
      {
        kind: 'text',
        description: 'Pipebeslag 600×600, stål sort',
        quantity: 1,
        unit: 'stk',
      },
    ],
    externalRef: 'woo-18822',
  }),
})
const data = await res.json()

$ch = curl_init('https://vbeslag.com/api/v1/orders');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST  => 'POST',
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer vb_test_…',
        'Content-Type: application/json',
        'Idempotency-Key: ' . bin2hex(random_bytes(16)),
    ],
    CURLOPT_POSTFIELDS     => json_encode([
        'intent'      => 'request',
        'contact'     => [
            'name'   => 'Kari Nordmann',
            'email'  => 'kari@example.no',
            'mobile' => '+4791234567',
        ],
        'title'       => 'Pipebeslag',
        'note'        => 'Se bilde av skissen',
        'lines'       => [
            [
                'kind'        => 'text',
                'description' => 'Pipebeslag 600×600, stål sort',
                'quantity'    => 1,
                'unit'        => 'stk',
            ],
        ],
        'externalRef' => 'woo-18822',
    ]),
    CURLOPT_RETURNTRANSFER => true,
]);
$data = json_decode(curl_exec($ch), true);

Svaret

HTTP/1.1 201 Created
Content-Type: application/json
Location: /api/v1/orders/004711

{
  "id": "2809d176-2724-4896-a690-52c5303f6825",
  "number": 4711,
  "numberDisplay": "004711",
  "isTest": false,
  "source": "lapp",
  "channel": "Nettsiden",
  "status": "forespurt",
  "statusLabel": "Forespørsel",
  "statusChangedAt": "2026-12-14T09:03:00.000Z",
  "customer": {
    "id": "87febf70-b0ae-4c70-a5cd-01339c01bce3",
    "number": 312,
    "name": "Byggmester Hansen AS"
  },
  "contact": {
    "name": "Kari Nordmann",
    "company": "Byggmester Hansen AS",
    "orgNr": "914276640",
    "email": "kari@example.no",
    "mobile": "+4791234567"
  },
  "projectNo": "P-2231",
  "orderer": "Ole",
  "customerPo": "PO-5512",
  "title": "Pipebeslag",
  "note": "Se bilde av skissen",
  "agreement": {
    "id": "b91241c6-ec40-4fe6-a9ec-63d5046dd995"
  },
  "delivery": {
    "mode": "henting",
    "requestedDate": "2026-12-18",
    "deliveryDate": "2026-12-18",
    "address": {
      "line": "Industriveien 4",
      "postalCode": "9405",
      "city": "Harstad"
    }
  },
  "lines": [
    {
      "lineNo": 1,
      "kind": "product",
      "description": "Vindskie 150×40, stål sort",
      "quantity": 1.5,
      "unit": "stk",
      "lengthMm": 2500,
      "productId": "8bddf77d-f04d-426d-adad-d3d8e49df3ce",
      "agreementPositionId": "6b6b0ced-eb0a-44dd-a1c7-5cc8a808d05e",
      "profile": {
        "family": "tekst",
        "params": {
          "a": 1.5
        },
        "material": "Stål",
        "colour": "Sort",
        "colourSide": "tekst"
      },
      "priceStatus": "priced",
      "unitPriceOre": 61200,
      "netOre": 61200,
      "vatBp": 2500
    }
  ],
  "totals": {
    "netOre": 61200,
    "vatOre": 61200,
    "grossOre": 61200,
    "currency": "NOK",
    "priceStatus": "priced"
  },
  "hasKalkyle": false,
  "stickerNumbers": [
    1
  ],
  "readyWithoutReceipt": false,
  "readySms": {
    "status": "queued",
    "sendAfter": "2026-12-14T09:03:00.000Z",
    "sentAt": "2026-12-14T09:03:00.000Z"
  },
  "invoice": {
    "id": "78dc0317-6985-41e7-aeb9-9deed0da1e24",
    "kind": "invoice",
    "number": "tekst",
    "issuedAt": "2026-12-14T09:03:00.000Z",
    "erpNo": "tekst"
  },
  "attachments": [
    {
      "id": "6fcbc93f-bc8d-4b8f-a1c5-f08647b0754c",
      "kind": "foto",
      "contentType": "image/jpeg",
      "bytes": 284123,
      "createdAt": "2026-12-14T09:03:00.000Z"
    }
  ],
  "externalRef": "woo-18822",
  "createdAt": "2026-12-14T09:03:00.000Z",
  "receivedAt": "2026-12-14T09:03:00.000Z",
  "inWorkAt": "2026-12-14T09:03:00.000Z",
  "readyAt": "2026-12-14T09:03:00.000Z",
  "deliveredAt": "2026-12-14T09:03:00.000Z",
  "invoicedAt": "2026-12-14T09:03:00.000Z",
  "paidAt": "2026-12-14T09:03:00.000Z",
  "cancelledAt": "2026-12-14T09:03:00.000Z",
  "cancelReason": "tekst",
  "updatedAt": "2026-12-14T09:03:00.000Z",
  "version": 3,
  "production": {
    "bendingSheets": 1,
    "bent": 1,
    "waitingForCustomer": 1
  }
}