E-Invoicing

Endpointhttps://api.kontier.eu/v1

E-invoice artifacts (EN 16931 / XRechnung / Peppol): generation, validation findings, and document downloads.

Count e-invoice documents per invoice (batch)

GET

https://api.kontier.eu/v1

/e-invoicing/document-counts

Returns a flat {invoice_id: count} map so the invoice list can render a per-row "has e-invoice document" badge in one extra round-trip rather than N. Up to 200 ids per call.

Count e-invoice documents per invoice (batch) › query Parameters

invoice_ids

string

Comma-separated invoice UUIDs (max 200)

Count e-invoice documents per invoice (batch) › Headers

X-Workspace-Id

string

Selects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.

Workspace UUID or slug.

Count e-invoice documents per invoice (batch) › Responses

object · required

List e-invoice documents

GET

https://api.kontier.eu/v1

/e-invoicing/documents

Every artifact ever rendered for the org, most recent first — the single canonical home for e-invoice documents. Filter to one parent with ?invoice_id= or ?credit_note_id= (the per-parent list the invoice/credit-note detail pages use); omit both for the org-wide, cursor-paginated feed that powers the global "E-Invoice Documents" page.

List e-invoice documents › query Parameters

invoice_id

string · uuid

Scope to one invoice's documents (canonical replacement for the retired /e-invoicing/invoices/{id}/documents nesting)

credit_note_id

string · uuid

Scope to one credit note's documents (canonical replacement for the retired /e-invoicing/credit-notes/{id}/documents nesting)

profile

string

Exact profile ID match

quarantined_only

string

Return only quarantined docs (true/1)

limit

integer · min: 1

Page size. Values above the server-side cap are clamped (standard default 50, cap 200; a few document-heavy lists use larger windows). Invalid values fall back to the default.

Example: 50

cursor

string

Opaque continuation token from the previous response's pagination.cursor. Omit for the first page. Cursors are stateless and do not expire, but are only valid for the list and filters that produced them.

sort

string

Ordering of the org-wide feed: created_at (default, descending), invoice_id, profile, syntax, jurisdiction or status, each with an optional :asc / :desc suffix. invoice_id orders by the document's anchor, falling back to credit_note_id; status orders by clean/quarantined, newest first within each group. A cursor is bound to the ordering that minted it, so changing sort requires starting a fresh walk.

List e-invoice documents › Headers

X-Workspace-Id

string

Workspace UUID or slug.

List e-invoice documents › Responses

array | null · required

object · required

GET/e-invoicing/documents

curl --request GET \
  --url https://api.kontier.eu/v1/e-invoicing/documents

shell

Example Responses

{
  "data": [
    {
      "byte_size": 0,
      "content_hash": "content_hash",
      "content_type": "content_type",
      "created_at": "2024-08-25T15:00:00Z",
      "credit_note_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
      "credit_note_number": "credit_note_number",
      "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
      "invoice_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
      "invoice_number": "invoice_number",
      "jurisdiction": "jurisdiction",
      "profile": "profile",
      "profile_source": "profile_source",
      "profile_source_detail": "profile_source_detail",
      "quarantine_reason": "quarantine_reason",
      "syntax": "syntax"
    }
  ],
  "pagination": {
    "counts": {
      "key": {
        "key": 0
      }
    },
    "cursor": "cursor",
    "has_more": true,
    "total_count": 0
  }
}

json

application/json

Generate an e-invoice document for an invoice

POST

https://api.kontier.eu/v1

/e-invoicing/documents

Renders and stores a new e-invoice artifact for the invoice or credit note named in the body. profile is OPTIONAL: omit it and the format is resolved from the customer's einvoice_profile, then the country rules, then the organization's default_einvoice_profile - the same chain the autogen worker uses, so the two produce the same document. Supply it only to override that decision for this one document. 409 when a stored choice names a format this deployment does not produce (naming the customer or rule at fault); 422 when nothing resolves at all.

Generate an e-invoice document for an invoice › Headers

Idempotency-Key

string · required

Unique key that makes this POST safe to retry: repeats with the same key replay the first response instead of re-executing. Replays are scoped to the retrying principal (same API key / user) and kept for 24 hours. Required on every POST.

Client-generated idempotency key (e.g. a UUID).

X-Workspace-Id

string

Workspace UUID or slug.

Generate an e-invoice document for an invoice › Request Body

credit_note_id

string · uuid

