Finovia API

At a glance

What an integration does

1
Get a token
Client credentials. Valid for 15 minutes.
POST/v1/oauth/token
2
Submit an invoice
Answered with 202 and a submission. Received is not registered.
POST/v1/clients/{clientId}/invoices
3
Follow the submission
Poll the submission, read the event feed, or receive webhooks.
GET/v1/clients/{clientId}/invoice-submissions/{submissionId}GET/v1/eventsPOST/v1/webhooks
4
Read the invoice
Once registered: the invoice and its four statuses.
GET/v1/clients/{clientId}/invoices/{invoiceId}GET/v1/clients/{clientId}/invoices
5
Correct with a credit note
Sent is sent. A wrong invoice is credited, and a new one submitted.
POST/v1/clients/{clientId}/invoices

From submission to invoice

Every submitted invoice becomes a submission that moves through these states. Each move is an event.

received
Received, not checked.
event invoice_submission_received
rejected
Rejected at Finovia's boundary.
event invoice_submission_rejectedCorrect it and submit again.
validated
The form is checked and accepted.
registration_failed
Not registered.
event invoice_registration_failedCorrect it and submit again.
handed_over
Handed over to invoice processing, awaiting the answer.
event invoice_submission_handed_over
registration_failed
Not registered.
event invoice_registration_failedCorrect it and submit again.
registered
Registered.
event invoice_registeredFinal. The invoice exists.

After registration: four statuses, each on its own

payment_status: unpaid, partially_paid, paid or overpaid.
financing_status: not_requested, requested, financed or repurchased. Shows whether Finovia has purchased the invoice.
collection_status: none, reminder, debt_collection or legal.
operational_status: active, paused or blocked.

Each change is an invoice_status_observed event. A status Finovia does not know is shown as absent, never as a value.

Overview

With the Finovia API a company, or a business system acting on the company's behalf, submits its customer invoices to Finovia and follows what happens to them.

Status: draft. The contract is written but not built. Fields and responses may change until version 1.0.0 is published. After that, a change that breaks backwards compatibility becomes a new version in the path (/v2), and /v1 remains available until an announced end date.

Two kinds of callers, one API

A company that is a Finovia client reaches its own invoices.
A business system (partner) reaches only the clients that have approved it themselves, in Finovia's client portal. The client approves each business system once and can end the connection at any time.

The client is always given in the path: /v1/clients/{clientId}/.... A client the caller cannot reach returns 404, never 403, so that the response does not reveal that the client exists at Finovia. The connection to the client is checked before anything else in the request. 403 only means that the token lacks the scope for the operation. An ended connection applies from the next request: no more invoices, no more events in the feed and no more webhooks for that client.

Language

Error messages (message in FieldError and failure, and title and detail in errors) are written in Swedish or English. Choose with the Accept-Language header: sv or en. Without the header, or with any other language, they are in Swedish. The response states the language in Content-Language.

Build your logic on code, never on the message. Codes are the same in both languages and do not change; messages may be reworded.

Absence

When Finovia does not have a value, it is shown as absence with a reason (state: absent and reason), never as null, zero or an omitted field that could be read as something else.

Receiving is not registering

A submitted invoice is answered with 202 Accepted and a submission with its own id. The invoice is then checked and handed over to invoice processing. Follow the submission with GET .../invoice-submissions/{id}, with webhooks or with the event feed GET /v1/events.

received ─┬→ validated ─┬→ handed_over ─┬→ registered
          │             │               └→ registration_failed
          │             └→ registration_failed   (stopped before hand-over, e.g. no purchase agreement)
          └→ rejected   (field errors, or the invoice number is already in use)

202 means received. It never means that Finovia has purchased the invoice. Whether the invoice is purchased depends on the client's agreement with Finovia and shows in the invoice's financing_status.

Sent is sent

A registered invoice cannot be changed or deleted. A wrong invoice is corrected with a credit note and a new invoice.

An invoice that was rejected or whose submission ended in registration_failed was never registered. Correct it and submit it again, with the same invoice number and a new Idempotency-Key.

Amounts

