Nøkler og tilgang

Hvert kall til API-et har med en nøkkel. En nøkkel hører til ett verksted, og den gir bare tilgang til det verkstedet. Et annet verksted ser aldri noe av ditt.

Test og ekte

Det finnes to slags nøkler. Start alltid med en testnøkkel.

	Testnøkkel	Ekte nøkkel
Begynner med	`vb_test_`	`vb_live_`
Ordrene	Testordre med egen serie (`T-000012`) som ikke vises i listene	Havner i ordrelisten med neste nummer, akkurat som en lapp
SMS og e-post	Sendes aldri	Kunden får SMS når ordren er klar
Kunderegisteret	Leser de ekte kundene, men endrer dem aldri	Kan endres med `customers:write`

En testnøkkel teller heller ikke på regningen, og den kan ikke sende avrop: et avrop er alltid en ekte ordre. Testordrene slettes etter 30 dager. Verkstedet kan også slette alle testordre med en gang med «Slett testdata» under Koblinger (API). Ekte ordre røres ikke.

Send nøkkelen

Nøkkelen sendes i Authorization-overskriften, aldri i adressen.

Overskriften


Authorization: Bearer vb_test_…

En nøkkel som mangler, er feil, er slått av eller har gått ut, gir samme svar: 401 unauthorized. Fra samme adresse godtar vi høyst 20 feil nøkler på 10 minutter. Se Grenser.

Hold nøkkelen på serveren

Nøkkelen er hemmelig. Den hører hjemme på serveren din, aldri i nettleseren.

Den vises bare en gang, når verkstedet lager den. Verkstedet lagrer den et trygt sted, eller gir den rett til den som lager nettsiden.
Les den fra miljøet, som VBESLAG_KEY i eksemplene, og ikke skriv den inn i koden.
I WordPress står den i wp-config.php, aldri i en temafil. Se WooCommerce-guiden.
Et skjema på nettsiden sender til din egen server, og serveren kaller vbeslag. Nettleseren ser aldri nøkkelen.

Slik lager verkstedet en nøkkel

Slå på Koblinger (API)

Koblinger (API) må være slått på under Abonnement, og databehandleravtalen må være godtatt, også under Abonnement. Uten den svarer API-et 403 dpa_required.

Velg hva nøkkelen skal brukes til

Under Innstillinger › Koblinger (API) trykker verkstedet «Lag ny nøkkel» og svarer på «Hva skal nøkkelen brukes til?». Formålet gir rettene, se under.

Gi nøkkelen et navn

For eksempel «Nettsiden» eller «Hansen Bygg innkjøp», høyst 60 tegn. Navnet står på ordrene som kommer inn, så kontoret ser hvor de kom fra.

Velg test eller ekte

Testordre får egne nummer (T-…), vises ikke i listene, det sendes aldri SMS, og de slettes etter 30 dager. Ekte ordre havner i ordrelisten med neste nummer.

Ta vare på nøkkelen

Nøkkelen vises bare nå. Verkstedet lagrer den et trygt sted, eller gir den rett til deg.

Bare den som styrer nettbutikken (eier eller administrator), kan lage og slå av nøkler. Et verksted kan ha 10 nøkler i bruk samtidig. Under «Siste kall» ser verkstedet de siste 50 kallene med hver nøkkel.

Åpne Koblinger (API)

Verkstedsnøkkel og kundenøkkel

En verkstedsnøkkel ser hele verkstedet.

En kundenøkkel hører til en kunde. Den ser bare den kundens ordre, avtaler og sendte fakturaer, sender forespørsler og avrop på kundens godtatte avtaler, og kan trekke tilbake sine egne forespørsler. Den kan lage 100 nye ordre i døgnet.

Et annet verksteds eller en annen kundes ordre eller faktura svarer 404 not_found, aldri 403. En 403 handler bare om nøkkelens egne rettigheter.

Formål

Verkstedet krysser ikke av for rettighetene en og en. Det velger hva nøkkelen skal brukes til, og formålet gir rettene. «Velg selv» ligger under «Vis flere valg» for den som vil krysse av selv. GET /me viser formålet i key.purpose.

