Partner-API — referens

Provisionera låna/lämna-resurser i en vaschego-organisation från er egen plattform, och få händelserna tillbaka via signerade webhooks. Översikt och sammanhang: integrationssidan. API-nycklar utfärdas per organisation och partner — hör av er till api@vaschego.se så ordnar vi en.

Testa direkt — sandlåda

Ni behöver inget avtal för att börja laborera. Fyll i er e-post så skapas en egen sandlåde-organisation med en egen nyckel — nyckeln landar i inkorgen inom någon minut. Sandlådan är på riktigt (samma API, samma publika resurssidor, samma webhooks) men medvetet begränsad:

Nyckelns livslängd	30 dagar (kan förnyas — hör av er)
Resurser	max 10 (`sandbox_limit` därefter)
Organisationen	märkt som testmiljö, räknas inte i någon statistik
Adminåtkomst	logga in på /admin med samma e-post (engångslänk) och se din sandlåda som en riktig kund

GET /ping svarar med "sandbox": true och key_expires_at så era system vet vilket läge de kör i. När vi har ett avtal på plats ersätts sandlådan med en produktionsnyckel utan utgångsdatum — koden ni skrivit behåller ni rakt av.

Bas-URL och autentisering

https://www.vaschego.se/api/partner/v1

Varje anrop bär nyckeln i headern:

Authorization: Bearer vpk_…

Nyckeln visas exakt en gång vid utfärdande och lagras hashad hos oss. Fel svarar alltid med samma form:

{ "error": { "code": "unauthorized", "message": "…" } }

Kod	Betyder
`unauthorized`	nyckel saknas, är ogiltig eller återkallad (HTTP 401/403)
`not_found`	okänd rutt eller okänt partner_item_id (404)
`invalid_payload`	body eller parametrar stämmer inte (400/405/422)
`account_limit`	organisationens kontotyp tillåter inte fler resurser (403)
`conflict`	t.ex. endpoint-taket nått (409)
`sandbox_limit`	sandlådans resurstak (10) är nått — dags för ett riktigt avtal (403)
`internal`	vårt fel — försök igen, och hör av er om det kvarstår (500)

Nyckeltyper och organisationer

Sandlåde-nycklar är låsta till en organisation — rutterna nedan används direkt. Med ett partneravtal får ni i stället en partnernyckel: en enda nyckel som skapar och hanterar era kundorganisationer via API:t, var och en separat brandad (accentfärg + er logotyp-URL) och med eget band-tak. Resurs- och webhook-rutterna nästlas då under orgen: /v1/orgs/{org}/resources. En partnernyckel når bara organisationer den själv skapat.

POST

/orgs

{
  "name": "Halmstads kommun – Återbruket",
  "resource_cap": 50,
  "branding": { "accent": "#2d6a4f", "logo_url": "https://er-cdn.example.com/kund-logo.svg" },
  "admin_email": "kontakt@kund.se"
}

resource_cap (default 25) är orgens band-tak — mekaniskt: vid fullt band svarar provisioneringen account_limit tills ni höjer det via PATCH /orgs/{org}. Er fakturering följer bandet, så taket är er kostnadskontroll. GET /orgs listar era organisationer med active_resources per org.

Resurser

En provisionerad resurs är alltid av typen låna/lämna: låntagaren öppnar resursens publika sida — utan konto — lånar och lämnar tillbaka. partner_item_id är er egen artikel-nyckel; alla anrop är idempotenta på den.

GET

/ping

Auth-koll. Svarar med org-id, provider och organisationens namn.

POST

/resources

Skapa eller uppdatera (idempotent upsert). profile: equipment (pryl), bike-pool (cykel) eller space (utrymme). building_label kopplas till en befintlig fastighet med samma namn eller skapar en ny — aldrig dubbletter. Finns partner_item_id redan uppdateras namn/beskrivning/paus i stället.

{
  "partner_item_id": "artikel-8f3a",
  "name": "Slagborr Bosch GBH 2-26",
  "profile": "equipment",
  "description": "Utlånas med två batterier.",
  "building_label": "Kontor Malmö",
  "address": "Storgatan 1, Malmö",
  "paused": false
}

Svar 201 (skapad) eller 200 (fanns, uppdaterad):

{
  "created": true,
  "partner_item_id": "artikel-8f3a",
  "resource_id": "…",
  "resource_slug": "ab12cd",
  "name": "Slagborr Bosch GBH 2-26",
  "status": "available",
  "resource_url": "https://www.vaschego.se/{orgSlug}/ab12cd",
  "kiosk_url": "https://www.vaschego.se/kiosk/{orgSlug}/ab12cd"
}

