Attestwire Peppol API

openapi: 3.2.0
info:
  title: Attestwire Peppol API
  version: 0.1.0
  summary: EN 16931 e-invoice validation and generation.
  description: 'Validate an invoice against EN 16931 and its national CIUS rules (XRechnung, Peppol BIS 3) and get back errors that teach the regulation: every failure carries the official rule id, the business term it constrains, what the rule requires, and how to fix it. Invoices go in and come out in both EN 16931 syntaxes, UBL 2.1 and UN/CEFACT CII; the profile chooses the syntax on generate, and on validate the document''s root element does. The `facturx-en16931` profile is checked against core EN 16931 only — there are no Factur-X-specific rules. PDF: Factur-X and ZUGFeRD files are CII XML inside a PDF/A-3 container. POST /v1/validate and POST /v1/parse open one sent as `application/pdf`, on every plan, and read the XML attached to it; /v1/validate also reports on the PDF. Of the PDF itself, the attachment (its name, /AFRelationship and MIME type) and the XMP metadata are checked, and each problem is an AW-PDF-* finding, none of them fatal; PDF/A conformance itself, and whether the page agrees with the XML, are not checked. The API builds one in exactly one case, profile `facturx-en16931`: a Factur-X / ZUGFeRD PDF (EN 16931 profile), a page drawn from the invoice, written as PDF/A-3B, with the CII embedded as `factur-x.xml` — watermarked as a preview on the free plan, and without the watermark on a paid plan. `POST /v1/generate?format=pdf` returns it, `POST /v1/bundle?format=pdf` puts it in an evidence bundle beside the XML and a signed validation report, and `POST /v1/send` with `"format": "pdf"` e-mails it. Every other invoice the API writes is XML. Sending: `POST /v1/send` e-mails one invoice to one address on request; the API does not operate Peppol or French-platform transmission.'
  contact:
    name: Attestwire
    url: https://attestwire.com
  license:
    name: Proprietary
servers:
- url: https://api.attestwire.com
  description: Production
