POST/v1/convert

Convert an EN 16931 invoice to Peppol / XRechnung / Factur-X

Convert a canonical EN 16931 invoice (JSON) into a compliant e-invoicing document in the target format. Use this endpoint when the user has structured invoice data and needs to generate a legally valid XML or PDF/A-3 file for submission to a Peppol access point, XRechnung portal, or Factur-X workflow. **Inputs:** an `Invoice` object (fields map to EN 16931 Business Terms BT-1…BT-158), a `target_format` code, an optional `target_profile`, and an `output` mode. **Output:** a `conversion_id` plus a 24-hour `download_url` pointing at `GET /v1/download/{conversion_id}`. Documents expire after 24 hours. **Supported target formats:** `peppol_bis_3`, `xrechnung`, `facturx`, `zugferd`, `ubl_2_1`. **Output modes:** `xml` (default, all formats) or `pdf` (Factur-X / ZUGFeRD only — embeds the XML in a PDF/A-3 container). Required scope: `einvoice:convert`.

Authentication

Requires API key via X-API-Key header.

Request body

invoiceInvoice-Inputrequired

EN 16931 invoice — canonical JSON representation. This model is the single source of truth for invoice data flowing through the API. It is used as input to /v1/convert and as output from /v1/intelligent/parse (schema idempotency).

invoice_numberstringrequired

BT-1 Invoice number

maxLen 64

issue_datestring (date)required

BT-2 Invoice issue date

type_codestringoptional

BT-3 Invoice type code (UNTDID 1001). 380=Invoice

maxLen 4 · default "380"

currency_codestringrequired

BT-5 Invoice currency code (ISO 4217)

minLen 3 · maxLen 3

due_dateanyoptional

BT-9 Payment due date

one of:

option 1:

string (date)

option 2:

null

buyer_referenceanyoptional

BT-10 Buyer reference (mandatory for XRechnung)

one of:

option 1:

string

option 2:

null

purchase_order_referenceanyoptional

BT-13 Purchase order reference

one of:

option 1:

string

option 2:

null

project_referenceanyoptional

BT-11 Project reference

one of:

option 1:

string

option 2:

null

contract_referenceanyoptional

BT-12 Contract reference

one of:

option 1:

string

option 2:

null

vat_accounting_currencyanyoptional

BT-6 VAT accounting currency

one of:

option 1:

string

option 2:

null

tax_point_dateanyoptional

BT-7 Value added tax point date

one of:

option 1:

string (date)

option 2:

null

noteanyoptional

BT-22 Invoice note

one of:

option 1:

string

option 2:

null

preceding_invoice_referenceanyoptional

BT-25 Preceding invoice reference

one of:

option 1:

string

option 2:

null

sellerPartyrequired

Seller (BG-4) or Buyer (BG-7) party.

namestringrequired

BT-27/BT-44 Party name

maxLen 256

addressAddressrequired

Postal address (BG-5 Seller / BG-8 Buyer / BG-15 Delivery).

streetstringrequired

BT-35/BT-50 Address line 1

maxLen 256

street2anyoptional

BT-36/BT-51 Address line 2

one of:

option 1:

string

option 2:

null

citystringrequired

BT-37/BT-52 City

maxLen 128

postal_codestringrequired

BT-38/BT-53 Post code

maxLen 16

country_subdivisionanyoptional

BT-39/BT-54 Country subdivision

one of:

option 1:

string

option 2:

null

country_codestringrequired

BT-40/BT-55 ISO 3166-1 alpha-2

minLen 2 · maxLen 2

vat_idanyoptional

BT-31/BT-48 VAT identifier

one of:

option 1:

string

option 2:

null

tax_registration_idanyoptional

BT-32 Tax registration ID

one of:

option 1:

string

option 2:

null

legal_registration_idanyoptional

BT-30/BT-47 Legal registration ID

one of:

option 1:

string

option 2:

null

identifieranyoptional

BT-29/BT-46 Party identifier

one of:

option 1:

string

option 2:

null

identifier_schemeanyoptional

BT-29-1/BT-46-1 Scheme ID

