Fakturor

Fakturaresursen speglar Fortnox /3/invoices. Fakturan adresseras på sitt publika nummer (DocumentNumber), inte på ett internt id, och numret kan inte ändras. Det finns ingen DELETE – makulering sker via /cancel och kreditering via /credit.

Klirr bokför vid utfärdandet: när en faktura bokförs allokeras fakturanummer och OCR, verifikatet postas och status blir skickad – i ett och samma steg. Fortnox skiljer på att skapa, bokföra och skicka; i Klirr är /bookkeep och /externalprint därför samma sak.

Scope: invoice · Kräver AI Pro

EndpointsCopy Anchor Link

Bas-URL: https://app.klirr.ai/api/v1. Skrivningar kuverteras i Invoice. Åtgärdsendpointen tar ingen kropp.

Ett DocumentNumber som inte är ett positivt heltal ger 404.

ListparametrarCopy Anchor Link

Utöver paginering (page, limit, offset) och sortorder (asc/desc):

Fortnox-parametrarna yourordernumber och lastmodified stöds inte ännu och ger 400 i stället för ett ofiltrerat svar.

FiltervärdenCopy Anchor Link

FältCopy Anchor Link

Fullständig form (GET /3/invoices/{DocumentNumber}, och svaret på POST, PUT och åtgärderna som returnerar JSON).

Skrivskyddade fält som skickas in ignoreras (en klient som läser och skriver tillbaka en faktura orörd får alltså inget fel). Fält som Klirr inte modellerar sparas och returneras oförändrade.

FakturaraderCopy Anchor Link

Discount/DiscountType på rader, samt Freight och AdministrationFee på fakturan, stöds inte och ger 400 – lägg beloppet som en egen rad.

ListformCopy Anchor Link

GET /3/invoices returnerar en reducerad rad utan InvoiceRows: @url, Balance, Booked, Cancelled, CostCenter, Currency, CurrencyRate, CurrencyUnit, CustomerName, CustomerNumber, DocumentNumber, DueDate, ExternalInvoiceReference1, ExternalInvoiceReference2, FinalPayDate, InvoiceDate, InvoiceType, NoxFinans, OCR, Project, Sent, TermsOfPayment, Total, VoucherNumber, VoucherSeries, VoucherYear, WayOfDelivery. Belopp och nummer (Balance, Total, CurrencyRate, VoucherNumber m.fl.) är strängar i listformen.

LivscykelCopy Anchor Link

En bokförd faktura kan inte ändras med PUT (bokföringslagen 5 kap. 5 §) – svaret är 409 med hänvisning till /credit.

Skapa en fakturaCopy Anchor Link

POST skapar alltid ett obokfört utkast. Bokför det sedan med /bookkeep, /email eller /print. Anropet räknas mot planens fakturakvot (403 när den är slut).

curl -X POST https://app.klirr.ai/api/v1/3/invoices \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{"Invoice":{"CustomerNumber":"1001","TermsOfPayment":"30","InvoiceRows":[{"Description":"Konsulttimmar","DeliveredQuantity":"10","Price":950,"VAT":25}]}}'

Svar (201, förkortat):

{
  "Invoice": {
    "@url": "https://app.klirr.ai/api/v1/3/invoices/42",
    "DocumentNumber": "42",
    "CustomerNumber": "1001",
    "CustomerName": "Bergström Bygg AB",
    "InvoiceDate": "2026-10-18",
    "DueDate": "2026-11-17",
    "TermsOfPayment": "30",
    "Net": 9500,
    "TotalVAT": 2375,
    "Total": 11875,
    "Gross": 11875,
    "RoundOff": 0,
    "Balance": 11875,
    "TotalToPay": 11875,
    "Booked": false,
    "Sent": false,
    "Cancelled": false,
    "OCR": "",
    "Currency": "SEK",
    "CurrencyRate": 1,
    "CurrencyUnit": 1,
    "TaxReductionType": "none",
    "VATIncluded": false,
    "Credit": "false",
    "CreditInvoiceReference": "0",
    "VoucherNumber": 0,
    "VoucherSeries": "",
    "VoucherYear": 0,
    "InvoiceRows": [
      {
        "RowId": 0,
        "ArticleNumber": "",
        "Description": "Konsulttimmar",
        "DeliveredQuantity": "10",
        "Price": 950,
        "VAT": 25,
        "VATCode": "services_25",
        "AccountNumber": 3001,
        "Unit": "h",
        "Total": 11875,
        "PriceExcludingVAT": 950,
        "TotalExcludingVAT": 9500,
        "HouseWork": false,
        "HouseWorkType": "",
        "ContributionPercent": "0",
        "ContributionValue": "0"
      }
    ]
  }
}

Lista fakturorCopy Anchor Link

curl "https://app.klirr.ai/api/v1/3/invoices?filter=unpaid&fromdate=2026-01-01&sortby=invoicedate" \
  -H "Authorization: Bearer <access_token>"