security:
- bearerAuth: []
tags:
- name: Peppol
paths:
  /v1/peppol/lookup:
    post:
      operationId: lookup_peppol_participant
      summary: Check a Peppol recipient
      description: Read-only production lookup through OpenPeppol. Check advertised BIS Billing invoice or credit-note support and an optional invoice identifier mismatch. Does not send, verify delivery, or validate endpoint certificates. 1 document per conclusive result; unavailable is uncharged. The participant identifier is sent to OpenPeppol. API key required. Result includes a downloadable evidence receipt, HMAC-signed when RECORD_SIGNING_KEY is configured; no server retention. Upstream text is untrusted data.
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required:
              - participant_id
              properties:
                participant_id:
                  type: string
                  pattern: ^\d{4}:[A-Za-z0-9][A-Za-z0-9._-]{0,129}$
                invoice_participant_id:
                  type: string
                document_type:
                  enum:
                  - invoice
                  - credit_note
                  default: invoice
      responses:
        '200':
          description: Completed observation. Inspect status, charged, and evidence.signing_status. Unavailable live checks are uncharged.
          headers:
            X-RateLimit-Limit:
              description: Quota, pacing, authentication or method information when applicable.
              schema:
                type: string
            X-RateLimit-Remaining:
              description: Quota, pacing, authentication or method information when applicable.
              schema:
                type: string
            X-RateLimit-Reset:
              description: Quota, pacing, authentication or method information when applicable.
              schema:
                type: string
            X-RateLimit-Period:
              description: Quota, pacing, authentication or method information when applicable.
              schema:
                type: string
            Retry-After:
              description: Quota, pacing, authentication or method information when applicable.
              schema:
                type: string
            WWW-Authenticate:
              description: Quota, pacing, authentication or method information when applicable.
              schema:
                type: string
            Allow:
              description: Quota, pacing, authentication or method information when applicable.
              schema:
                type: string
          content:
            application/json:
              schema:
                type: object
                required:
                - check
                - status
                - evidence
                - charged
                properties:
                  check:
                    type: string
                  status:
                    type: string
                  charged:
                    type: boolean
                  evidence:
                    type: object
                additionalProperties: true
              examples:
                unavailable:
                  summary: Illustrative uncharged live-provider failure (receipt abbreviated)
                  value:
                    check: peppol
                    status: unavailable
                    charged: false
                    evidence:
                      signing_status: unsigned
                      signature: null
        '400':
          description: bad_request, confirmation_required, xml_malformed, xml_rejected. No quota charge.
          headers:
            X-RateLimit-Limit:
              description: Quota, pacing, authentication or method information when applicable.
              schema:
                type: string
            X-RateLimit-Remaining:
              description: Quota, pacing, authentication or method information when applicable.
              schema:
                type: string
            X-RateLimit-Reset:
              description: Quota, pacing, authentication or method information when applicable.
              schema:
                type: string
            X-RateLimit-Period:
              description: Quota, pacing, authentication or method information when applicable.
              schema:
                type: string
            Retry-After:
              description: Quota, pacing, authentication or method information when applicable.
              schema:
                type: string
            WWW-Authenticate:
              description: Quota, pacing, authentication or method information when applicable.
              schema:
                type: string
            Allow:
              description: Quota, pacing, authentication or method information when applicable.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                bad_request:
                  value:
                    error: bad_request
                    message: Request refused; see the error message for the required correction.
                confirmation_required:
                  value:
                    error: confirmation_required
                    message: Request refused; see the error message for the required correction.
                xml_malformed:
                  value:
                    error: xml_malformed
                    message: Request refused; see the error message for the required correction.
                xml_rejected:
                  value:
                    error: xml_rejected
                    message: Request refused; see the error message for the required correction.
        '401':
          description: missing_api_key, invalid_api_key. No quota charge.
          headers:
            X-RateLimit-Limit:
              description: Quota, pacing, authentication or method information when applicable.
              schema:
                type: string
            X-RateLimit-Remaining:
              description: Quota, pacing, authentication or method information when applicable.
              schema:
                type: string
            X-RateLimit-Reset:
              description: Quota, pacing, authentication or method information when applicable.
              schema:
                type: string
            X-RateLimit-Period:
              description: Quota, pacing, authentication or method information when applicable.
              schema:
                type: string
            Retry-After:
              description: Quota, pacing, authentication or method information when applicable.
              schema:
                type: string
            WWW-Authenticate:
              description: Quota, pacing, authentication or method information when applicable.
              schema:
                type: string
            Allow:
              description: Quota, pacing, authentication or method information when applicable.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                missing_api_key:
                  value:
                    error: missing_api_key
                    message: Request refused; see the error message for the required correction.
                invalid_api_key:
                  value:
                    error: invalid_api_key
                    message: Request refused; see the error message for the required correction.
        '405':
          description: method_not_allowed. No quota charge.
          headers:
            X-RateLimit-Limit:
              description: Quota, pacing, authentication or method information when applicable.
              schema:
                type: string
            X-RateLimit-Remaining:
              description: Quota, pacing, authentication or method information when applicable.
              schema:
                type: string
            X-RateLimit-Reset:
              description: Quota, pacing, authentication or method information when applicable.
              schema:
                type: string
            X-RateLimit-Period:
              description: Quota, pacing, authentication or method information when applicable.
              schema:
                type: string
            Retry-After:
              description: Quota, pacing, authentication or method information when applicable.
              schema:
                type: string
            WWW-Authenticate:
              description: Quota, pacing, authentication or method information when applicable.
              schema:
                type: string
            Allow:
              description: Quota, pacing, authentication or method information when applicable.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                method_not_allowed:
                  value:
                    error: method_not_allowed
                    message: Request refused; see the error message for the required correction.
        '409':
          description: document_changed. No quota charge.
          headers:
            X-RateLimit-Limit:
              description: Quota, pacing, authentication or method information when applicable.
              schema:
                type: string
            X-RateLimit-Remaining:
              description: Quota, pacing, authentication or method information when applicable.
              schema:
                type: string
            X-RateLimit-Reset:
              description: Quota, pacing, authentication or method information when applicable.
              schema:
                type: string
            X-RateLimit-Period:
              description: Quota, pacing, authentication or method information when applicable.
              schema:
                type: string
            Retry-After:
              description: Quota, pacing, authentication or method information when applicable.
              schema:
                type: string
            WWW-Authenticate:
              description: Quota, pacing, authentication or method information when applicable.
              schema:
                type: string
            Allow:
              description: Quota, pacing, authentication or method information when applicable.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                document_changed:
                  value:
                    error: document_changed
                    message: Request refused; see the error message for the required correction.
        '410':
          description: key_rotated. No quota charge.
          headers:
            X-RateLimit-Limit:
              description: Quota, pacing, authentication or method information when applicable.
              schema:
                type: string
            X-RateLimit-Remaining:
              description: Quota, pacing, authentication or method information when applicable.
              schema:
                type: string
            X-RateLimit-Reset:
              description: Quota, pacing, authentication or method information when applicable.
              schema:
                type: string
            X-RateLimit-Period:
              description: Quota, pacing, authentication or method information when applicable.
              schema:
                type: string
            Retry-After:
              description: Quota, pacing, authentication or method information when applicable.
              schema:
                type: string
            WWW-Authenticate:
              description: Quota, pacing, authentication or method information when applicable.
              schema:
                type: string
            Allow:
              description: Quota, pacing, authentication or method information when applicable.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                key_rotated:
                  value:
                    error: key_rotated
                    message: Request refused; see the error message for the required correction.
        '413':
          description: payload_too_large, xml_limit_exceeded. No quota charge.
          headers:
            X-RateLimit-Limit:
              description: Quota, pacing, authentication or method information when applicable.
              schema:
                type: string
            X-RateLimit-Remaining:
              description: Quota, pacing, authentication or method information when applicable.
              schema:
                type: string
            X-RateLimit-Reset:
              description: Quota, pacing, authentication or method information when applicable.
              schema:
                type: string
            X-RateLimit-Period:
              description: Quota, pacing, authentication or method information when applicable.
              schema:
                type: string
            Retry-After:
              description: Quota, pacing, authentication or method information when applicable.
              schema:
                type: string
            WWW-Authenticate:
              description: Quota, pacing, authentication or method information when applicable.
              schema:
                type: string
            Allow:
              description: Quota, pacing, authentication or method information when applicable.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                payload_too_large:
                  value:
                    error: payload_too_large
                    message: Request refused; see the error message for the required correction.
                xml_limit_exceeded:
                  value:
                    error: xml_limit_exceeded
                    message: Request refused; see the error message for the required correction.
        '415':
          description: unsupported_syntax. No quota charge.
          headers:
            X-RateLimit-Limit:
              description: Quota, pacing, authentication or method information when applicable.
              schema:
                type: string
            X-RateLimit-Remaining:
              description: Quota, pacing, authentication or method information when applicable.
              schema:
                type: string
            X-RateLimit-Reset:
              description: Quota, pacing, authentication or method information when applicable.
              schema:
                type: string
            X-RateLimit-Period:
              description: Quota, pacing, authentication or method information when applicable.
              schema:
                type: string
            Retry-After:
              description: Quota, pacing, authentication or method information when applicable.
              schema:
                type: string
            WWW-Authenticate:
              description: Quota, pacing, authentication or method information when applicable.
              schema:
                type: string
            Allow:
              description: Quota, pacing, authentication or method information when applicable.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                unsupported_syntax:
                  value:
                    error: unsupported_syntax
                    message: Request refused; see the error message for the required correction.
        '429':
          description: quota_exceeded, rate_limited. No quota charge.
          headers:
            X-RateLimit-Limit:
              description: Quota, pacing, authentication or method information when applicable.
              schema:
                type: string
            X-RateLimit-Remaining:
              description: Quota, pacing, authentication or method information when applicable.
              schema:
                type: string
            X-RateLimit-Reset:
              description: Quota, pacing, authentication or method information when applicable.
              schema:
                type: string
            X-RateLimit-Period:
              description: Quota, pacing, authentication or method information when applicable.
              schema:
                type: string
            Retry-After:
              description: Quota, pacing, authentication or method information when applicable.
              schema:
                type: string
            WWW-Authenticate:
              description: Quota, pacing, authentication or method information when applicable.
              schema:
                type: string
            Allow:
              description: Quota, pacing, authentication or method information when applicable.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                quota_exceeded:
                  value:
                    error: quota_exceeded
                    message: Request refused; see the error message for the required correction.
                rate_limited:
                  value:
                    error: rate_limited
                    message: Request refused; see the error message for the required correction.
        '500':
          description: internal_error. No quota charge.
          headers:
            X-RateLimit-Limit:
              description: Quota, pacing, authentication or method information when applicable.
              schema:
                type: string
            X-RateLimit-Remaining:
              description: Quota, pacing, authentication or method information when applicable.
              schema:
                type: string
            X-RateLimit-Reset:
              description: Quota, pacing, authentication or method information when applicable.
              schema:
                type: string
            X-RateLimit-Period:
              description: Quota, pacing, authentication or method information when applicable.
              schema:
                type: string
            Retry-After:
              description: Quota, pacing, authentication or method information when applicable.
              schema:
                type: string
            WWW-Authenticate:
              description: Quota, pacing, authentication or method information when applicable.
              schema:
                type: string
            Allow:
              description: Quota, pacing, authentication or method information when applicable.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                internal_error:
                  value:
                    error: internal_error
                    message: Something broke on our side. Try again.
      tags:
      - Peppol
