EN 16931 compliance, as an API

Post an invoice as JSON. Get back every rule it breaks — with the official rule id, the business term at fault, what the regulation actually requires, and the fix. No Java, no Schematron toolchain, no XSLT.

Quickstart

1. Get a key

Free tier, no card, 100 documents a month. One key per email address.

curl -X POST https://api.attestwire.com/v1/keys \
  -H 'content-type: application/json' \
  -d '{"email":"you@example.com"}'

{
  "key": "aw_live_qh4t2m…",
  "tier": "free",
  "monthly_limit": 100,
  "created": "2026-08-09T10:04:11.482Z"
}

2. Validate an invoice

curl -X POST https://api.attestwire.com/v1/validate \
  -H "authorization: Bearer $ATTESTWIRE_KEY" \
  -H 'content-type: application/json' \
  -d '{"profile":"xrechnung-ubl","invoiceNumber":"INV-2026-0042","issueDate":"2026-08-09","dueDate":"2026-09-08","currency":"EUR","buyerReference":"04011000-1234512345-06","seller":{"name":"Nordwind Software GmbH","vatId":"DE123456789","address":{"line1":"Hafenstraße 12","city":"Hamburg","postalCode":"20095","countryCode":"DE"},"electronicAddress":{"schemeId":"9930","value":"DE123456789"},"contact":{"name":"Buchhaltung","phone":"+49 40 1234567","email":"rechnungen@nordwind.example"}},"buyer":{"name":"Stadt Musterstadt","address":{"line1":"Rathausplatz 1","city":"Musterstadt","postalCode":"80331","countryCode":"DE"},"electronicAddress":{"schemeId":"0204","value":"04011000-1234512345-06"}},"payment":{"meansCode":"58","iban":"DE02120300000000202051","accountName":"Nordwind Software GmbH"},"paymentTerms":"Net 30 days","lines":[{"id":"1","description":"Implementation services, July 2026","quantity":12,"unitCode":"HUR","unitPrice":145,"vatCategory":"S","vatRate":19}]}'

{
  "valid": true,
  "profile": "xrechnung-ubl",
  "errors": [],
  "warnings": []
}

3. See a teaching error

Drop buyerReference from the invoice above and the XRechnung CIUS rejects it:

{
  "valid": false,
  "profile": "xrechnung-ubl",
  "errors": [
    {
      "rule": "BR-DE-15",
      "field": "BT-10",
      "severity": "fatal",
      "message": "XRechnung requires a buyer reference (BT-10). For German public-sector buyers this is the Leitweg-ID…",
      "fix": "Ask your client for their Leitweg-ID (public sector) or an order/customer reference, and set buyerReference.",
      "example": "\"buyerReference\": \"04011000-1234512345-06\"",
      "docsUrl": "https://attestwire.com/rules/BR-DE-15"
    }
  ],
  "warnings": []
}

Errors are designed to be actionable by a person or by an agent: the fix field is an instruction, not a restatement of the message, and rule is the same identifier that appears in KoSIT validator reports, so you can cross-reference an official run against ours.

Authentication

A bearer token on every metered endpoint. Keys look like aw_live_ followed by 40 characters.

authorization: Bearer aw_live_qh4t2m…

Missing or unknown keys get 401 with a link back to this page. Send the key in the header only — never in a query string, where it would land in logs and browser history. Keys are secrets: they belong on your server, not in a browser or a mobile app.

Rotating a key

Leaked a key into a git commit, a CI log, a screenshot? Replace it yourself, immediately, without opening a support ticket:

curl -X POST https://api.attestwire.com/v1/keys/rotate \
  -H "authorization: Bearer aw_live_YOUR_CURRENT_KEY"

The call is authenticated by the key you are replacing — that is the proof of ownership — and it is free: rotating consumes no documents, because a security action you might put off to save quota is a security action you will not take.

Everything follows the new key, atomically:

{
  "key": "aw_live_…",
  "tier": "starter",
  "monthly_limit": 2500,
  "period": "2026-08",
  "used": 3,
  "remaining": 2497,
  "rotated_at": "2026-08-09T12:00:00.000Z",
  "warning": "Store this key now. It is shown once and cannot be recovered. …"
}

Rotations are limited to 3 per key per UTC day, and the limit travels with the key, so chaining rotations does not reset it. Two rotate calls sent at the same time cannot both succeed: one gets the new key, the other gets 409 rotation_already_done.

If you have lost the key entirely there is no self-serve path, by design — a rotation triggered by anything other than the key itself (an email link, say) would let anyone who knows your address take your account over. Email hello@attestwire.com from the address on your Stripe billing receipt and we will do it by hand.

Endpoints

The invoice model

One JSON object, field names mapped to EN 16931 business terms. Full schema in the OpenAPI document; here is a complete valid example:

{
  "profile": "xrechnung-ubl",
  "invoiceNumber": "INV-2026-0042",
  "issueDate": "2026-08-09",
  "dueDate": "2026-09-08",
  "currency": "EUR",
  "buyerReference": "04011000-1234512345-06",
  "seller": {
    "name": "Nordwind Software GmbH",
    "vatId": "DE123456789",
    "address": {
      "line1": "Hafenstraße 12",
      "city": "Hamburg",
      "postalCode": "20095",
      "countryCode": "DE"
    },
    "electronicAddress": {
      "schemeId": "9930",
      "value": "DE123456789"
    },
    "contact": {
      "name": "Buchhaltung",
      "phone": "+49 40 1234567",
      "email": "rechnungen@nordwind.example"
    }
  },
  "buyer": {
    "name": "Stadt Musterstadt",
    "address": {
      "line1": "Rathausplatz 1",
      "city": "Musterstadt",
      "postalCode": "80331",
      "countryCode": "DE"
    },
    "electronicAddress": {
      "schemeId": "0204",
      "value": "04011000-1234512345-06"
    }
  },
  "payment": {
    "meansCode": "58",
    "iban": "DE02120300000000202051",
    "accountName": "Nordwind Software GmbH"
  },
  "paymentTerms": "Net 30 days",
  "lines": [
    {
      "id": "1",
      "description": "Implementation services, July 2026",
      "quantity": 12,
      "unitCode": "HUR",
      "unitPrice": 145,
      "vatCategory": "S",
      "vatRate": 19
    }
  ]
}

Profile support

profile selects the rule set, and it also decides whether this build can generate the document:

Narrower profiles add rules; they never remove core ones. Generation is UBL-syntax only today: xrechnung-cii and facturx-en16931 are CII documents (and Factur-X is CII embedded in a PDF/A-3), and emitting UBL under those names would produce a file that passes nothing — so /v1/generate answers 400 unsupported_profile for them rather than something plausible and invalid. Validation of those profiles is fully supported.

Error model

Two kinds of failure, and they are shaped differently on purpose.

Invoice problems come back inside a 200 as errors[] / warnings[] of teaching errors. Your invoice is wrong; the request was fine.

Request problems come back as a non-2xx with a flat envelope. Branch on error, which is stable; message is prose and may be reworded.

{
  "error": "invalid_api_key",
  "message": "That API key is not recognised.",
  "docs": "https://api.attestwire.com/docs#auth"
}

Rate limits and quotas

The quota is documents per calendar month, counted per key. One document is one /v1/validate or one /v1/generate call. /v1/keys, /v1/usage, /v1/health and this page are free.

Every metered response carries the current state, so you never have to guess:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 97
X-RateLimit-Reset: 1756684800
X-RateLimit-Period: 2026-08

Counters reset at 00:00 UTC on the 1st of each month. Over the limit you get 429 with error: "quota_exceeded" and an upgrade link — and the refused call does not consume a document, so a retry loop cannot push your reset further away.

There is no per-second rate limit today. Be reasonable; if you need sustained high throughput, talk to us first so we can tell you honestly whether it will hold.

Pricing

Upgrading

Self-serve, through Stripe-hosted Checkout — card details never touch our servers. Post your key and the plan you want, then send the customer to the url that comes back:

curl -X POST https://api.attestwire.com/v1/billing/checkout \
  -H 'content-type: application/json' \
  -d '{"key":"aw_live_…","plan":"starter"}'

{
  "url": "https://checkout.stripe.com/c/pay/cs_live_…",
  "session_id": "cs_live_…",
  "plan": "starter"
}

plan is starter or scale. The key's tier changes when Stripe confirms the subscription, so the new allowance applies from the next request after checkout completes — no redeploy, no new key.

Changing plan. Use the Stripe billing portal, linked from any receipt we send — not a second checkout. Posting to this endpoint again while you are already subscribed returns 409 already_subscribed and deliberately does nothing: it would create a second subscription and bill you for both plans. A portal switch is prorated, and your key follows the new price automatically.

If a payment fails

Renewals fail for boring reasons — an expired card, a bank's fraud hold — and the overwhelming majority recover. So a failed charge does not cut you off:

Nothing here revokes a key or deletes data — a downgrade only changes the monthly limit. Poll /v1/usage if you want to detect billing trouble programmatically.

MCP server

Attestwire is also a Model Context Protocol server, so an agent can use it as a tool rather than as an HTTP API. Endpoint: https://api.attestwire.com/mcp, streamable HTTP transport, stateless.

Five of the eight tools are free and need no key — explain_rule (any of the 57 rule ids in plain English), check_vies_status, check_french_readiness, list_approved_platforms, and issue_api_key. Connect with no credential at all and those work immediately. validate_invoice and generate_invoice need a key and cost one document each, exactly like the HTTP endpoints they wrap. Pass the key as an Authorization: Bearer header on the server, not as a tool argument.

Claude Code

claude mcp add --transport http attestwire https://api.attestwire.com/mcp

# with a key, so validate_invoice and generate_invoice work:
claude mcp add --transport http attestwire https://api.attestwire.com/mcp \
  --header "Authorization: Bearer aw_live_..."

Claude Desktop

Settings → Connectors → Add custom connector, with the URL above. Or, in claude_desktop_config.json, via the stdio bridge:

{
  "mcpServers": {
    "attestwire": {
      "command": "npx",
      "args": ["-y", "@attestwire/mcp"],
      "env": { "ATTESTWIRE_API_KEY": "aw_live_..." }
    }
  }
}

Cursor

In .cursor/mcp.json (or the global ~/.cursor/mcp.json):

{
  "mcpServers": {
    "attestwire": {
      "url": "https://api.attestwire.com/mcp",
      "headers": { "Authorization": "Bearer aw_live_..." }
    }
  }
}

Omit the headers / env block entirely to run keyless. The agent can then call issue_api_key to mint one, which is returned once and cannot be recovered — save it before continuing.

For agents

llms.txt is a compact, plain-text description of this API for LLM consumers, and openapi.json is the full OpenAPI 3.1 document. Teaching errors are written to be pasted straight into a coding agent's context: rule id, requirement, and fix, with no spec lookup required. For tool-calling agents, the MCP server is usually the better door.