Amounts are always strings with a dot as decimal separator, for example "12500.00", never JSON numbers. The currency is always given, as ISO 4217. An invoice without a currency is rejected; it never becomes SEK. An amount has at most as many decimals as its currency (two for SEK and EUR). Every amount on an invoice has the invoice's currency and the basis its field states; otherwise the invoice is rejected.

On a credit note, unit_price, face_amount, tax_reduction and amount_due are negative, and is_credit_note is true.

Finovia does not check the sum of the lines against face_amount before hand-over; VAT and rounding per line are calculated by invoice processing. After registration the registered amount is reconciled with amount_due to the öre. If they differ, Finovia's staff sees it, and the submission ends in registration_failed with the code amount_mismatch.

Unknown is never a status

When Finovia does not know a status, it is shown as absence (state: absent) with a reason. It never means unpaid, approved or anything else. New values may be added to code lists without a new version; a client must tolerate a value it does not recognise.

Sandbox and production

The sandbox accepts invoices freely and never sends anything to a real recipient. Production is closed until Finovia opens it.

Getting started in the sandbox

1. Confirm the sandbox terms below to Finovia. Finovia hands out no credentials before that. 2. Get your credentials from Finovia: the sandbox address, a client id, a secret and the id of a fictitious test client that your key reaches. The secret is shown once; Finovia only keeps its hash. 3. Get a token: POST /v1/oauth/token with grant_type=client_credentials, client_id and client_secret, form-encoded or as HTTP Basic. The token is valid for 15 minutes. 4. Submit an invoice to POST /v1/clients/{clientId}/invoices with an Idempotency-Key, and follow it with GET .../invoice-submissions/{id} or GET /v1/events.

What is different in the sandbox:

Responses are simulated. Every response carries the header Finovia-Sandbox: simulated. A valid invoice is registered after a few seconds; nothing reaches invoice processing, and the statuses are those of a new invoice.
Private persons only with Skatteverket's test numbers. A recipient that is a private person must be identified with one of Skatteverket's published test personal identity numbers, with twelve digits (YYYYMMDDNNNN). Any other personal identity number is rejected with sandbox_requires_test_personnummer, and so is a personal identity number in any other field.
Nothing is kept. Submissions are held in memory and deleted after seven days, or when the sandbox restarts. A PDF is accepted but never stored.
Limits: at most 10 MB per request and 1,000 submissions per API client.
Webhooks are not available yet and return 501. Use GET /v1/events.
This documentation is open at /docs on the sandbox address, and the contract itself at /openapi.yaml, without a token. Generate a client from /openapi.yaml if you like; it is the source.

Sandbox terms

These terms apply to everyone who uses the sandbox. They are also part of the partnership agreement with Finovia.

1. Only fictitious data. Never real personal data or real customers' data, and never a copy of production data. This includes names, addresses and free text about private persons. 2. Personal identity numbers only from Skatteverket's list of test numbers, and only as the recipient's number. 3. The sandbox is not production. Nothing is registered, and everything is deleted after seven days. 4. Keep the secret secret. Report a leak to Finovia immediately. Finovia may revoke the key at any time. 5. If real data is sent by mistake, tell Finovia, and Finovia deletes it. 6. No security testing or load testing without Finovia's written consent. 7. Finovia logs your calls: when, which operation, the result and the error code. Never the content. 8. Finovia may suspend your key at any time, and does so on suspicion of a breach of these terms. 9. The sandbox is provided as is. No availability is guaranteed, and it may change or be emptied without notice. 10. Keep it confidential. What you learn from Finovia that is not public, and your key, is not passed on.

Servers

https://sandbox.api.finovia.seSandbox. The address is preliminary.

https://api.finovia.seProduction. Closed for now. The address is preliminary.

Authentication

A client id and secret give a short-lived token (OAuth 2.0 client credentials). The secret is shown once when the API client is created and can be rotated with overlap, so that rotation causes no outage. A token grants nothing by itself: every request is checked against the API client's scopes and against its connection to the client.

Token endpoint: POST /v1/oauth/token