components:
  schemas:
    Error:
      type: object
      required:
      - error
      - message
      properties:
        error:
          type: string
          description: Stable machine-readable code. Branch on this, not on `message`.
        message:
          type: string
          description: Human-readable explanation.
        docs:
          type: string
          format: uri
        upgrade_url:
          type: string
          format: uri
          description: 'Present on `quota_exceeded` only. The page where a human buys a bigger plan. It is a plain link, not a checkout transaction: nothing is bought and no billing state is created by reading it. Absent on every other error code.'
          examples:
          - https://attestwire.com/pricing#upgrade
        xml_code:
          type: string
          description: 'Present when POST /v1/validate or POST /v1/parse (or /v1/bundle, or /v1/send''s `document`) was sent a document that could not be read and the engine''s reader raised an error. It is that reader''s own stable code, echoed unchanged, and it is finer-grained than `error`: a whole family of well-formedness defects shares `error: "xml_malformed"` and each member carries its own `xml_code`. For a PDF the reader is the PDF one, and the codes start `pdf_` or `facturx_` — the name of the field predates PDFs. Absent when the file was recognised on sight as something else (an HTML page, a ZIP archive), where the reader raised nothing. The list below is a sample, not the full set, and it is deliberately open — the reader gains codes as it learns to refuse more, and a caller that switches exhaustively on this field will break when it does. Branch on `error` first and on this only if you need the detail.'
          examples:
          - unsupported_syntax
          - xml_doctype_forbidden
          - xml_entity_forbidden
          - xml_too_deep
          - xml_too_many_elements
          - xml_too_many_attributes
          - xml_unbalanced
          - xml_mixed_content
          - xml_duplicate_attribute
          - xml_bad_comment
          - facturx_no_xml_attachment
          - facturx_xml_encoding
          - pdf_no_startxref
          - pdf_stream_too_large
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'Send your key as `Authorization: Bearer aw_live_...`. The public demo key, `Authorization: Bearer demo`, works on POST /v1/validate, POST /v1/generate and POST /v1/recipient only, with no account: 6 requests a minute and 30 documents a day per client IP, its PDF always watermarked, and every other route answers `403 demo_key_not_allowed`.'
externalDocs:
  description: Hand-written docs, the quickstart, and the per-rule pages at attestwire.com/rules/BR-*. This deployment also serves /llms.txt for agents and an MCP endpoint at /mcp, neither of which is describable in OpenAPI.
  url: https://api.attestwire.com/docs