one of:

option 1:

string

option 2:

null

electronic_addressanyoptional

BT-34/BT-49 Electronic address

one of:

option 1:

schemestringrequired

Electronic Address Scheme (EAS), e.g. EM, 0088, 0184

maxLen 8

idstringrequired

Electronic address value

maxLen 256

option 2:

null

contactanyoptional

BG-6 Seller contact

one of:

option 1:

nameanyoptional

BT-41 Contact name

one of:

option 1:

string

option 2:

null

phoneanyoptional

BT-42 Contact telephone

one of:

option 1:

string

option 2:

null

emailanyoptional

BT-43 Contact email

one of:

option 1:

string

option 2:

null

option 2:

null

buyerPartyrequired

Seller (BG-4) or Buyer (BG-7) party.

namestringrequired

BT-27/BT-44 Party name

maxLen 256

addressAddressrequired

Postal address (BG-5 Seller / BG-8 Buyer / BG-15 Delivery).

streetstringrequired

BT-35/BT-50 Address line 1

maxLen 256

street2anyoptional

BT-36/BT-51 Address line 2

one of:

option 1:

string

option 2:

null

citystringrequired

BT-37/BT-52 City

maxLen 128

postal_codestringrequired

BT-38/BT-53 Post code

maxLen 16

country_subdivisionanyoptional

BT-39/BT-54 Country subdivision

one of:

option 1:

string

option 2:

null

country_codestringrequired

BT-40/BT-55 ISO 3166-1 alpha-2

minLen 2 · maxLen 2

vat_idanyoptional

BT-31/BT-48 VAT identifier

one of:

option 1:

string

option 2:

null

tax_registration_idanyoptional

BT-32 Tax registration ID

one of:

option 1:

string

option 2:

null

legal_registration_idanyoptional

BT-30/BT-47 Legal registration ID

one of:

option 1:

string

option 2:

null

identifieranyoptional

BT-29/BT-46 Party identifier

one of:

option 1:

string

option 2:

null

identifier_schemeanyoptional

BT-29-1/BT-46-1 Scheme ID

one of:

option 1:

string

option 2:

null

electronic_addressanyoptional

BT-34/BT-49 Electronic address

one of:

option 1:

schemestringrequired

Electronic Address Scheme (EAS), e.g. EM, 0088, 0184

maxLen 8

idstringrequired

Electronic address value

maxLen 256

option 2:

null

contactanyoptional

BG-6 Seller contact

one of:

option 1:

nameanyoptional

BT-41 Contact name

one of:

option 1:

string

option 2:

null

phoneanyoptional

BT-42 Contact telephone

one of:

option 1:

string

option 2:

null

emailanyoptional

BT-43 Contact email

one of:

option 1:

string

option 2:

null

option 2:

null

deliveryanyoptional

BG-13 Delivery information

one of:

option 1:

dateanyoptional

BT-72 Actual delivery date

one of:

option 1:

string (date)

option 2:

null

locationanyoptional

one of:

option 1:

nameanyoptional

BT-70 Deliver to party name

one of:

option 1:

...(deeper nesting omitted)

option 2:

...(deeper nesting omitted)

addressanyoptional

one of:

option 1:

...(deeper nesting omitted)

option 2:

...(deeper nesting omitted)

option 2:

null

option 2:

null

paymentanyoptional

BG-16 Payment instructions

one of:

option 1:

means_codestringrequired

BT-81 Payment means type code (UNTDID 4461)

maxLen 4

means_textanyoptional

BT-82 Payment means text

one of:

option 1:

string

option 2:

null

termsanyoptional

BT-20 Payment terms

one of:

option 1:

string

option 2:

null

bank_accountanyoptional

BG-17 Credit transfer

one of:

option 1:

ibananyoptional

BT-84 IBAN

one of:

option 1:

...(deeper nesting omitted)

option 2:

...(deeper nesting omitted)

bicanyoptional

BT-86 BIC/SWIFT

one of:

option 1:

...(deeper nesting omitted)

option 2:

...(deeper nesting omitted)