Scope	Allows
`invoices:write`	Submit invoices.
`invoices:read`	Read invoices and submissions.
`events:read`	Fetch events.
`webhooks:manage`	Add and remove webhooks.

Invoices

Submit and read invoices.

GET /v1/clients/{clientId}/invoices

List the client's invoices

Scope invoices:read

All the client's invoices at Finovia, however they arrived. A business system sees all invoices of a client that has approved it, including those it did not submit itself.

Parameters

Name	In	Description
`Accept-Language`	header string	The language of error messages, `sv` or `en`. Swedish when omitted. Examples `sv` `en`
`clientId`required	path string, uuid	The Finovia client. A company calling for itself gives its own id.
`cursor`	query string	The cursor from the previous page.
`limit`	query integer	At most this many items. Default `50` Range 1–100
`invoice_number`	query string	Only the invoice with this invoice number.

Responses

200	A page of invoices.	InvoicePage
401	No valid token.	Problem
403	The token lacks the scope for the operation.	Problem
404	Does not exist, or the caller cannot reach it. The two are not distinguished.	Problem

POST /v1/clients/{clientId}/invoices

Submit an invoice

Scope invoices:write

Receives an invoice or credit note. The response is a submission in state received. Checking and hand-over happen afterwards.

Idempotency-Key is required and applies per API client and client. The same key with the same content returns the same response again, without a new submission, for as long as the submission exists: the submission as it was when it was received. Read its current state with GET .../invoice-submissions/{id}. The same content means the same JSON after parsing, regardless of field order and whitespace. The same key with different content returns 409 with the code idempotency_key_reused. A request with the same key while the first is still being processed returns 409 with the code request_in_progress and a Retry-After header.

An invoice number may be used once per client. If the client already has an invoice with the same number, in any currency, that is registered or has a submission in progress, the new submission is rejected with the code duplicate_invoice_number. A number whose earlier submissions were all rejected or registration_failed may be submitted again. An invoice that Finovia knows only from the client's accounting system, and that has never been submitted, is not a duplicate: the submission is linked to it.

An invoice with ROT, RUT or green technology requires the recipient to be a private person (se_personnummer), the details in tax_reduction_details, property for ROT, tax_reduction, and a cost type on every line. If anything is missing the invoice is rejected with field errors; it never goes through with the tax reduction removed. tax_reduction_details without any line with a tax reduction is also rejected.

Parameters

Name	In	Description
`Accept-Language`	header string	The language of error messages, `sv` or `en`. Swedish when omitted. Examples `sv` `en`
`clientId`required	path string, uuid	The Finovia client. A company calling for itself gives its own id.
`Idempotency-Key`required	header string	The caller's unique key for this submission. The same key is used when retrying.

Request body

InvoiceSubmissionRequest

Field	Type	Description
`invoice_number`required	string	The invoice number as a string, so that leading zeros are kept. Used once per client.
`issue_date`required	string, date
`due_date`required	string, date
`currency`required	CurrencyCode
`ocr_reference`	string	The OCR payment reference as a string.
`is_credit_note`	boolean	Default `false`
`credited_invoice`	CreditedInvoiceReference
`debtor`required	Debtor
`lines`required	array of InvoiceLineRequest
`tax_reduction_details`	TaxReductionDetails
`face_amount`required	FaceAmount
`tax_reduction`	TaxReductionAmount	Required when any line has `tax_reduction_type`, and must not be given otherwise.
`amount_due`required	AmountDue	The same as `face_amount` when the invoice has no tax reduction.
`document`	InvoiceDocument

Invoice to a company

{
  "invoice_number": "000123",
  "issue_date": "2026-11-02",
  "due_date": "2026-12-02",
  "currency": "SEK",
  "ocr_reference": "0001230",
  "debtor": {
    "identifier": {
      "scheme": "se_orgnr",
      "value": "556847-2210"
    },
    "name": "Kalle Anka AB",
    "address": {
      "street": "Paradisäppelvägen 111",
      "postal_code": "12345",
      "city": "Ankeborg",
      "country_code": "SE"
    },
    "client_reference": "KUND-88"
  },
  "lines": [
    {
      "text": "Konsulttjänst",
      "quantity": "1",
      "unit_price": "10000.00",
      "vat_rate": "25"
    }
  ],
  "face_amount": {
    "amount": "12500.00",
    "currency": "SEK",
    "basis": "face_amount"
  },
  "amount_due": {
    "amount": "12500.00",
    "currency": "SEK",
    "basis": "amount_due"
  }
}