Credit note to generate the e-invoice for; set exactly one of invoice_id or credit_note_id.

Example: 0f8fad5b-d9cb-469f-a165-70867728950e

invoice_id

string · uuid

Invoice to generate the e-invoice for; set exactly one of invoice_id or credit_note_id.

Example: 0f8fad5b-d9cb-469f-a165-70867728950e

jurisdiction

string · maxLength: 100

Optional jurisdiction hint (e.g. DE) recorded on the document and used to pick the archival retention policy. It does NOT select the format - that is what the profile rules do.

profile

string · maxLength: 100

Target e-invoice profile (e.g. XRECHNUNG_3_0_UBL). OMIT IT to resolve the format from the customer's preference, then the country rules, then the organization default; supply it only to override that decision for this one document. See GET /v1/e-invoicing/profiles for the accepted values.

reissue_reason

string · maxLength: 500

Short operator-facing note recorded on the superseded submission.

supersedes_submission_id

string · uuid

The refused submission this document replaces. Set it when re-issuing after a buyer refusal; the link is refused unless that submission is REFUSED_BY_BUYER and not already superseded.

Example: 0f8fad5b-d9cb-469f-a165-70867728950e

Generate an e-invoice document for an invoice › Responses

Created

object · required

POST/e-invoicing/documents

curl --request POST \
  --url https://api.kontier.eu/v1/e-invoicing/documents \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <string>' \
  --data '
{
  "credit_note_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
  "invoice_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
  "jurisdiction": "jurisdiction",
  "profile": "profile",
  "reissue_reason": "reissue_reason",
  "supersedes_submission_id": "0f8fad5b-d9cb-469f-a165-70867728950e"
}
'

shell

Example Request Body

{
  "credit_note_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
  "invoice_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
  "jurisdiction": "jurisdiction",
  "profile": "profile",
  "reissue_reason": "reissue_reason",
  "supersedes_submission_id": "0f8fad5b-d9cb-469f-a165-70867728950e"
}

json

Example Responses

{
  "data": {
    "byte_size": 0,
    "content_hash": "content_hash",
    "created_at": "2024-08-25T15:00:00Z",
    "document_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "findings": [
      {
        "message": "message",
        "rule_id": "rule_id",
        "severity": "severity",
        "xpath": "xpath"
      }
    ],
    "profile": "profile",
    "quarantined": true,
    "storage_bucket": "storage_bucket",
    "storage_key": "storage_key",
    "syntax": "syntax"
  }
}

json

application/json

Get an e-invoice document's metadata

GET

https://api.kontier.eu/v1

/e-invoicing/documents/{id}

Returns the document's metadata row (parent invoice or credit note, profile, syntax, jurisdiction, content hash, byte size, quarantine reason) without the artifact bytes — use /e-invoicing/documents/{id}/raw for the payload.

Get an e-invoice document's metadata › path Parameters

id

string · uuid · required

Document UUID

Get an e-invoice document's metadata › Headers

X-Workspace-Id

string

Workspace UUID or slug.

Get an e-invoice document's metadata › Responses

object · required

GET/e-invoicing/documents/{id}

curl --request GET \
  --url https://api.kontier.eu/v1/e-invoicing/documents/:id

shell

Example Responses

{
  "data": {
    "byte_size": 0,
    "content_hash": "content_hash",
    "content_type": "content_type",
    "created_at": "2024-08-25T15:00:00Z",
    "credit_note_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "credit_note_number": "credit_note_number",
    "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "invoice_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "invoice_number": "invoice_number",
    "jurisdiction": "jurisdiction",
    "profile": "profile",
    "profile_source": "profile_source",
    "profile_source_detail": "profile_source_detail",
    "quarantine_reason": "quarantine_reason",
    "syntax": "syntax"
  }
}

json

application/json

List validation findings for an e-invoice document

GET

https://api.kontier.eu/v1

/e-invoicing/documents/{id}/findings

Returns every validation finding recorded for the document, resolved ones included (those carry resolved_at and resolution_notes). Findings identify the violated rule, severity, and the XPath of the offending element where available.

List validation findings for an e-invoice document › path Parameters

id

string · uuid · required

Document UUID

List validation findings for an e-invoice document › Headers

X-Workspace-Id

string

Workspace UUID or slug.

List validation findings for an e-invoice document › Responses

array | null · required

object · required

Download an e-invoice document's bytes

GET