bank_nameanyoptional

Bank name (informational)

one of:

option 1:

...(deeper nesting omitted)

option 2:

...(deeper nesting omitted)

account_nameanyoptional

BT-85 Account name

one of:

option 1:

...(deeper nesting omitted)

option 2:

...(deeper nesting omitted)

option 2:

null

payment_idanyoptional

BT-83 Remittance information

one of:

option 1:

string

option 2:

null

option 2:

null

linesarray<InvoiceLine-Input>required

BG-25 Invoice lines (at least one)

minItems 1

array of InvoiceLine-Input

idstringrequired

BT-126 Invoice line identifier

maxLen 32

descriptionstringrequired

BT-153 Item name

maxLen 512

quantityanyrequired

BT-129 Invoiced quantity

one of:

option 1:

number

option 2:

string

unitstringrequired

BT-130 Unit of measure (UN/ECE Rec 20)

maxLen 8

unit_priceanyrequired

BT-146 Item net price

one of:

option 1:

number

option 2:

string

net_amountanyrequired

BT-131 Invoice line net amount

one of:

option 1:

number

option 2:

string

vat_categorystringrequired

BT-151 VAT category code (UN/ECE 5305)

maxLen 4

vat_rateanyoptional

BT-152 VAT rate as percentage

one of:

option 1:

number

option 2:

string

option 3:

null

item_classificationanyoptional

BT-158 Item classification

one of:

option 1:

codestringrequired

BT-158 Item classification identifier

maxLen 32

schemestringrequired

BT-158-1 Scheme identifier (e.g. STI, CPV)

maxLen 8

option 2:

null

noteanyoptional

BT-127 Invoice line note

one of:

option 1:

string

option 2:

null

order_line_referenceanyoptional

BT-132 Referenced purchase order line

one of:

option 1:

string

option 2:

null

allowance_amountanyoptional

BT-136 Invoice line allowance amount

one of:

option 1:

number

option 2:

string

option 3:

null

charge_amountanyoptional

BT-141 Invoice line charge amount

one of:

option 1:

number

option 2:

string

option 3:

null

allowancesanyoptional

BG-20/BG-21 Allowances and charges

one of:

option 1:

array of DocumentAllowanceCharge-Input

is_chargebooleanrequired

True = charge (BG-21), False = allowance (BG-20)

amountanyrequired

BT-92/BT-99 Amount

one of:

option 1:

number

option 2:

string

vat_categorystringrequired

BT-95/BT-102 VAT category code

maxLen 4

vat_rateanyoptional

BT-96/BT-103 VAT rate

one of:

option 1:

number

option 2:

string

option 3:

null

reasonanyoptional

BT-97/BT-104 Reason

one of:

option 1:

string

option 2:

null

reason_codeanyoptional

BT-98/BT-105 Reason code

one of:

option 1:

string

option 2:

null

option 2:

null

country_extensionsanyoptional

Country-specific fields

one of:

option 1:

itanyoptional

one of:

option 1:

codice_destinatariostringrequired

SDI recipient code

minLen 7 · maxLen 7

codice_fiscale_selleranyoptional

Seller Codice Fiscale

one of:

option 1:

...(deeper nesting omitted)

option 2:

...(deeper nesting omitted)

codice_fiscale_buyeranyoptional

Buyer Codice Fiscale

one of:

option 1:

...(deeper nesting omitted)

option 2:

...(deeper nesting omitted)

regime_fiscalestringoptional

Tax regime code

maxLen 4 · default "RF01"

tipo_documentostringoptional

Document type code

maxLen 4 · default "TD01"

option 2:

null

deanyoptional

one of:

option 1:

leitweg_idstringrequired

Leitweg-ID (BT-10 routing ID for German B2G)

maxLen 64

option 2:

null

planyoptional

one of:

option 1:

nip_sellerstringrequired

Seller NIP

maxLen 10

nip_buyeranyoptional

Buyer NIP

one of:

option 1:

...(deeper nesting omitted)

option 2:

...(deeper nesting omitted)

gtu_codesanyoptional

GTU goods/services type codes