ROT invoice to a private person

{
  "invoice_number": "000124",
  "issue_date": "2026-11-02",
  "due_date": "2026-12-02",
  "currency": "SEK",
  "debtor": {
    "identifier": {
      "scheme": "se_personnummer",
      "value": "<personnummer>"
    },
    "name": "Kajsa Anka",
    "address": {
      "street": "Paradisäppelvägen 113",
      "postal_code": "12345",
      "city": "Ankeborg",
      "country_code": "SE"
    }
  },
  "lines": [
    {
      "text": "Installation av värmepump",
      "quantity": "10",
      "unit_price": "500.00",
      "vat_rate": "25",
      "cost_type": "labour",
      "tax_reduction_type": "rot"
    },
    {
      "text": "Värmepump",
      "quantity": "1",
      "unit_price": "4000.00",
      "vat_rate": "25",
      "cost_type": "material"
    }
  ],
  "tax_reduction_details": {
    "work_description": "Installation av värmepump",
    "work_address": {
      "street": "Paradisäppelvägen 113",
      "postal_code": "12345",
      "city": "Ankeborg",
      "country_code": "SE"
    },
    "work_period": {
      "from": "2026-10-20",
      "to": "2026-10-24"
    },
    "property": {
      "kind": "real_estate",
      "designation": "Ankeborg Paradiset 1:13"
    }
  },
  "face_amount": {
    "amount": "11250.00",
    "currency": "SEK",
    "basis": "face_amount"
  },
  "tax_reduction": {
    "amount": "1875.00",
    "currency": "SEK",
    "basis": "tax_reduction"
  },
  "amount_due": {
    "amount": "9375.00",
    "currency": "SEK",
    "basis": "amount_due"
  }
}

Responses

202	Received. Not checked, not registered and not purchased.	InvoiceSubmission
400	Form errors. Nothing is stored.	Problem
401	No valid token.	Problem
403	The token lacks the scope for the operation.	Problem
404	Does not exist, or the caller cannot reach it. The two are not distinguished.	Problem
409	The key is already used with different content (`idempotency_key_reused`), or a request with the same key is being processed right now (`request_in_progress`, with `Retry-After`).	Problem

GET /v1/clients/{clientId}/invoices/{invoiceId}

Read an invoice and its statuses

Scope invoices:read

The invoice and its four statuses: payment, financing, collection and operational. Each status carries observed_at, when Finovia last saw it. The status is Finovia's observation and may lag behind.

Parameters

Name	In	Description
`Accept-Language`	header string	The language of error messages, `sv` or `en`. Swedish when omitted. Examples `sv` `en`
`clientId`required	path string, uuid	The Finovia client. A company calling for itself gives its own id.
`invoiceId`required	path string, uuid

Responses

200	The invoice.	Invoice
401	No valid token.	Problem
403	The token lacks the scope for the operation.	Problem
404	Does not exist, or the caller cannot reach it. The two are not distinguished.	Problem

GET /v1/clients/{clientId}/invoice-submissions/{submissionId}

Read a submission

Scope invoices:read

The state of the submission, and field errors or the reason if it was rejected or could not be registered.

Parameters

Name	In	Description
`Accept-Language`	header string	The language of error messages, `sv` or `en`. Swedish when omitted. Examples `sv` `en`
`clientId`required	path string, uuid	The Finovia client. A company calling for itself gives its own id.
`submissionId`required	path string, uuid

Responses

200	The submission.	InvoiceSubmission
401	No valid token.	Problem
403	The token lacks the scope for the operation.	Problem
404	Does not exist, or the caller cannot reach it. The two are not distinguished.	Problem

Events

Everything that happens to the caller's invoices, in order, to fetch afterwards.

GET /v1/events

