Generate invoice PDFs and EN16931-core e-invoice XML with the InvoiceCraftly Developer Document API

1. Get an API key

Sign in with your InvoiceCraftly account, then generate a key from the account page. Only one key is active per account — generating a new key immediately revokes the previous one. The full key is shown exactly once, at generation time, so store it somewhere safe.

Sign in and get your API key

2. Authenticate your request

Every request to the Developer Document API carries your key as a bearer token in the Authorization header. Keys always start with the dk_live_ prefix, which makes a leaked key easy to spot and rotate.

Authorization: Bearer dk_live_YOUR_API_KEY_HERE
Content-Type: application/json

A missing, malformed, or revoked key returns 401 with error code AUTHENTICATION_FAILED. Query-string keys are never accepted — the key must be sent in the Authorization header.

3. Send an invoice, get a PDF back

The request body is a single JSON invoice document — no wrapper object, no multi-step upload. Save this fixture as invoice.json in your project; every example below sends this exact document:

{
  "type": "invoice",
  "number": "INV-1042",
  "issueDate": "2026-09-05",
  "dueDate": "2026-09-19",
  "currency": "USD",
  "seller": {
    "name": "Fixture Seller Studio",
    "addressLines": ["12 Render Way", "Austin, TX 73301", "United States"]
  },
  "buyer": {
    "name": "Fixture Buyer Co",
    "addressLines": ["400 Client Ave", "Denver, CO 80202", "United States"]
  },
  "items": [
    {
      "description": "Brand design retainer",
      "quantity": 2,
      "unitPrice": 150,
      "taxRate": 8.25,
      "taxLabel": "Sales Tax"
    }
  ],
  "payment": {
    "iban": "DE89370400440532013000",
    "reference": "INV-1042",
    "terms": "Net 14"
  }
}

curl https://invoicecraftly.com/api/v1/documents/pdf \
  -X POST \
  -H "Authorization: Bearer dk_live_YOUR_API_KEY_HERE" \
  -H "Content-Type: application/json" \
  --data @invoice.json \
  --output invoice.pdf

// Node.js 18+, built-in fetch — no dependency install
import { readFileSync } from 'node:fs';
import { writeFile } from 'node:fs/promises';

const invoice = JSON.parse(readFileSync('invoice.json', 'utf8'));

const response = await fetch('https://invoicecraftly.com/api/v1/documents/pdf', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer dk_live_YOUR_API_KEY_HERE',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(invoice)
});
if (!response.ok) throw new Error(`Render failed: ${response.status}`);
await writeFile('invoice.pdf', Buffer.from(await response.arrayBuffer()));

# pip install requests
import json
import requests

with open("invoice.json") as f:
    invoice = json.load(f)

response = requests.post(
    "https://invoicecraftly.com/api/v1/documents/pdf",
    headers={
        "Authorization": "Bearer dk_live_YOUR_API_KEY_HERE",
        "Content-Type": "application/json",
    },
    json=invoice,
)
response.raise_for_status()
with open("invoice.pdf", "wb") as f:
    f.write(response.content)

// Plain PHP, curl extension only — no Composer package required
$invoice = file_get_contents('invoice.json');

$ch = curl_init('https://invoicecraftly.com/api/v1/documents/pdf');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer dk_live_YOUR_API_KEY_HERE',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => $invoice,
    CURLOPT_RETURNTRANSFER => true,
]);
$pdf = curl_exec($ch);
file_put_contents('invoice.pdf', $pdf);
curl_close($ch);

A successful call returns 200 with Content-Type: application/pdf and the finished document as the response body — write it straight to a file or stream it to your own user. An X-Render-Duration-Ms header reports how long the render took.

4. Check EN16931-core e-invoice readiness

Before you commit to generating a structured e-invoice, check whether an invoice is ready — and see exactly what's missing if it isn't. This endpoint returns diagnostics only, no XML. The body is the same document object as the PDF endpoint, plus an optional supplement object carrying EN16931-core-specific fields (postal addresses, tax identifiers, per-line unit and VAT category codes) that a plain invoice document doesn't otherwise capture:

{
  "document": { /* same shape as the PDF endpoint's invoice.json */ },
  "supplement": {
    "version": 1,
    "seller": {
      "postalAddress": { "countryCode": "NO", "city": "Oslo", "postalCode": "0154" },
      "taxId": { "role": "legal-registration", "schemeId": "0192" },
      "vatIdentifier": "NO123456785MVA"
    },
    "buyer": {
      "postalAddress": { "countryCode": "NO", "city": "Oslo", "postalCode": "0184" }
    },
    "lines": [
      { "sourceIndex": 0, "unitCode": "HUR", "vatCategoryCode": "S" }
    ]
  }
}

curl https://invoicecraftly.com/api/v1/invoices/readiness \
  -X POST \
  -H "Authorization: Bearer dk_live_YOUR_API_KEY_HERE" \
  -H "Content-Type: application/json" \
  --data @readiness-request.json

// Node.js 18+, built-in fetch — no dependency install
import { readFileSync } from 'node:fs';

const requestBody = readFileSync('readiness-request.json', 'utf8');

const response = await fetch('https://invoicecraftly.com/api/v1/invoices/readiness', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer dk_live_YOUR_API_KEY_HERE',
    'Content-Type': 'application/json'
  },
  body: requestBody
});
const readiness = await response.json();
console.log(readiness.ready, readiness.gaps);

# pip install requests
import json
import requests