one of:

option 1:

...(deeper nesting omitted)

option 2:

...(deeper nesting omitted)

split_paymentbooleanoptional

MPP split payment flag

default false

option 2:

null

esanyoptional

one of:

option 1:

nif_sellerstringrequired

Seller NIF

maxLen 16

face_oficina_contableanyoptional

FACe routing code

one of:

option 1:

...(deeper nesting omitted)

option 2:

...(deeper nesting omitted)

face_organo_gestoranyoptional

FACe routing code

one of:

option 1:

...(deeper nesting omitted)

option 2:

...(deeper nesting omitted)

face_unidad_tramitadoraanyoptional

FACe routing code

one of:

option 1:

...(deeper nesting omitted)

option 2:

...(deeper nesting omitted)

option 2:

null

franyoptional

one of:

option 1:

siret_selleranyoptional

Seller SIRET

one of:

option 1:

...(deeper nesting omitted)

option 2:

...(deeper nesting omitted)

siret_buyeranyoptional

Buyer SIRET

one of:

option 1:

...(deeper nesting omitted)

option 2:

...(deeper nesting omitted)

service_codeanyoptional

Chorus Pro service code

one of:

option 1:

...(deeper nesting omitted)

option 2:

...(deeper nesting omitted)

option 2:

null

option 2:

null

target_formatstringrequired

Target e-invoicing format code: peppol_bis_3, xrechnung, facturx, ubl_2_1

target_profileanyoptional

Format profile (e.g. facturx_en16931, facturx_basic, facturx_minimum)

one of:

option 1:

string

option 2:

null

outputstringoptionalenum: xml | pdf

Output type. 'pdf' only for Factur-X.

default "xml"

Example request

curl

curl -X POST \
  "https://einvoice.aethar.dev/api/v1/convert" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"invoice":{"invoice_number":"string","issue_date":"string","type_code":"380","currency_code":"string","seller":{"name":"string","address":{"street":"string","city":"string","postal_code":"string","country_code":"string"}},"buyer":{"name":"string","address":{"street":"string","city":"string","postal_code":"string","country_code":"string"}},"lines":[{"id":"string","description":"string","unit":"string","vat_category":"string"}]},"target_format":"string","output":"xml"}'

Responses

200Successful Response

dataConversionResultrequired

Conversion result returned in the response envelope.

conversion_idstring (uuid)required

Unique conversion identifier (UUID)

target_formatstringrequired

target_profileanyoptional

one of:

option 1:

string

option 2:

null

statusstringoptionalenum: success | error

default "success"

document_size_bytesanyoptional

one of:

option 1:

integer

option 2:

null

processing_msanyoptional

one of:

option 1:

integer

option 2:

null

download_urlanyoptional

URL to download the converted document (24h TTL)

one of:

option 1:

string

option 2:

null

download_expires_atanyoptional

one of:

option 1:

string (date-time)

option 2:

null

metadataMetadataSchemarequired

sourcesarray<SourceSchema>optional

array of SourceSchema

namestringrequired

Data source name

urlanyoptional

URL to the source

one of:

option 1:

string

option 2:

null

request_idstringrequired

Unique request identifier

rate_limitanyoptional

one of:

option 1:

object

option 2:

null

400Conversion failed — malformed invoice, missing required EN 16931 fields, or unsupported target format.

errorErrorDetailrequired

Structured error payload returned by all Aethar APIs. Mirrors the shape produced by aethar_auth.exception_handlers so the OpenAPI spec accurately describes real error bodies for documentation readers and MCP clients.

codestringrequired

Machine-readable error code (e.g. INVALID_API_KEY)

messagestringrequired

Human-readable error message

statusintegerrequired

HTTP status code

request_idstringrequired

Request identifier — include in support tickets

suggestionanyoptional

Actionable hint on how to resolve the error

one of:

option 1:

string

option 2:

null

doc_urlanyoptional

Link to full documentation for this error code

one of:

option 1:

string

option 2:

null

fieldanyoptional

Field that caused the error (if applicable)

one of:

option 1:

string

option 2:

null

errorsanyoptional

Per-field validation errors (only for 422 VALIDATION_ERROR responses)

one of:

option 1:

array of object

object

option 2:

null

401Missing or invalid API key.

errorErrorDetailrequired

codestringrequired

Machine-readable error code (e.g. INVALID_API_KEY)

messagestringrequired

Human-readable error message

statusintegerrequired

HTTP status code

request_idstringrequired

Request identifier — include in support tickets

suggestionanyoptional

Actionable hint on how to resolve the error

one of:

option 1:

string

option 2:

null

doc_urlanyoptional

Link to full documentation for this error code

one of:

option 1:

string

option 2:

null

fieldanyoptional

Field that caused the error (if applicable)

one of:

option 1:

string

option 2:

null

errorsanyoptional

Per-field validation errors (only for 422 VALIDATION_ERROR responses)

one of:

option 1:

array of object

object

option 2:

null

403API key lacks the required scope for this endpoint.

errorErrorDetailrequired

codestringrequired

Machine-readable error code (e.g. INVALID_API_KEY)

messagestringrequired

Human-readable error message

statusintegerrequired

HTTP status code

request_idstringrequired

Request identifier — include in support tickets

suggestionanyoptional

Actionable hint on how to resolve the error

one of:

option 1:

string

option 2:

null

doc_urlanyoptional

Link to full documentation for this error code

one of:

option 1:

string

option 2:

null

fieldanyoptional

Field that caused the error (if applicable)

one of:

option 1:

string

option 2:

null

errorsanyoptional

Per-field validation errors (only for 422 VALIDATION_ERROR responses)

one of:

option 1:

array of object

object

option 2:

null

422Request validation failed (bad JSON shape, missing required fields, etc.).

errorErrorDetailrequired

codestringrequired

Machine-readable error code (e.g. INVALID_API_KEY)

messagestringrequired

Human-readable error message

statusintegerrequired

HTTP status code

request_idstringrequired

Request identifier — include in support tickets

suggestionanyoptional

Actionable hint on how to resolve the error

one of:

option 1:

string

option 2:

null

doc_urlanyoptional

Link to full documentation for this error code

one of:

option 1:

string

option 2:

null

fieldanyoptional

Field that caused the error (if applicable)

one of:

option 1:

string

option 2:

null

errorsanyoptional

Per-field validation errors (only for 422 VALIDATION_ERROR responses)

one of:

option 1:

array of object

object

option 2:

null

429Daily rate limit exceeded for this API key.

errorErrorDetailrequired

codestringrequired

Machine-readable error code (e.g. INVALID_API_KEY)

messagestringrequired

Human-readable error message

statusintegerrequired

HTTP status code

request_idstringrequired

Request identifier — include in support tickets

suggestionanyoptional

Actionable hint on how to resolve the error

one of:

option 1:

string

option 2:

null

doc_urlanyoptional

Link to full documentation for this error code

one of:

option 1:

string

option 2:

null

fieldanyoptional

Field that caused the error (if applicable)

one of:

option 1:

string

option 2:

null

errorsanyoptional

Per-field validation errors (only for 422 VALIDATION_ERROR responses)

one of:

option 1:

array of object

object

option 2:

null

500Unexpected server error. Includes a request_id for support.

errorErrorDetailrequired

codestringrequired

Machine-readable error code (e.g. INVALID_API_KEY)

messagestringrequired

Human-readable error message

statusintegerrequired

HTTP status code

request_idstringrequired

Request identifier — include in support tickets

suggestionanyoptional

Actionable hint on how to resolve the error

one of:

option 1:

string

option 2:

null

doc_urlanyoptional

Link to full documentation for this error code

one of:

option 1:

string

option 2:

null

fieldanyoptional

Field that caused the error (if applicable)

one of:

option 1:

string

option 2:

null

errorsanyoptional

Per-field validation errors (only for 422 VALIDATION_ERROR responses)

one of:

option 1:

array of object

object

option 2:

null

Try this endpoint

Create a free Aethar account and generate an API key in 2 minutes.

Create free account →