För plattformar: skapa kunder automatiskt

För er som driver en plattform med egna handlare – kassasystem, butiksplattformar, kedjor eller redovisningsbyråer. Med en partnernyckel skapar och sköter ni era kunders konton hos oss helt automatiskt.

Bas: https://dokumentadress.se/api/public/v1/partner Autentisering: Authorization: Bearer ds_partner_…

Grundregler

• En handlare = en egen organisation hos oss. En butik = en inkorg med egen tenant_ref. Handlare kan aldrig se varandras data.
• Partnernyckeln finns bara på er server. Den kan skapa och sköta era kunder, men aldrig läsa dokument, personal eller filer – de anropen nekas med 403.
• Organisationer som inte tillhör er svarar 404, även om de finns.
• Alla skrivande anrop kräver huvudet Idempotency-Key och är dessutom upprepningssäkra på ert eget external_id.
• Varje anrop loggas med partner, organisation och åtgärd.

1. Skapa handlare

POST /orgs

{ "external_id": "ert-handlar-id", "name": "Handlaren AB",
  "org_number": "556000-0000", "webhook_url": "https://er-plattform.se/hook" }

Svar 201 med org_id, api_key (ds_live_…) och webhook_secret. Nyckel och hemlighet visas bara denna gång – spara dem i ert valv under handlarens namn. Samma external_id igen ger 200 med samma org_id, utan ny nyckel. Mottagaren prenumererar direkt på dokument- och tidshändelser.

2. Kontrollera inkorgsnamn

GET /addresses/available?local_part=automataskeby

Svar { "available": true } eller { "available": false, "reason": "taken" }. Orsaker: invalid, blocked, taken, retired. Regler: a–z, 0–9 och bindestreck, 3–40 tecken.

3. Skapa butik

POST /orgs/{org_id}/stores

{ "external_id": "ert-butiks-id", "label": "Askeby",
  "tenant_ref": "sm-3f9a2c", "local_part": "automataskeby",
  "human_inbox": "butik@automataskeby.se" }

• local_part väljs av kunden. Upptaget namn ger 409 – vi byter aldrig namn i smyg.
• tenant_ref sätter ni. Den är unik över hela plattformen och återanvänds aldrig.
• human_inbox är obligatorisk: butikens egen e-post dit post som inte kan tolkas skickas vidare. Den får inte ligga på dokumentadress.se.

Butiken räknas som klar först när ett testdokument gått hela vägen till rätt butik.

4. Sköta kunden

Överlåtelse av en butik. Adressen följer alltid med till köparen. Om parterna kommit överens kan mer följa med, valbart var för sig i include:

• documents – butikens alla dokument, filer, tolkningar och historik flyttas. Gamla granskningslänkar spärras.
• staff – butikens anställda med scheman, tid och utlägg flyttas. Deras inloggningar spärras och de loggar in på nytt hos köparen.
• supplier_profiles – säljarens leverantörsinlärning kopieras. Säljaren behåller sin.

Utan include stannar all historik hos säljaren. Allt sker i ett steg: krockar något hos köparen (t.ex. samma anställningsnummer) flyttas ingenting och ni får 409 transfer_conflict. Svaret visar hur mycket som flyttades.

Hela verksamheten säljs (samma kund, ny ägare): handover byter namn och organisationsnummer. Adresser, dokument, personal och inlärning ligger kvar, men alla nycklar och mottagarhemligheter byts direkt, utan övergångstid, så att tidigare ägare tappar åtkomst. Dessutom:

• Säljarens inloggningar tas bort, utom de e-postadresser ni anger i keep_member_emails. new_owner_email bjuds in som ägare.
• Kopplingen till säljarens ekonomisystem kopplas bort, om inte keep_erp: true (bara när parterna uttryckligen kommit överens).
• Säljarens abonnemang hos oss avslutas. Nivån ligger kvar en kort övergångstid.

Svaret innehåller den nya nyckeln och hemligheterna – lämna dem till den nya ägaren. En butik kan inte överlåtas till en köpare vars nivå saknar plats: 409 plan_limit. Låt därför köparen starta eller uppgradera sitt abonnemang innan överlåtelsen.

Abonnemang via er. Kunder ni skapar betalar inte hos oss – nivån ingår i er egen avgift. Ange plan (free, start, business) när kunden skapas, annars används er standardnivå, och byt med POST /orgs/{org_id}/plan. Kunden kan inte själv byta nivå hos oss. En nivå med för få butiker nekas med 409 plan_limit, både när butiker skapas och när nivån sänks. Uppgradera därför innan ni lägger till eller tar över en butik.

5. Byta nyckel och hemlighet – bygg det i ert gränssnitt

DokumentAdress har inget partnergränssnitt. Ni bygger knapparna i er egen admin, och ert system anropar oss. Båda bytena har 24 timmars överlapp så inget avbrott uppstår.

Kundens API-nyckel (ds_live_…)

1. Er knapp "Byt nyckel" anropar POST /orgs/{org_id}/keys/rotate med er partnernyckel och en unik Idempotency-Key.
2. Svaret (201) innehåller api_key och previous_valid_until. Nyckeln visas bara i detta svar – spara den direkt i ert hemlighetsförråd.
3. Byt nyckeln i den tjänst som anropar oss. Den gamla fungerar tills previous_valid_until, sedan ger den 401.

Mottagarhemligheten (signering av våra utskick)

1. Er knapp "Byt hemlighet" anropar POST /orgs/{org_id}/webhook/rotate.
2. Svaret innehåller webhooks[] med url, webhook_secret, secret_version samt previous_valid_until.
3. Er mottagare ska under övergången godta signatur med både gamla och nya hemligheten. Vi skickar en signatur per aktiv version i X-Dokumentadress-Signature – godkänn om någon av dem stämmer.
4. Efter previous_valid_until signerar vi bara med den nya.

Samma Idempotency-Key inom 24 timmar ger exakt samma svar (huvudet Idempotent-Replayed: true) utan ett nytt byte – skicka en ny nyckel per avsiktligt byte. Samma nyckel med annat innehåll ger 422 idempotency_key_reused. Vid misstänkt läcka kan DokumentAdress också byta hemligheten åt er – då får ni den nya säkert från oss.

Felkoder

400 idempotency_key_required / invalid_json · 401 unauthorized · 403 insufficient_scope · 404 not_found · 409 address_taken / tenant_ref_taken / transfer_conflict / plan_limit / idempotency_in_progress · 413 payload_too_large · 422 validation_failed / address_invalid / idempotency_key_reused · 429 för många anrop (120/min per IP, 600/min per nyckel).

Svara 2xx på alla händelsetyper, även dem ni inte använder – annars görs nya försök.