{
  "Invoices": [
    {
      "@url": "https://app.klirr.ai/api/v1/3/invoices/42",
      "Balance": "11875",
      "Booked": true,
      "Cancelled": false,
      "CostCenter": "",
      "Currency": "SEK",
      "CurrencyRate": "1",
      "CurrencyUnit": "1",
      "CustomerName": "Bergström Bygg AB",
      "CustomerNumber": "1001",
      "DocumentNumber": "42",
      "DueDate": "2026-11-17",
      "ExternalInvoiceReference1": "",
      "ExternalInvoiceReference2": "",
      "FinalPayDate": "",
      "InvoiceDate": "2026-10-18",
      "InvoiceType": "INVOICE",
      "NoxFinans": false,
      "OCR": "4200007",
      "Project": "",
      "Sent": true,
      "TermsOfPayment": "30",
      "Total": "11875",
      "VoucherNumber": "17",
      "VoucherSeries": "B",
      "VoucherYear": "1",
      "WayOfDelivery": ""
    }
  ],
  "MetaInformation": { "@TotalResources": 1, "@TotalPages": 1, "@CurrentPage": 1 }
}

Uppdatera ett utkastCopy Anchor Link

PUT ändrar bara de huvudfält du skickar. Raderna följer Fortnox regel: utelämnas InvoiceRows behålls befintliga rader; skickas fältet ersätts alla rader. Ange { "RowId": n } för de rader som ska stå kvar oförändrade. Se Fortnox-kompatibilitet.

curl -X PUT https://app.klirr.ai/api/v1/3/invoices/42 \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{"Invoice":{"Comments":"Avser oktober","InvoiceRows":[{"RowId":0},{"Description":"Resekostnad","DeliveredQuantity":"1","Price":400,"VAT":25}]}}'

ÅtgärderCopy Anchor Link

Alla åtgärder adresserar fakturan på DocumentNumber och tar ingen kropp. De som svarar med JSON returnerar {"Invoice": {...}} i fullständig form, läst om efter åtgärden.

bookkeepCopy Anchor Link

PUT /3/invoices/{DocumentNumber}/bookkeep utfärdar ett utkast: fakturanummer och OCR allokeras, verifikatet bokförs och status blir skickad. Ingenting mailas. En redan bokförd faktura ger 200 med resursen (idempotent), även vid samtidiga anrop.

curl -X PUT https://app.klirr.ai/api/v1/3/invoices/42/bookkeep \
  -H "Authorization: Bearer <access_token>"

externalprintCopy Anchor Link

PUT /3/invoices/{DocumentNumber}/externalprint – för när du levererar fakturan i ditt eget system. I Klirr gör den exakt samma sak som /bookkeep.

emailCopy Anchor Link

GET /3/invoices/{DocumentNumber}/email mailar fakturan till kundens e-postadress. Observera att det är en GET med sidoeffekt, precis som hos Fortnox.

• Är fakturan ett utkast utfärdas och bokförs den först, och mailas i samma anrop.
• Är den redan bokförd skickas bara mejlet igen – inget nytt nummer eller verifikat.
• Saknar kunden e-postadress svarar API:t 400.
• Misslyckas utskicket av en redan bokförd faktura svarar API:t 502. Fakturan är oförändrad och anropet kan göras om.

printCopy Anchor Link

GET /3/invoices/{DocumentNumber}/print returnerar fakturan som PDF (Content-Type: application/pdf, Content-Disposition: inline; filename="faktura-<nummer>.pdf"). Ett utkast utfärdas och bokförs först – utskrift räknas som leverans. Klirr mailar ingenting. Personnummer maskeras i PDF:en. En faktura utan rader ger 400.

curl https://app.klirr.ai/api/v1/3/invoices/42/print \
  -H "Authorization: Bearer <access_token>" \
  -o faktura-42.pdf

previewCopy Anchor Link

GET /3/invoices/{DocumentNumber}/preview returnerar en PDF utan sidoeffekter – fakturan utfärdas inte och ändras inte. Fungerar på utkast, som då märks UTKAST. Filnamnet är forhandsgranskning-<nummer>.pdf, svaret har Cache-Control: no-store och personnummer maskeras. En faktura utan rader ger 400.

cancelCopy Anchor Link

PUT /3/invoices/{DocumentNumber}/cancel makulerar ett utkast. Utkastet raderas, och svaret är fakturan som den såg ut före raderingen med Cancelled: true. Efteråt ger GET på numret 404.

En bokförd faktura kan inte makuleras – svaret är 409 med hänvisning till /credit.

creditCopy Anchor Link

PUT /3/invoices/{DocumentNumber}/credit skapar en kreditfaktura för hela den bokförda fakturan, rad för rad, daterad idag. Delkreditering stöds inte via den här endpointen.

Avvikelse från Fortnox: kreditfakturan får en egen nummerserie i Klirr och är inte adresserbar som faktura. Svaret är i stället den ursprungliga fakturan, nu med Cancelled: true och Balance nollat.

• Ett utkast kan inte krediteras: 400 (makulera det med /cancel).
• En redan helt krediterad faktura: 409.

FelCopy Anchor Link

Allmänna fel (401, 403, 429) beskrivs under Felkoder.