with open("readiness-request.json") as f:
    request_body = json.load(f)

response = requests.post(
    "https://invoicecraftly.com/api/v1/invoices/readiness",
    headers={
        "Authorization": "Bearer dk_live_YOUR_API_KEY_HERE",
        "Content-Type": "application/json",
    },
    json=request_body,
)
response.raise_for_status()
readiness = response.json()
print(readiness["ready"], readiness["gaps"])

// Plain PHP, curl extension only — no Composer package required
$requestBody = file_get_contents('readiness-request.json');

$ch = curl_init('https://invoicecraftly.com/api/v1/invoices/readiness');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer dk_live_YOUR_API_KEY_HERE',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => $requestBody,
    CURLOPT_RETURNTRANSFER => true,
]);
$readiness = json_decode(curl_exec($ch), true);
curl_close($ch);

A successful call returns 200 with a JSON body — never a 422 for an invoice that's merely incomplete, since "not ready yet" is a normal, expected outcome here:

{
  "apiVersion": "v1",
  "profileId": "en16931-core",
  "specificationIdentifier": "urn:cen.eu:en16931:2017",
  "ready": false,
  "gaps": [
    { "id": "EN16931-CORE-SELLER-VAT-IDENTIFIER", "message": "Seller is missing a VAT identifier." }
  ]
}

There's no artifact or xml field in this response — this endpoint reports diagnostics only. Once gaps is empty and ready is true, call the structured artifact endpoint below to get the actual XML.

5. Get the EN16931-core XML artifact

Same request body as the readiness endpoint above — document plus optional supplement — but the response also carries the rendered EN16931-core UBL/XML when the invoice is ready:

curl https://invoicecraftly.com/api/v1/documents/structured \
  -X POST \
  -H "Authorization: Bearer dk_live_YOUR_API_KEY_HERE" \
  -H "Content-Type: application/json" \
  --data @readiness-request.json

// Node.js 18+, built-in fetch — no dependency install
import { readFileSync, writeFileSync } from 'node:fs';

const requestBody = readFileSync('readiness-request.json', 'utf8');

const response = await fetch('https://invoicecraftly.com/api/v1/documents/structured', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer dk_live_YOUR_API_KEY_HERE',
    'Content-Type': 'application/json'
  },
  body: requestBody
});
const result = await response.json();
if (result.ready) writeFileSync('invoice.xml', result.artifact.content);

# pip install requests
import json
import requests

with open("readiness-request.json") as f:
    request_body = json.load(f)

response = requests.post(
    "https://invoicecraftly.com/api/v1/documents/structured",
    headers={
        "Authorization": "Bearer dk_live_YOUR_API_KEY_HERE",
        "Content-Type": "application/json",
    },
    json=request_body,
)
response.raise_for_status()
result = response.json()
if result["ready"]:
    with open("invoice.xml", "w", encoding="utf-8") as f:
        f.write(result["artifact"]["content"])

// Plain PHP, curl extension only — no Composer package required
$requestBody = file_get_contents('readiness-request.json');

$ch = curl_init('https://invoicecraftly.com/api/v1/documents/structured');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer dk_live_YOUR_API_KEY_HERE',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => $requestBody,
    CURLOPT_RETURNTRANSFER => true,
]);
$result = json_decode(curl_exec($ch), true);
if ($result['ready']) file_put_contents('invoice.xml', $result['artifact']['content']);

A successful call returns 200 with JSON. When ready, artifact.content holds the EN16931-core XML as a string; when not ready, artifact is null and gaps explains why:

{
  "apiVersion": "v1",
  "profileId": "en16931-core",
  "specificationIdentifier": "urn:cen.eu:en16931:2017",
  "ready": true,
  "gaps": [],
  "artifact": { "mediaType": "application/xml", "content": "<Invoice ...>...</Invoice>" }
}

This is EN16931-core UBL/XML, not a Peppol BIS artifact. There's no network delivery, no Access Point transmission, and no official-conformance claim — it's a structured export you can feed into your own validation or delivery pipeline, not a finished Peppol e-invoice.

Invoice document fields

The request body is a PublicDocumentV1 invoice: plain, versioned JSON — not InvoiceCraftly's internal editor format. Unknown fields are rejected outright rather than silently ignored.

The readiness and structured artifact endpoints wrap this same document in a request envelope, plus an optional supplement object carrying EN16931-core-specific fields a plain invoice document doesn't capture:

Missing supplement fields aren't rejected — they simply show up as entries in the response's gaps array, so you can call the readiness endpoint first, fill in what it flags, then re-check.

Errors

Every error — validation, authentication, quota, or render failure — comes back as the same JSON envelope, never a raw stack trace or an undocumented code:

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Too many requests. Please slow down.",
    "requestId": null,
    "details": []
  }
}

API changelog

This tracks changes to the /v1 contract itself — request/response shape, authentication, and quota behaviour. For product-wide feature announcements across the whole InvoiceCraftly app, see the changelog.

• 2026-09-06 — Added POST /api/v1/invoices/readiness (EN16931-core e-invoice readiness diagnostics, no artifact) and POST /api/v1/documents/structured (readiness diagnostics plus the EN16931-core UBL/XML artifact when ready). Both reuse the same API key as the PDF endpoint, aren't quota-limited yet, and never claim Peppol BIS conformance.
• 2026-09-05 — v1 beta launched: POST /api/v1/documents/pdf, invoice document type with the Ledger template only, API keys with a 100-render monthly quota.

Frequently asked questions