Automation Blog Pricing Contact

Create CII Invoice using REST-API

Generate a complete UN/CEFACT Cross Industry Invoice (CII) D16B document from structured JSON data. Submit seller and buyer details, line items, and totals — the API produces a validated CII XML checked against EN 16931 Schematron rules, ready for standalone XML delivery, ERP import, or embedding inside a ZUGFeRD or Factur-X PDF/A-3.

POST /v1/create/cii

Request

Submit invoice data as multipart/form-data. All monetary values use decimal format (e.g. 1234.56).

Invoice Header

Field Type Description
InvoiceNumber * string Unique invoice identifier (e.g. INV-2025-001).
IssueDate * string Issue date in YYYY-MM-DD format.
PaymentDueDate string Payment due date in YYYY-MM-DD format.
Currency * string ISO 4217 currency code (e.g. EUR, USD).

Seller & Buyer

Both parties share the same field structure. Replace Seller with Buyer for the buyer fields.

Field Type Description
SellerName * string Legal business name.
SellerLegalId string Legal registration number (e.g. SIRET, HRB).
SellerTaxId * string VAT identification number (e.g. DE123456789).
SellerStreet * string Street address.
SellerPostcode * string Postal code.
SellerCity * string City name.
SellerCountry * string ISO 3166-1 alpha-2 country code (e.g. DE, FR).

Line Items

Submit one or more line items using indexed field names: Lines[0].Description, Lines[1].Description, etc.

Field Type Description
Lines[n].Description * string Description of the goods or service.
Lines[n].Quantity * decimal Quantity of items.
Lines[n].UnitPrice * decimal Price per unit (net, excluding VAT).
Lines[n].LineTotal decimal Line net total. Auto-calculated from Quantity × UnitPrice if omitted.
Lines[n].UnitCode string UN/ECE Rec 20 unit code. Default: C62 (piece). Common: HUR (hour), DAY.
Lines[n].TaxPercentage * decimal VAT rate for this line (e.g. 19, 20).
Lines[n].TaxCategoryCode * string VAT category: S (standard), AE (reverse charge), E (exempt), G (export).

Totals & Payment

Field Type Description
LineTotalAmount * decimal Sum of all line net totals.
TaxTotalAmount * decimal Total VAT amount.
GrandTotalAmount * decimal Total payable amount (net + tax).
PaymentMeansCode string UNTDID 4461 code: 30 (credit transfer), 49 (SEPA DD), 54 (card).
IBAN string Seller bank account IBAN.
BIC string Seller bank BIC/SWIFT code.

Headers

Header Value
Authorization * Bearer YOUR_API_KEY
Content-Type multipart/form-data

Response

200 Returns the generated PDF as a binary download.
Content-Type: application/pdf
400 Validation failed. Returns a ProblemDetails object with field-level errors. 
{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "title": "Model Validation Failed",
  "status": 400,
  "errorCode": 4002,
  "detail": "One or more fields are invalid.",
  "errors": {
    "SellerName": ["Seller name is required."],
    "Lines[0].Description": ["Line item description is required."]
  }
}
400 The generated invoice failed EN 16931 Schematron validation. 
{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "title": "XML Validation Failed",
  "status": 400,
  "errorCode": 4001,
  "detail": "The generated invoice contains 2 validation error(s).",
  "errors": {
    "xml": [
      "[BR-CO-15] Invoice total amount with VAT = 1785.00 expected 1500.00 + 285.00.",
      "[BR-S-08] VAT category tax amount must equal category basis × rate."
    ]
  }
}

Error Reference

Errors are returned as RFC 7807 ProblemDetails. The errorCode field indicates the error category.

errorCode Meaning errors key
4001 XML validation — the generated XML violates EN 16931 Schematron rules. errors.xml[]
4002 Model validation — one or more request fields are missing or invalid. errors.{FieldName}[]
4000 General error — check detail for more information. —

Code Example

curl -X POST https://api.invoicexml.com/v1/create/cii \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "InvoiceNumber=INV-2025-001" \
  -F "IssueDate=2025-07-01" \
  -F "Currency=EUR" \
  -F "SellerName=Acme GmbH" \
  -F "SellerTaxId=DE123456789" \
  -F "SellerStreet=Musterstr. 1" \
  -F "SellerPostcode=10115" \
  -F "SellerCity=Berlin" \
  -F "SellerCountry=DE" \
  -F "BuyerName=Example Corp" \
  -F "BuyerTaxId=FR87654321012" \
  -F "BuyerStreet=12 Rue de Rivoli" \
  -F "BuyerPostcode=75001" \
  -F "BuyerCity=Paris" \
  -F "BuyerCountry=FR" \
  -F "Lines[0].Description=Consulting Services" \
  -F "Lines[0].Quantity=10" \
  -F "Lines[0].UnitPrice=150.00" \
  -F "Lines[0].UnitCode=HUR" \
  -F "Lines[0].TaxPercentage=19" \
  -F "Lines[0].TaxCategoryCode=S" \
  -F "LineTotalAmount=1500.00" \
  -F "TaxTotalAmount=285.00" \
  -F "GrandTotalAmount=1785.00" \
  -o invoice-cii.xml

Frequently Asked Questions

What is the difference between /convert/cii and /create/cii?

The /convert/cii endpoint transforms an existing PDF into a CII XML document using AI extraction. The /create/cii endpoint generates a new CII invoice from scratch using the structured JSON data you provide — no source PDF required.

Can I embed the output in a ZUGFeRD or Factur-X PDF?

Yes. The generated CII D16B XML is structurally identical to the XML embedded in ZUGFeRD 2.x and Factur-X documents. You can attach it to a PDF/A-3 container in your own pipeline. Alternatively, use /v1/create/zugferd or /v1/create/facturx to receive the complete hybrid PDF in a single API call.

What is the difference between /create/cii and /create/zugferd?

/create/cii returns a standalone CII XML file — ideal for ERP import, direct transmission, or manual PDF/A-3 embedding. /create/zugferd returns a complete ZUGFeRD-compliant PDF/A-3 with the CII XML already embedded, ready for direct B2B exchange in Germany.

How does CII differ from UBL?

Both are valid EN 16931 syntaxes. CII (UN/CEFACT) is the format used by ZUGFeRD and Factur-X and is the dominant choice in Germany and France. UBL (OASIS) is the native format of the Peppol network. Use CII when your recipient expects ZUGFeRD, Factur-X, or a CII-based integration. Use /v1/create/ubl for Peppol-destined invoices.

Is the output validated automatically?

Yes. Every generated CII document is validated against EN 16931 Schematron business rules before delivery. If validation fails (e.g. mismatched totals or missing mandatory fields), the API returns a 400 response with errorCode 4001 and the specific rule violations.