Fetch events from a cursor

Scope events:read

The same events that webhooks send, in the order Finovia recorded them. Start without after, then continue from next_cursor. A business system only gets events for the clients that have approved it. A lost webhook never becomes lost knowledge.

Parameters

Name	In	Description
`Accept-Language`	header string	The language of error messages, `sv` or `en`. Swedish when omitted. Examples `sv` `en`
`after`	query string	The cursor from the previous response. Omitted means from the beginning.
`limit`	query integer	At most this many items. Default `50` Range 1–100
`client_id`	query string, uuid	Only events for this client. A client the caller cannot reach returns 404.

Responses

200	A page of events.	EventPage
401	No valid token.	Problem
403	The token lacks the scope for the operation.	Problem
404	Does not exist, or the caller cannot reach it. The two are not distinguished.	Problem

Webhooks

Have the events sent to an address of your own.

GET /v1/webhooks

List the caller's webhooks

Scope webhooks:manage

Parameters

Name	In	Description
`Accept-Language`	header string	The language of error messages, `sv` or `en`. Swedish when omitted. Examples `sv` `en`

Responses

200	Webhooks.	object
401	No valid token.	Problem
403	The token lacks the scope for the operation.	Problem

POST /v1/webhooks

Add a webhook

Scope webhooks:manage

Events are sent with POST to the address, as JSON according to Event. A business system receives events only for the clients that have approved it. The signing secret is shown only in this response.

Parameters

Name	In	Description
`Accept-Language`	header string	The language of error messages, `sv` or `en`. Swedish when omitted. Examples `sv` `en`

Request body

object

Field	Type	Description
`url`required	string, uri	The address, always https. Pattern `^https://`
`event_types`	array of EventType	Which events. Omitted means all.

Responses

201	Created.	Webhook + object
400	Form errors. Nothing is stored.	Problem
401	No valid token.	Problem
403	The token lacks the scope for the operation.	Problem

DELETE /v1/webhooks/{webhookId}

Remove a webhook

Scope webhooks:manage

No more events are sent to the address. The events can still be fetched with GET /v1/events.

Parameters

Name	In	Description
`Accept-Language`	header string	The language of error messages, `sv` or `en`. Swedish when omitted. Examples `sv` `en`
`webhookId`required	path string, uuid

Responses

204	Removed.
401	No valid token.	Problem
403	The token lacks the scope for the operation.	Problem
404	Does not exist, or the caller cannot reach it. The two are not distinguished.	Problem

Webhook delivery

An event, sent to the caller's webhook

Every delivery carries the header Finovia-Signature: t=<unix time>,v1=<hex>, where v1 is HMAC-SHA256 with the webhook's secret over "{t}.{raw body}". Reject a delivery whose t is more than five minutes from your clock.

An event may be delivered more than once, and order is not guaranteed. Use the event's id to recognise a repeat, and sequence for order. Respond with 2xx once the event is stored; otherwise Finovia retries.

Body: Event

Schemas

`Decimal`

An exact decimal number as a string, with a dot as decimal separator and an optional minus sign.

string

Pattern ^-?\d{1,15}(\.\d{1,6})?$
Examples 12500.00 -800.00 25

`CurrencyCode`

ISO 4217, upper case.

string

Pattern ^[A-Z]{3}$
Examples SEK EUR

`Money`

An amount. Two amounts with different currency or basis are never added together.

Field Type Description

amountrequired Decimal

currencyrequired CurrencyCode

basisrequired

string

What the amount is.

face_amount: the invoice amount, including VAT, before tax reduction.
tax_reduction: the tax reduction for ROT, RUT or green technology.
amount_due: what the recipient is to pay, including VAT, after tax reduction.

Values face_amount tax_reduction amount_due

`FaceAmount`

The invoice amount including VAT, before tax reduction.

Field	Type	Description
`amount`required	Decimal
`currency`required	CurrencyCode
`basis`required	`face_amount`

`TaxReductionAmount`

The tax reduction. "0.00" when the invoice has none.

Field	Type	Description
`amount`required	Decimal
`currency`required	CurrencyCode
`basis`required	`tax_reduction`