https://api.kontier.eu/v1

/e-invoicing/documents/{id}/raw

Streams the artifact bytes with a Content-Disposition attachment header. With ?presigned=1 the response is a 302 redirect to a short-lived presigned URL instead.

Download an e-invoice document's bytes › path Parameters

id

string · uuid · required

Document UUID

Download an e-invoice document's bytes › query Parameters

presigned

string

Return a 302 redirect to a presigned URL instead of streaming (presigned=1)

Download an e-invoice document's bytes › Headers

X-Workspace-Id

string

Workspace UUID or slug.

Download an e-invoice document's bytes › Responses

Document bytes

No data returned

Mark a finding resolved (operator override)

POST

https://api.kontier.eu/v1

/e-invoicing/findings/{id}/resolve

Stamps the finding resolved_at with optional operator notes from the body ({"notes": "..."}; a bare POST resolves with empty notes). Record-keeping only: the document is not re-validated and its quarantine state is untouched. A finding that is already resolved responds 404.

Mark a finding resolved (operator override) › path Parameters

id

string · uuid · required

Finding UUID

Mark a finding resolved (operator override) › Headers

Idempotency-Key

string · required

Client-generated idempotency key (e.g. a UUID).

X-Workspace-Id

string

Workspace UUID or slug.

Mark a finding resolved (operator override) › Request Body

notes

string · maxLength: 2000

Optional operator notes explaining why the finding was overridden/resolved.

Mark a finding resolved (operator override) › Responses

No Content

No data returned

List the per-country e-invoice format rules

GET

https://api.kontier.eu/v1

/e-invoicing/profile-rules

The jurisdiction level of format selection: "buyers in this country (optionally this region) get this profile". Ordered by country, with the country-wide rule of each country first. A rule with an empty region covers the whole country; a region rule outranks it. These rules sit BELOW an explicit profile on the request and below the customer's own einvoice_profile, and ABOVE the organization's default_einvoice_profile setting.

List the per-country e-invoice format rules › Headers

X-Workspace-Id

string

Workspace UUID or slug.

List the per-country e-invoice format rules › Responses

array | null · required

object · required

Add a per-country e-invoice format rule

POST

https://api.kontier.eu/v1

/e-invoicing/profile-rules

Creates the rule mapping (country, optional region) to a profile. The profile must be one this deployment offers (GET /e-invoicing/profiles) - a retired or unproducible one is refused here with 400 rather than discovered asynchronously when an invoice is finalized. One rule per (country, region): a duplicate answers 409, so change an existing rule with PATCH rather than adding a second.

Add a per-country e-invoice format rule › Headers

Idempotency-Key

string · required

Client-generated idempotency key (e.g. a UUID).

X-Workspace-Id

string

Workspace UUID or slug.

Add a per-country e-invoice format rule › Request Body

country

string · minLength: 2 · maxLength: 2 · required

ISO 3166-1 alpha-2 country code of the buyer, upper-case. Matched against the customer's billing address country.

Example: DE

profile_id

string · maxLength: 100 · required

E-invoice profile buyers matching this rule get. Must be one this deployment offers - see GET /v1/e-invoicing/profiles.

Example: XRECHNUNG_3_0_UBL

region

string · maxLength: 100

Sub-national region as an ISO 3166-2 code without the country prefix (BY for Bavaria); a name from GET /v1/e-invoicing/regions is accepted and stored as its code. Only countries listed there have a region axis. Omit for a rule covering the whole country; a region rule outranks its own country-wide rule.

Example: BY

Add a per-country e-invoice format rule › Responses

Created

object · required

Remove a per-country e-invoice format rule

DELETE

https://api.kontier.eu/v1

/e-invoicing/profile-rules/{id}

Deletes the rule. Buyers it covered fall through to the next level of the chain - a wider rule for the same country, or the organization default. Documents already generated are unaffected; their profile is recorded on the document row.

Remove a per-country e-invoice format rule › path Parameters

id

string · uuid · required

Profile rule UUID

Remove a per-country e-invoice format rule › Headers

X-Workspace-Id

string

Workspace UUID or slug.

Remove a per-country e-invoice format rule › Responses

No Content

No data returned

Change the format a rule selects

PATCH

https://api.kontier.eu/v1

/e-invoicing/profile-rules/{id}

Replaces the rule's profile. The (country, region) key is deliberately immutable - re-keying a rule in place is indistinguishable from deleting one and creating another, and it moves the row out from under whoever is looking at it. Delete and re-create to change the jurisdiction.