«Nettsiden min sender inn ordre»nettside
Skjemaet eller nettbutikken på nettsiden legger ordre og forespørsler rett i ordrelisten.
catalog:read prices:read orders:read orders:write
«Mitt eget system leser og oppdaterer ordre»eget_system
For eksempel et planleggingsprogram eller en etikettskriver: ser ordrene og setter dem klar.
orders:read orders:write orders:status customers:read invoices:read
«En kunde sender forespørsler fra sitt eget system»kunde
Kunden ser bare sine egne ordre. Avrop på avtale kommer.
agreements:read orders:read orders:write catalog:read prices:read
Kundenøkkel: hører til en kunde
«Velg selv»egendefinert
Kryss av for akkurat det nøkkelen skal få lov til.
Rettene verkstedet krysser av for
«Maskinen eller planleggingsprogrammet henter dagens bøyeliste»maskin
Programmet ser bøyearkene og kan merke dem som bøyd. Det ser ingen priser.
production:read production:status
«Regnearket vårt henter månedstallene»regneark
Regnearket får tallene for en måned. Det ser ingen kundenavn.
reports:read
«Et annet verksted kjøper fra oss»leverandor
Lages bare når det andre verkstedet godtar koblingen. Verkstedet ser bare sine egne ordre og fakturaer.
catalog:read prices:read orders:read orders:write invoices:read
Kundenøkkel: hører til en kundeVelges ikke på nøkkelskjermen

Rettigheter

Hver operasjon krever en rett (x-scopes i OpenAPI-dokumentet). Mangler nøkkelen retten, svarer API-et 403 insufficient_scope, og requiredScope sier hvilken rett som mangler. GET /me krever bare en nøkkel, og viser hva nøkkelen har lov til. GET /openapi.json krever ingen nøkkel.

catalog:readSe beslagene i butikken
GET/catalog/library GET/catalog/products GET/catalog/products/{id}GET/shop
Kundenøkkel kan ha denTestnøkkel kan ha den
prices:readRegne ut priser
POST/prices POST/delivery-quotes
Kundenøkkel kan ha denTestnøkkel kan ha den
orders:readSe ordre
GET/orders GET/orders/{number}GET/orders/{number}/attachments/{id}GET/orders/{number}/events GET/events GET/orders/{number}/payments
Kundenøkkel kan ha denTestnøkkel kan ha den
orders:writeLegge inn og endre ordre
POST/orders PATCH/orders/{number}POST/orders/{number}/confirm POST/orders/{number}/cancel POST/orders/{number}/attachments POST/orders/{number}/payment-link
Kundenøkkel kan ha denTestnøkkel kan ha den
orders:statusSette ordre i arbeid, klar og levert
POST/orders/{number}/status
Aldri for en kundenøkkelTestnøkkel kan ha den
agreements:readSe avtaler
GET/agreements GET/agreements/{number}
Kundenøkkel kan ha denTestnøkkel kan ha den
customers:readSe kunderegisteret
GET/customers GET/customers/{id}GET/customers/{id}/projects
Aldri for en kundenøkkelTestnøkkel kan ha den
customers:writeEndre kunderegisteret
POST/customers PATCH/customers/{id}
Aldri for en kundenøkkelAldri for en testnøkkel
invoices:readSe fakturaer
GET/invoices GET/invoices/{id}GET/invoices/{id}/pdf
Kundenøkkel kan ha denTestnøkkel kan ha den
production:readSe bøyeark og dagens bøyeliste
GET/orders/{number}/bending-sheets GET/bending-sheets/{id}GET/bending-sheets/{id}/pdf GET/bending-sheets/{id}/dxf GET/production/queue GET/presses
Aldri for en kundenøkkelTestnøkkel kan ha denBare verkstedets egne nøkler
production:statusMerke bøyeark som bøyd
POST/bending-sheets/{id}/bent
Aldri for en kundenøkkelTestnøkkel kan ha denBare verkstedets egne nøkler
reports:readSe månedstallene
GET/reports/months/{month}
Aldri for en kundenøkkelTestnøkkel kan ha denBare verkstedets egne nøkler

Slå av en nøkkel

Verkstedet trykker «Slå av» ved nøkkelen under Koblinger (API). Alt som bruker den, slutter å virke innen 1 minutt, og får 401 unauthorized. Det kan ikke angres: verkstedet lager en ny nøkkel om det trenger den igjen.

Dette holder nøkkelen trygg

Nøkkelen gir bare tilgang til ett verksted. Et annet verksted ser aldri noe av det.
Verkstedet kan slå en nøkkel av når som helst. Den slutter å virke innen 1 minutt.
Påslaget og innkjøpsprisene vises aldri.
En testnøkkel lager testordre med egne nummer (T-…), sender aldri SMS eller e-post, og testordrene slettes etter 30 dager.