`AmountDue`

What the recipient is to pay, including VAT, after tax reduction.

Field	Type	Description
`amount`required	Decimal
`currency`required	CurrencyCode
`basis`required	`amount_due`

`Address`

Field	Type	Description
`street`required	string
`street_2`	string
`postal_code`required	string
`city`required	string
`country_code`required	string	ISO 3166-1 alpha-2. Pattern `^[A-Z]{2}$`

`PartyIdentifier`

Field	Type	Description
`scheme`required	string	`se_orgnr`: Swedish organisation number. `se_personnummer`: Swedish personal identity number, for a private person or a sole trader. Values `se_orgnr` `se_personnummer`
`value`required	string	The number as a string. In responses a personal identity number is never shown, only the year of birth, for example `1945-••••`. This also applies to an organisation number that is in fact a personal identity number, such as a sole trader's: Finovia recognises it and treats it as a personal identity number, whatever `scheme` the caller gave.

`Debtor`

The recipient of the invoice. If Finovia already knows the recipient by the same identifier, that recipient is used. Otherwise it is created. Two recipients are never merged automatically.

Field	Type	Description
`identifier`required	PartyIdentifier
`name`required	string
`address`required	Address
`vat_number`	string	The recipient's VAT registration number. Required when a line has reverse charge for construction.
`email`	string, email	Information about the recipient. Does not control how the invoice is sent.
`client_reference`	string	The client's own customer number for the recipient.

`InvoiceLineRequest`

Field	Type	Description
`text`required	string
`quantity`required	Decimal
`unit`	string	For example st, tim, kg.
`unit_price`required	Decimal	Price per unit, excluding VAT, in the invoice currency. Negative on a credit note.
`vat_rate`required	Decimal	VAT rate in percent, for example `"25"`. `"0"` for reverse charge in construction.
`vat_treatment`	string	`standard`: ordinary VAT. `reverse_charge_construction`: reverse charge in the construction sector. Requires `vat_rate` `"0"` and the recipient's `vat_number`. Values `standard` `reverse_charge_construction` Default `standard`
`cost_type`	string	What the line is. Required on every line when the invoice has a tax reduction, so that the split shows on the invoice. Values `labour` `material` `other`
`tax_reduction_type`	string	The tax reduction that applies to the line. Omitted means none. `rot`: ROT work (repairs, conversion, extension). `rut`: RUT services (household services). `green_technology_solar`: green technology, solar cells. `green_technology_storage_charging`: green technology, battery storage or charging point. Values `rot` `rut` `green_technology_solar` `green_technology_storage_charging`

`PropertyReference`

Where the ROT work was done. Required for ROT.

One of — variant 1

Field	Type	Description
`kind`required	`real_estate`
`designation`required	string	Property designation (fastighetsbeteckning), for example Ankeborg Paradiset 1:13.

One of — variant 2

Field	Type	Description
`kind`required	`tenant_owned_apartment`
`housing_cooperative_orgnr`required	string	The housing cooperative's organisation number.
`apartment_number`required	string

`TaxReductionDetails`

Details that must appear on the invoice to the buyer for ROT, RUT or green technology. Required when any line has tax_reduction_type. The buyer's personal identity number is the recipient's identifier and is not given here again.

Field Type Description

work_descriptionrequired

string

What has been done.

work_addressrequired Address

work_periodrequired

object

When the work was done. from is on or before to.

Fields

Field	Type	Description
`from`required	string, date
`to`required	string, date

property

PropertyReference

Required when any line has tax_reduction_type rot.

`InvoiceDocument`

The client's own invoice as a PDF. Without it, Finovia builds the invoice from the data. For ROT, RUT or green technology the client is responsible for its own PDF showing the same details as tax_reduction_details.

Field	Type	Description
`content_type`required	`application/pdf`
`content`required	string, base64

`CreditedInvoiceReference`

The invoice being credited. Give Finovia's id or the invoice number.

One of — variant 1

Field	Type	Description
`invoice_id`required	string, uuid

One of — variant 2

Field	Type	Description
`invoice_number`required	string

