openapi: 3.1.0 info: title: Peppox API version: 1.0.0 description: | Official Peppox API contract. Use an API key only from your server. The PDF2Peppol flow is upload, check, confirm, then send. For structured invoices and credit notes, /xml/generate/ generates UBL and triggers the configured Peppol submission when validation succeeds. contact: url: https://peppox.com/developers/ servers: - url: https://api.peppox.com description: Production API tags: - name: PDF2Peppol - name: Structured invoices - name: Structured credit notes - name: Sent documents - name: Received documents - name: Peppol discovery paths: /pdf2peppol/add/: post: tags: [PDF2Peppol] summary: Upload a PDF and create a conversion queue description: Provide exactly one PDF source. Save queue_guid for the following calls. requestBody: required: true content: multipart/form-data: schema: type: object required: [supplier_id, pdf_file] properties: supplier_id: {$ref: '#/components/schemas/ApiKey'} pdf_file: {type: string, format: binary} document_type_code: {type: string, enum: ['380', '381'], default: '380'} network: {$ref: '#/components/schemas/Network'} application/json: schema: type: object required: [supplier_id] properties: supplier_id: {$ref: '#/components/schemas/ApiKey'} pdf_base64: {type: string, description: Base64 PDF source} pdf_url: {type: string, format: uri, description: HTTPS or HTTP PDF source} filename: {type: string} document_type_code: {type: string, enum: ['380', '381'], default: '380'} network: {$ref: '#/components/schemas/Network'} responses: '200': {$ref: '#/components/responses/PdfQueue'} '400': {$ref: '#/components/responses/BadRequest'} '401': {$ref: '#/components/responses/Unauthorized'} /pdf2peppol/check/: get: tags: [PDF2Peppol] summary: Read extraction results and Peppol readiness parameters: - {$ref: '#/components/parameters/SupplierId'} - {$ref: '#/components/parameters/QueueGuid'} responses: '200': description: Extracted data and readiness state content: application/json: schema: {$ref: '#/components/schemas/PdfCheck'} '400': {$ref: '#/components/responses/BadRequest'} '401': {$ref: '#/components/responses/Unauthorized'} /pdf2peppol/confirm/: post: tags: [PDF2Peppol] summary: Confirm verified conversion data requestBody: {$ref: '#/components/requestBodies/SupplierQueue'} responses: '200': {$ref: '#/components/responses/PdfConfirmed'} '400': {$ref: '#/components/responses/BadRequest'} '401': {$ref: '#/components/responses/Unauthorized'} /pdf2peppol/send/: post: tags: [PDF2Peppol] summary: Send a confirmed PDF document through Peppol requestBody: {$ref: '#/components/requestBodies/SupplierQueue'} responses: '200': {$ref: '#/components/responses/PdfSent'} '400': {$ref: '#/components/responses/BadRequest'} '401': {$ref: '#/components/responses/Unauthorized'} /invoice/add/: post: tags: [Structured invoices] summary: Create a structured sales invoice header requestBody: required: true content: application/json: schema: {$ref: '#/components/schemas/InvoiceHeader'} application/x-www-form-urlencoded: schema: {$ref: '#/components/schemas/InvoiceHeader'} responses: '200': {$ref: '#/components/responses/DraftDocument'} '400': {$ref: '#/components/responses/BadRequest'} '401': {$ref: '#/components/responses/Unauthorized'} /invoice_line/add/: post: tags: [Structured invoices] summary: Add one sales invoice line requestBody: required: true content: application/json: {schema: {$ref: '#/components/schemas/InvoiceLine'}} application/x-www-form-urlencoded: {schema: {$ref: '#/components/schemas/InvoiceLine'}} responses: '200': {$ref: '#/components/responses/LineCreated'} '400': {$ref: '#/components/responses/BadRequest'} '401': {$ref: '#/components/responses/Unauthorized'} /invoice_attach_pdf/add/: post: tags: [Structured invoices] summary: Attach or replace an invoice PDF requestBody: {$ref: '#/components/requestBodies/InvoicePdf'} responses: '200': {$ref: '#/components/responses/Attachment'} '400': {$ref: '#/components/responses/BadRequest'} '401': {$ref: '#/components/responses/Unauthorized'} /creditnote/add/: post: tags: [Structured credit notes] summary: Create a structured credit note header requestBody: required: true content: application/json: {schema: {$ref: '#/components/schemas/CreditNoteHeader'}} application/x-www-form-urlencoded: {schema: {$ref: '#/components/schemas/CreditNoteHeader'}} responses: '200': {$ref: '#/components/responses/DraftDocument'} '400': {$ref: '#/components/responses/BadRequest'} '401': {$ref: '#/components/responses/Unauthorized'} /creditnote_line/add/: post: tags: [Structured credit notes] summary: Add one credit note line requestBody: required: true content: application/json: {schema: {$ref: '#/components/schemas/CreditNoteLine'}} application/x-www-form-urlencoded: {schema: {$ref: '#/components/schemas/CreditNoteLine'}} responses: '200': {$ref: '#/components/responses/LineCreated'} '400': {$ref: '#/components/responses/BadRequest'} '401': {$ref: '#/components/responses/Unauthorized'} /creditnote_attach_pdf/add/: post: tags: [Structured credit notes] summary: Attach or replace a credit note PDF requestBody: {$ref: '#/components/requestBodies/CreditNotePdf'} responses: '200': {$ref: '#/components/responses/Attachment'} '400': {$ref: '#/components/responses/BadRequest'} '401': {$ref: '#/components/responses/Unauthorized'} /xml/generate/: post: tags: [Structured invoices, Structured credit notes] summary: Generate UBL XML and submit a structured document to Peppol description: | Send invoice_guid for an invoice (type 380), or creditnote_guid for a credit note (type 381). This is the final structured-flow call: when the XML is valid, Peppox continues the configured Peppol submission. There is no separate structured /send endpoint. requestBody: required: true content: application/json: {schema: {$ref: '#/components/schemas/XmlGenerate'}} application/x-www-form-urlencoded: {schema: {$ref: '#/components/schemas/XmlGenerate'}} responses: '200': {$ref: '#/components/responses/XmlBuilt'} '400': {$ref: '#/components/responses/BadRequest'} '401': {$ref: '#/components/responses/Unauthorized'} /invoice/list/: get: tags: [Structured invoices] summary: List stored structured invoice records parameters: - {$ref: '#/components/parameters/ApiKey'} - {name: profile, in: query, schema: {type: string, enum: [mini, customer, full]}} - {name: invoice_guid, in: query, schema: {type: string}} - {name: inv_id, in: query, schema: {type: string}} - {name: status, in: query, schema: {type: string}} - {name: network, in: query, schema: {$ref: '#/components/schemas/Network'}} - {name: from, in: query, schema: {type: string, format: date}} - {name: to, in: query, schema: {type: string, format: date}} - {$ref: '#/components/parameters/Limit'} - {name: offset, in: query, schema: {type: integer, minimum: 0, default: 0}} responses: '200': {$ref: '#/components/responses/DocumentList'} '401': {$ref: '#/components/responses/Unauthorized'} /doc-sent/header/list/: get: tags: [Sent documents] summary: List sent document headers parameters: - {$ref: '#/components/parameters/SupplierId'} - {$ref: '#/components/parameters/PaginationPage'} - {$ref: '#/components/parameters/PerPage'} - {$ref: '#/components/parameters/Search'} - {$ref: '#/components/parameters/DateFrom'} - {$ref: '#/components/parameters/DateTo'} - {name: status, in: query, description: One status or CSV list, schema: {type: string}} - {name: local_status, in: query, description: One status or CSV list, schema: {type: string}} - {name: date_field, in: query, schema: {type: string, default: sent_at}} - {name: sort_by, in: query, schema: {type: string, default: sent_at}} - {name: sort_dir, in: query, schema: {type: string, enum: [ASC, DESC], default: DESC}} responses: '200': {$ref: '#/components/responses/DocumentList'} '401': {$ref: '#/components/responses/Unauthorized'} /doc-sent/lines/list/: get: tags: [Sent documents] summary: List lines of one sent document parameters: - {$ref: '#/components/parameters/SupplierId'} - {name: invoice_guid, in: query, required: true, schema: {type: string}} - {$ref: '#/components/parameters/PaginationPage'} - {$ref: '#/components/parameters/PerPage'} - {$ref: '#/components/parameters/Search'} responses: '200': {$ref: '#/components/responses/DocumentList'} '401': {$ref: '#/components/responses/Unauthorized'} /doc-received/header/list/: get: tags: [Received documents] summary: List received document headers parameters: - {$ref: '#/components/parameters/SupplierId'} - {$ref: '#/components/parameters/PaginationPage'} - {$ref: '#/components/parameters/PerPage'} - {$ref: '#/components/parameters/Search'} - {$ref: '#/components/parameters/DateFrom'} - {$ref: '#/components/parameters/DateTo'} - {name: status, in: query, description: One status or CSV list, schema: {type: string}} - {name: document_type_code, in: query, schema: {type: string, example: '380'}} - {name: date_field, in: query, schema: {type: string, default: api_created_at}} - {name: sort_by, in: query, schema: {type: string, default: api_created_at}} - {name: sort_dir, in: query, schema: {type: string, enum: [ASC, DESC], default: DESC}} responses: '200': {$ref: '#/components/responses/DocumentList'} '401': {$ref: '#/components/responses/Unauthorized'} /doc-received/lines/list/: get: tags: [Received documents] summary: List lines of one received document parameters: - {$ref: '#/components/parameters/SupplierId'} - {name: document_id, in: query, required: true, schema: {type: string}} - {$ref: '#/components/parameters/PaginationPage'} - {$ref: '#/components/parameters/PerPage'} - {$ref: '#/components/parameters/Search'} responses: '200': {$ref: '#/components/responses/DocumentList'} '401': {$ref: '#/components/responses/Unauthorized'} /box/pdf/: get: tags: [Received documents] summary: Download the PDF linked to a received document parameters: - {name: documentId, in: query, required: true, schema: {type: string}} - {name: idsupplier, in: query, required: true, schema: {$ref: '#/components/schemas/ApiKey'}} - {name: type_flowin, in: query, schema: {type: string, example: reel}} responses: '200': {description: PDF document, content: {application/pdf: {schema: {type: string, format: binary}}}} '404': {description: No supplier-provided PDF is available} /ap/get/: get: tags: [Peppol discovery] summary: Check a Peppol participant and endpoint information security: [] parameters: - {name: scheme, in: query, required: true, schema: {type: string, example: '0208'}} - {name: value, in: query, required: true, schema: {type: string, example: '0123456789'}} - {name: sml, in: query, schema: {type: string, enum: [digitprod, digittest], default: digitprod}} - {name: withEndpoints, in: query, schema: {type: boolean, default: true}} - {name: pretty, in: query, schema: {type: boolean, default: false}} responses: '200': {description: Participant discovery result} components: securitySchemes: ApiKeyQuery: type: apiKey in: query name: apikey description: Use apikey or api_key for structured endpoints. PDF and document APIs use supplier_id. parameters: ApiKey: {name: apikey, in: query, required: true, schema: {$ref: '#/components/schemas/ApiKey'}} SupplierId: {name: supplier_id, in: query, required: true, schema: {$ref: '#/components/schemas/ApiKey'}} QueueGuid: {name: queue_guid, in: query, required: true, schema: {type: string}} PaginationPage: {name: page, in: query, schema: {type: integer, minimum: 1, default: 1}} PerPage: {name: per_page, in: query, schema: {type: integer, minimum: 1, maximum: 300, default: 50}} Search: {name: q, in: query, schema: {type: string}} DateFrom: {name: date_from, in: query, schema: {type: string, format: date}} DateTo: {name: date_to, in: query, schema: {type: string, format: date}} Limit: {name: limit, in: query, schema: {type: integer, minimum: 1, maximum: 500, default: 100}} requestBodies: SupplierQueue: required: true content: application/x-www-form-urlencoded: schema: type: object required: [supplier_id, queue_guid] properties: supplier_id: {$ref: '#/components/schemas/ApiKey'} queue_guid: {type: string} application/json: schema: type: object required: [supplier_id, queue_guid] properties: supplier_id: {$ref: '#/components/schemas/ApiKey'} queue_guid: {type: string} InvoicePdf: required: true content: multipart/form-data: schema: type: object required: [apikey, invoice_guid, file] properties: apikey: {$ref: '#/components/schemas/ApiKey'} invoice_guid: {type: string} file: {type: string, format: binary} CreditNotePdf: required: true content: multipart/form-data: schema: type: object required: [apikey, creditnote_guid, file] properties: apikey: {$ref: '#/components/schemas/ApiKey'} creditnote_guid: {type: string} file: {type: string, format: binary} schemas: ApiKey: {type: string, example: YOUR_API_KEY} Network: {type: string, enum: [production, integration], default: production} Customer: type: object required: [endpoint_id, name, street, city, postal, country] properties: endpoint_scheme: {type: string, default: '0208'} endpoint_id: {type: string} name: {type: string} street: {type: string} city: {type: string} postal: {type: string} country: {type: string, minLength: 2, maxLength: 2, example: BE} InvoiceHeader: type: object required: [apikey, inv_id, issue_date, customer] properties: apikey: {$ref: '#/components/schemas/ApiKey'} inv_id: {type: string, example: INV-2026-0042} issue_date: {type: string, format: date} due_date: {type: string, format: date} invoice_type_code: {type: string, default: '380'} currency: {type: string, default: EUR} customer: {$ref: '#/components/schemas/Customer'} payment: {type: object, additionalProperties: true} delivery: {type: object, additionalProperties: true} network: {$ref: '#/components/schemas/Network'} CreditNoteHeader: allOf: - {$ref: '#/components/schemas/InvoiceHeader'} - type: object required: [creditnote_id] properties: creditnote_id: {type: string, example: CN-2026-001} invoice_type_code: {type: string, default: '381'} InvoiceLine: type: object required: [apikey, invoice_guid, quantity, unit_code, price_amount, item_name, item_description, tax_percent] properties: apikey: {$ref: '#/components/schemas/ApiKey'} invoice_guid: {type: string} line_id: {type: string} quantity: {type: number, example: 2} unit_code: {type: string, example: C62} price_amount: {type: number, example: 49.50} item_name: {type: string} item_description: {type: string} tax_percent: {type: number, example: 21} CreditNoteLine: allOf: - {$ref: '#/components/schemas/InvoiceLine'} - type: object required: [creditnote_guid] properties: creditnote_guid: {type: string} XmlGenerate: type: object required: [apikey] properties: apikey: {$ref: '#/components/schemas/ApiKey'} invoice_guid: {type: string, description: Required for invoice type 380} creditnote_guid: {type: string, description: Required for credit note type 381} network: {$ref: '#/components/schemas/Network'} PdfQueue: type: object properties: success: {type: boolean, example: true} queue_guid: {type: string} status: {type: string, example: pending} document_type_code: {type: string, example: '380'} network: {$ref: '#/components/schemas/Network'} PdfCheck: type: object properties: success: {type: boolean} queue: {type: object, additionalProperties: true} peppol_readiness: {type: object, additionalProperties: true} converted_data: {type: object, additionalProperties: true} Error: type: object properties: ok: {type: boolean, example: false} success: {type: boolean, example: false} error: {type: string} responses: BadRequest: {description: Missing, invalid or incomplete input} Unauthorized: {description: Missing or invalid account API key} PdfQueue: description: PDF conversion queue created content: {application/json: {schema: {$ref: '#/components/schemas/PdfQueue'}}} PdfConfirmed: {description: Converted data confirmed} PdfSent: {description: Confirmed document sent or accepted for dispatch} DraftDocument: {description: Structured document draft created} LineCreated: {description: Structured document line created} Attachment: {description: PDF attachment saved} XmlBuilt: {description: UBL XML built and configured Peppol submission continued} DocumentList: {description: Paginated document or line list} security: - ApiKeyQuery: []