API Reference

Base URL

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:

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.

HTTP Status Codes

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

Quick Example

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