`InvoiceSubmissionRequest`

An invoice to submit. Finovia checks that face_amount minus tax_reduction equals amount_due exactly, to the öre. If not, the invoice is rejected; Finovia never corrects an amount.

Field	Type	Description
`invoice_number`required	string	The invoice number as a string, so that leading zeros are kept. Used once per client.
`issue_date`required	string, date
`due_date`required	string, date
`currency`required	CurrencyCode
`ocr_reference`	string	The OCR payment reference as a string.
`is_credit_note`	boolean	Default `false`
`credited_invoice`	CreditedInvoiceReference
`debtor`required	Debtor
`lines`required	array of InvoiceLineRequest
`tax_reduction_details`	TaxReductionDetails
`face_amount`required	FaceAmount
`tax_reduction`	TaxReductionAmount	Required when any line has `tax_reduction_type`, and must not be given otherwise.
`amount_due`required	AmountDue	The same as `face_amount` when the invoice has no tax reduction.
`document`	InvoiceDocument

When is_credit_note is true, credited_invoice is required; otherwise it must not be given.

`FieldError`

Field	Type	Description
`path`required	string	JSON Pointer to the field, for example `/lines/0/vat_rate`.
`code`required	string	The error code. New codes may be added. Examples `required` `invalid_format` `invalid_value` `invalid_identifier` `unsupported_currency` `too_many_decimals` `currency_mismatch` `amounts_do_not_reconcile` `wrong_sign` `duplicate_invoice_number` `missing_tax_reduction` `missing_tax_reduction_details` `tax_reduction_without_reduction` `tax_reduction_details_without_reduction` `tax_reduction_requires_private_person` `missing_property` `missing_cost_type` `invalid_work_period` `reverse_charge_requires_zero_vat` `reverse_charge_requires_vat_number`
`message`required	string	A human-readable explanation

`Problem`

An error according to RFC 9457.

Field	Type	Description
`type`required	string, uri
`code`	string	A stable code for the error, for example `idempotency_key_reused` or `request_in_progress`. New codes may be added.
`title`required	string
`status`required	integer
`detail`	string
`errors`	array of FieldError

`SubmissionState`

received: received, not checked.
validated: the form is checked and accepted.
rejected: rejected at Finovia's boundary. See errors. May be corrected and submitted again.
handed_over: handed over to invoice processing, awaiting the answer.
registered: registered. The invoice is in invoice_id.
registration_failed: not registered. Either stopped before hand-over, for example because the client has no purchase agreement or no account in the invoice currency, or declined by invoice processing. See failure. May be corrected and submitted again.

string

Values received validated rejected handed_over registered registration_failed

`InvoiceSubmission`

Field Type Description

idrequired string, uuid

client_idrequired string, uuid

staterequired SubmissionState

received_atrequired string, date-time

state_changed_at string, date-time

invoice_id

string, uuid

Present when the invoice is registered.

errors

array of FieldError

Present when the submission is rejected.

failure

object

Present when the submission is registration_failed.

Fields

Field	Type	Description
`code`required	string	The reason. New codes may be added. Examples `no_purchase_agreement` `currency_not_supported` `declined` `amount_mismatch` `not_supported_yet`
`message`required	string	A human-readable explanation

`AbsenceReason`

Why a value is missing. The same reasons as in Finovia's data model. New reasons may be added.

string

Values not_fetched provider_absent provider_empty not_applicable parse_failed mapping_gap privacy_suppressed unknown

`ObservedStatus`

A status Finovia has seen, or absence with a reason. Absence is never a status.

One of — variant 1

Field	Type	Description
`state`required	`present`
`value`required	string
`observed_at`required	string, date-time	When Finovia last saw the status.

One of — variant 2

Field	Type	Description
`state`required	`absent`
`reason`required	AbsenceReason

`Invoice`

Field Type Description

idrequired string, uuid

client_idrequired string, uuid

invoice_numberrequired string

issue_daterequired string, date

due_daterequired string, date

currencyrequired CurrencyCode

ocr_reference string

is_credit_noterequired boolean

credited_invoice_id string, uuid

debtorrequired

object

