Automatisation Blog Tarifs Contact
v1.0.0

API Reference

The InvoiceXML API lets you convert PDF invoices into structured e-invoicing formats and validate compliance — all via simple REST endpoints.

Base URL

https://api.invoicexml.com

All endpoints are relative to this base URL. The API is served over HTTPS only.

Authentication

Authenticate every request by including your API key in the Authorization header. 

Authorization: Bearer YOUR_API_KEY

Rate Limits

API requests are rate-limited per API key. The current limits depend on your plan:

Plan Requests / minute Requests / month
Free 10 100
Starter 60 5,000
Business 120 50,000

When you exceed the limit, the API returns 429 Too Many Requests. The response includes a Retry-After header indicating how many seconds to wait before retrying.

Error Handling

The API returns errors as RFC 7807 ProblemDetails JSON objects. Every error response includes a machine-readable errorCode and an errors object with structured details. 

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "title": "Validation Failed",
  "status": 400,
  "errorCode": 4001,
  "detail": "The invoice contains 2 validation error(s).",
  "errors": {
    "xml": [
      "[BR-01] An invoice shall have a specification identifier.",
      "[BR-06] An invoice shall contain the seller name."
    ]
  }
}

Error Codes

The errorCode field identifies the category of error. Use it to decide how to handle the response programmatically.

errorCode Name Description errors key
4000 General Error An unclassified processing error. Check title and detail for information. —
4001 XML Validation The invoice XML violates EN 16931 Schematron business rules (e.g. BR-01, BR-CO-15). Each violated rule is listed in the errors.xml array. errors.xml[]
4002 Model Validation One or more request fields are missing or invalid. Each field's errors are listed under errors.{FieldName}. errors.{Field}[]
4003 File Too Large The uploaded file exceeds the 20 MB size limit. —
4004 Unsupported Format The uploaded file type is not supported for that endpoint. —
4005 Extraction Failed The API could not extract invoice data from the PDF. The document may not be an invoice, or a corrupted file. —
4006 Rate Limited You have exceeded the request rate limit for your plan. Retry after the period indicated in the Retry-After header. —
4007 Quota Exceeded Your monthly request quota has been reached. Upgrade your plan or wait for the next billing cycle. —

HTTP Status Codes

Status Meaning
200 Success — the request completed and the result is in the response body.
400 Bad Request — validation or processing error. See errorCode and errors for details.
401 Unauthorized — missing or invalid API key in the Authorization header.
422 Unprocessable Entity — the file format is not supported for this endpoint.
429 Too Many Requests — rate limit exceeded. Check the Retry-After header.
500 Internal Server Error — an unexpected error occurred. Retry the request or contact support.

Handling Errors in Code

Parse the JSON response body and branch on errorCode to handle each category. For 4002 (model validation), iterate errors to display field-level messages. For 4001 (XML validation), read errors.xml for the list of violated business rules. 

const response = await fetch(url, { method: 'POST', body: formData });

if (!response.ok) {
  const problem = await response.json();

  switch (problem.errorCode) {
    case 4002: // Model validation — field-level errors
      for (const [field, messages] of Object.entries(problem.errors)) {
        console.error(`${field}: ${messages.join(', ')}`);
      }
      break;

    case 4001: // XML validation — Schematron rule violations
      const xmlErrors = problem.errors?.xml ?? [];
      xmlErrors.forEach(err => console.error(err));
      break;

    default:   // 4000, 4003–4007: general errors
      console.error(`${problem.title}: ${problem.detail}`);
  }
}

Endpoints

Convert

Transform PDF invoices into Factur-X, ZUGFeRD, CII, EN 16931, or XRechnung formats.

Create

Generate compliant e-invoices from structured data — no source PDF needed.

Extract

Extract embedded XML from a PDF or generate CII XML from any invoice using AI.

Validate

Validate e-invoices against Factur-X, ZUGFeRD, CII, or EN 16931 compliance rules.

Quick Example

curl -X POST https://api.invoicexml.com/v1/convert/facturx \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "[email protected]"