resource_url är låntagarens sida — länka eller QR-koda den från er katalog. kiosk_url är en chrome-fri helskärmsvariant för skärmar. status: available | occupied (utlånad) | closed | paused | archived.

Lån med återlämningsdag

Med "loan_mode": "due_date" väljer låntagaren återlämningsdag när lånet startar; max_loan_days sätter maxlånetiden (servern avvisar längre lån) och "advance_booking": true tillåter förbokning med start- och slutdatum. Intervallet är halvöppet — återlämningsdagen är fri för nästa låntagare. När resursen är utlånad innehåller svaret due_date (pågående låns återlämningsdag) — visa "tillbaka 25 aug" direkt i er katalog. loan_mode kan inte ändras i efterhand (409) — arkivera och skapa ny.

{
  "partner_item_id": "artikel-9c1b",
  "name": "Släpkärran",
  "loan_mode": "due_date",
  "max_loan_days": 7
}

→ 201 (utdrag)
{
  "created": true,
  "status": "available",
  "loan_mode": "due_date",
  "max_loan_days": 7,
  "due_date": null
}

GET

/resources

Lista era provisionerade resurser, samma form som ovan.

GET

/resources/{partner_item_id}

Hämta en resurs med aktuell live-status.

PATCH

/resources/{partner_item_id}

Valfri delmängd av { "name", "description", "paused" }.

DELETE

/resources/{partner_item_id}

Arkiverar (idempotent). Skiljelinjen paus/arkiv: pausad syns men kan inte lånas ("tillfälligt inte lånbar"); arkiverad försvinner ("inte längre lånbar").

Webhooks — händelser tillbaka till er

POST

/webhooks

{
  "url": "https://er-plattform.example.com/hooks/vaschego",
  "events": ["checkin", "checkout", "resource.updated", "resource.archived"]
}

events utelämnad = allt (["*"]). Max 3 endpoints per partner och organisation. Svar 201 innehåller secret (whsec_…) — visas exakt en gång, spara den. Endpoints ni skapar är era egna; organisationens övriga webhooks syns inte här.

GET

/webhooks

Lista era endpoints (utan secret).

DELETE

/webhooks/{id}

Ta bort en endpoint.

Event	När
`checkin`	någon lånade resursen
`checkout`	resursen lämnades tillbaka
`fault.reported`	en låntagare felanmälde
`resource.updated`	namn/beskrivning/paus ändrades från vaschego-sidan
`resource.archived`	resursen arkiverades från vaschego-sidan
`booking.created`	ett lån startade/förbokades (due_date-läget) — date + end_date är lånets intervall
`booking.released / booking.cancelled`	lånet återlämnades i förtid respektive togs bort
`slot.*`	passhändelser (ej relevanta för lån)

Så ser en leverans ut

POST <er endpoint-URL>
X-Vaschego-Event:     checkin
X-Vaschego-Delivery:  <uuid>
X-Vaschego-Timestamp: <unix-sekunder>
X-Vaschego-Signature: sha256=<hex>

{
  "event": "checkin",
  "org_id": "…",
  "resource_id": "…",
  "resource_slug": "ab12cd",
  "occurred_at": "2026-08-19T09:12:33Z",
  "apartment": "Anna E, plan 3",
  "partner": { "provider": "er-plattform", "partner_item_id": "artikel-8f3a" }
}

partner-objektet finns på alla händelser för resurser ni provisionerat — korrelera på partner_item_id. apartment är låntagarens självangivna identitet (namn/avdelning — vaschego har inga slutanvändarkonton).

Verifiera signaturen

HMAC-SHA256 (Hash-based Message Authentication Code) av den råa request-bodyn med er endpoint-secret som nyckel:

signature = "sha256=" + hex(hmac_sha256(secret, raw_body))
if not constant_time_equals(signature, header["X-Vaschego-Signature"]): reject
if now() - header["X-Vaschego-Timestamp"] > 300: reject

Leveransgarantier

Svar 2xx räknas som levererat. Annars görs omförsök efter 1, 5, 30, 120 och 360 minuter; därefter markeras leveransen misslyckad och endpointen inaktiveras automatiskt (skapa den på nytt, eller be organisationens admin slå på den igen).

Frågor, önskemål eller något som skaver? Skriv till api@vaschego.se — vi bygger gärna ihop med er.