The recipient, with the name the client itself gave. A name given by another client for the same recipient is never shown. A personal identity number is shown only with the year of birth.

Fields

Field	Type	Description
`identifier`required	PartyIdentifier
`name`required	string

face_amountrequired FaceAmount

tax_reductionrequired TaxReductionAmount

amount_duerequired AmountDue

statusrequired

object

The invoice's four statuses, each on its own. No status is derived from another.

Fields

Field	Type	Description
`payment_status`required	ObservedStatus	`unpaid`, `partially_paid`, `paid` or `overpaid`.
`financing_status`required	ObservedStatus	`not_requested`, `requested`, `financed` or `repurchased`. Shows whether Finovia has purchased the invoice.
`collection_status`required	ObservedStatus	`none`, `reminder`, `debt_collection` or `legal`.
`operational_status`required	ObservedStatus	`active`, `paused` or `blocked`.

`InvoicePage`

Field	Type	Description
`data`required	array of Invoice
`has_more`required	boolean	Whether there are more invoices after this page.
`next_cursor`required	string	The cursor for the next page. Only used when `has_more` is true.

`EventType`

New event types may be added.

string

Values invoice_submission_received invoice_submission_rejected invoice_submission_handed_over invoice_registered invoice_registration_failed invoice_status_observed

`Event`

Field Type Description

idrequired

string, uuid

The same id on every delivery of the same event.

sequencerequired

string

The order. Equal length for all events and increasing for each new one, so that it can be compared as a string.

typerequired EventType

occurred_atrequired string, date-time

client_idrequired string, uuid

datarequired

object

The submission or invoice the event concerns, as it was after the event.

Fields

Field	Type	Description
`submission`	InvoiceSubmission
`invoice`	Invoice

`EventPage`

Field	Type	Description
`data`required	array of Event
`next_cursor`required	string	The cursor to continue from. Always present, also when the page is empty.

`Webhook`

Field	Type	Description
`id`required	string, uuid
`url`required	string, uri
`event_types`required	array of EventType
`created_at`required	string, date-time

Generated from apps/api/openapi/v1.yaml. The contract is the source; this page never says anything else.

At a glance

What an integration does

Get a token

Submit an invoice

Follow the submission

Read the invoice

Correct with a credit note

From submission to invoice

After registration: four statuses, each on its own

Overview

Two kinds of callers, one API

Language

Absence

Receiving is not registering

Sent is sent

Amounts

Unknown is never a status

Sandbox and production

Getting started in the sandbox

Sandbox terms

Servers

Authentication

Invoices

List the client's invoices

Parameters

Responses

Submit an invoice

Parameters

Request body

Responses

Read an invoice and its statuses

Parameters

Responses

Read a submission

Parameters

Responses

Events

Fetch events from a cursor

Parameters

Responses

Webhooks

List the caller's webhooks

Parameters

Responses

Add a webhook

Parameters

Request body

Responses

Remove a webhook

Parameters

Responses

Webhook delivery

An event, sent to the caller's webhook

Schemas

Decimal

CurrencyCode

Money

FaceAmount

TaxReductionAmount

AmountDue

Address

PartyIdentifier

Debtor

InvoiceLineRequest

PropertyReference

TaxReductionDetails

InvoiceDocument

CreditedInvoiceReference

InvoiceSubmissionRequest

FieldError

Problem

SubmissionState

InvoiceSubmission

AbsenceReason

ObservedStatus

Invoice

InvoicePage

EventType

Event

EventPage

`Decimal`

`CurrencyCode`

`Money`

`FaceAmount`

`TaxReductionAmount`

`AmountDue`

`Address`

`PartyIdentifier`

`Debtor`

`InvoiceLineRequest`

`PropertyReference`

`TaxReductionDetails`

`InvoiceDocument`

`CreditedInvoiceReference`

`InvoiceSubmissionRequest`

`FieldError`

`Problem`

`SubmissionState`

`InvoiceSubmission`

`AbsenceReason`

`ObservedStatus`

`Invoice`

`InvoicePage`

`EventType`

`Event`

`EventPage`

`Webhook`