Change the format a rule selects › path Parameters

id

string · uuid · required

Profile rule UUID

Change the format a rule selects › Headers

X-Workspace-Id

string

Workspace UUID or slug.

Change the format a rule selects › Request Body

profile_id

string · maxLength: 100 · required

Replacement e-invoice profile for this rule. Must be one this deployment offers.

Example: ZUGFERD_2_COMFORT

Change the format a rule selects › Responses

object · required

List the e-invoice formats this deployment can produce

GET

https://api.kontier.eu/v1

/e-invoicing/profiles

The profile catalogue: every format that can actually be generated, with its syntax and container. Use it to populate a format picker instead of hardcoding identifiers — a retired or unproducible profile disappears from this list, which a hand-written array does not. hybrid: true means the profile is a PDF/A-3 with the XML embedded and additionally requires a configured mustangserver.

List the e-invoice formats this deployment can produce › Headers

X-Workspace-Id

string

Workspace UUID or slug.

List the e-invoice formats this deployment can produce › Responses

array | null · required

object · required

List the regions a country rule may name

GET

https://api.kontier.eu/v1

/e-invoicing/regions

The catalogue of first-level ISO 3166-2 subdivisions, per country. A country rule's region must be one of these codes (a name is accepted on write and stored as its code), and a customer's billing-address state is matched against the same catalogue, so "Bayern", "BY" and "Bavaria" all meet a rule for DE/BY. A country absent from this list has no region axis.

List the regions a country rule may name › Headers

X-Workspace-Id

string

Workspace UUID or slug.

List the regions a country rule may name › Responses

array | null · required

object · required

Why this invoice does or does not have an e-invoice

GET

https://api.kontier.eu/v1

/e-invoicing/rollout-decisions

Returns the rollout decision the autogen worker recorded for one invoice or credit note: whether it decided to generate, WHICH mechanism answered (the customer's own preference, a rollout audience, the legacy consumer gate, the workspace switch — and never-configured distinctly from turned-off), and WHICH ROW decided, naming the audience and the revision that answered. This is the counterpart of profile_source on a document, and unlike it, it answers for the invoices with NO document — the case an operator actually asks about. Supply exactly one of ?invoice_id= or ?credit_note_id=. 404 means NO DECISION WAS RECORDED, which is its own answer and not a reason: the gate never ran for this anchor (a lost message, a worker that was down, or an invoice finalized before the decision was being recorded). generate=true with no document beside it means rendering never completed.

Why this invoice does or does not have an e-invoice › query Parameters

invoice_id

string · uuid

The invoice to explain. Supply exactly one of invoice_id / credit_note_id.

credit_note_id

string · uuid

The credit note to explain.

Why this invoice does or does not have an e-invoice › Headers

X-Workspace-Id

string

Workspace UUID or slug.

Why this invoice does or does not have an e-invoice › Responses

object · required

The delivery status of an invoice's e-invoice

GET

https://api.kontier.eu/v1

/invoices/{id}/einvoice/submission

Every attempt to get this invoice's e-invoice out of the building, newest first: the state it reached, the reference the authority or network minted, the refusal reason where there is one, and whether a re-issue applies. An EMPTY list is a real answer and not an error — a document exchanged directly with the buyer has no submission at all.

The delivery status of an invoice's e-invoice › path Parameters

id

string · uuid · required

The delivery status of an invoice's e-invoice › Headers

X-Workspace-Id

string

Workspace UUID or slug.

The delivery status of an invoice's e-invoice › Responses

object · required

GET/invoices/{id}/einvoice/submission

curl --request GET \
  --url https://api.kontier.eu/v1/invoices/:id/einvoice/submission

shell

Example Responses

{
  "data": {
    "anchor_id": "anchor_id",
    "submissions": [
      {
        "attempts": 0,
        "authority_document_id": "authority_document_id",
        "channel": "channel",
        "clearance_kind": "clearance_kind",
        "created_at": "created_at",
        "document_id": "document_id",
        "id": "id",
        "profile_id": "profile_id",
        "reason": "reason",
        "reason_code": "reason_code",
        "reissuable": true,
        "state": "state",
        "terminal": true,
        "updated_at": "updated_at",
        "validation_report": "validation_report"
      }
    ]
  }
}

json

application/json

Tax Compliance Payments