DokumentAdress
← Alla guider

Skicka in dokument

Uppladdning i tre steg, metadata, dubblettskydd med checksumma och idempotens, samt hur ni läser tillbaka tolkat innehåll.

Utvecklare · cirka 6 minuters läsning

Så skickar ert system in dokument till tolkning. Allt är JSON — själva filen laddas upp separat mot en signerad länk.

Bas: https://<er-instans>/api/public/v1 Autentisering: Authorization: Bearer ds_live_…, scope documents:write.

Tre steg — hoppa inte över något

Det vanligaste felet är att skicka filen som multipart/form-data. Det fungerar inte. Så här går det till:

1. Begär en uppladdningslänk

POST /uploads

{
  "filename": "faktura-8812.pdf",
  "mime_type": "application/pdf",
  "byte_size": 184320,
  "checksum_sha256": "a3f1…"
}

Svar 201 med document_id, storage_key och upload_url.

2. Ladda upp filen

PUT <upload_url> med filens råa bytes och rätt Content-Type. Ingen formulärkodning, inga fältnamn, ingen nyckel i headern — länken är redan signerad och kortlivad.

3. Bekräfta

POST /uploads

{ "document_id": "…", "confirm": true }

Utan bekräftelsen tolkas dokumentet aldrig. Det blir liggande som påbörjat och ni undrar var det tog vägen.

Skapa dokumentet med metadata

POST /documents — kräver huvudet Idempotency-Key (valfri sträng ni hittar på, unik per dokument). Skickas samma nyckel igen får ni tillbaka samma dokument i stället för en dubblett.

{
  "document_type": "supplier_invoice",
  "tenant_ref": "nordbutik-linkoping",
  "external_reference": "ert-id-8812",
  "sender_name": "Leverantör AB",
  "attachments": [{ "document_id": "…" }]
}

checksum_sha256 ger dubblettskydd gratis: skickas samma fil två gånger svarar vi duplicate: true — det är ett lyckat svar, inte ett fel.

Läsa tillbaka

  • GET /documents?status=&document_type=&limit= — lista
  • GET /documents/{id} — ett dokument med tolkat innehåll
  • POST /documents/{id} med { "action": "retry" } eller { "action": "verify" }

Tolkat innehåll levereras med belopp som tal, aldrig strängar. Saknade värden är null, aldrig tom sträng.

Statuskedja

received → parsing → parsed eller needs_review → verified

needs_review betyder att något fält var osäkert. Dokumentet är fullt läsbart, men en människa bör titta på det innan det bokförs.

Checklista

  1. JSON överallt — PUT med rå fil endast mot den signerade länken.
  2. Alltid checksum_sha256.
  3. Alltid Idempotency-Key på POST /documents.
  4. Alltid tenant_ref så dokumentet hamnar på rätt enhet.
  5. Glöm aldrig bekräftelsesteget.
  6. Behandla duplicate: true som lyckat.
  7. Läs error.code, inte texten.

Fortsätt läsa