AP
Developer Portal
APEX AP Service — REST API & SAPI Documentation
Integration guide REST API SAPI Swagger / OpenAPI OAuth 2.0
🇸🇰 SK 🇨🇿 CS 🇬🇧 EN
Peppol Access Point • REST API • SAPI-SK v1.0

APEX AP Developer Portal — complete documentation of API and SAPI endpoints. Developer Portal — kompletná dokumentácia API a SAPI endpointov.

Technical reference for all 25+ endpoints implemented in APEX AP Service. Covers APEX API for deep integration, SAPI for simplified access per SAPI-SK v1.0, authentication, validation, sending, inbox, webhooks, reporting and participant lookup.

Quickstart API Reference Authentication
APEX API
Documents, Inbox, Events
Full REST API for sending, receiving, validating and tracking documents.
SAPI
Simplified interface
Synchronous sending, receiving and authentication per the SAPI-SK specification.
Participants
Lookup by VAT / Company ID
Participant lookup by VAT ID or Company ID via SMP/SML.
Webhooky & Reporting
Notifications & EUSR/TSR
Webhook subscriptions, AMQP queue and reporting statistics.
Portal navigation
Documentation structure
Quickstart — 4 steps to your first integration→ REST API Reference — all endpoints→ Authentication — OAuth 2.0, JWT→ Examples — request/response JSON→ Swagger→
All endpoints are implemented and available. Documentation reflects the current state of source code and Swagger annotations.
Integration paths

Two ways to connect to APEX

The APEX Access Point offers two equivalent integration paths. Your choice depends on where your system runs and which communication style you need. Both paths cover the full Peppol flow (sending and receiving) and you can combine them.

A
Path A — direct REST integration

APEX REST API (SAPI)

REST OAuth 2.0 JSON UBL 2.1 Webhooks
👤 Who it is for
Developers of ERP, accounting, e-commerce and portal systems who want to build their own client and keep full control over the flow.
⚙️ How it works
HTTPS calls to apex.asseco-peppol.com with an OAuth 2.0 token. JSON payload, UBL XML Base64-encoded. Synchronous request/response + status polling or webhooks.
✅ Why choose this path
  • No additional infrastructure — an HTTPS client is enough
  • Full control over retry logic, timeouts and error handling
  • On-demand synchronous sending (e.g. triggered from a UI action)
  • Easy testing via Postman / curl / Swagger UI
Open API Reference →
B
Path B — managed messaging

QHUB (RabbitMQ message bus)

AMQPS RabbitMQ async DLQ Audit
👤 Who it is for
Systems running in the ASOL Cloud and external ERPs that already use a messaging layer (Java/Spring AMQP, .NET MassTransit, pika). Ideal for enterprise operations and automated batch flows.
⚙️ How it works
AMQPS connection to RabbitMQ in the ASOL Cloud. You send a SynchronizationMessage carrying a PeppolDocument entity, QHUB delivers it to APEX and any responses are returned to your queue.
✅ Why choose this path
  • Retry + Dead-Letter Queue out-of-the-box during transient outages
  • Automatic audit trail of every message in a transaction table
  • Asynchronous flow — your system does not need to be online 24/7
  • Unified credential management across multiple ASOL products
Open Integration Guide →
💡
Tip: You can combine both paths. For example: send via the REST API (synchronous, from a UI action) and receive via QHUB (asynchronous, with reliable retry).
Overview

Who is this documentation for

ERP Integrator
Needs to know how to authenticate, validate a document, send it and track its delivery status. Primarily uses APEX API.
Key sections: Quickstart, Document Management, Participants, Status & Events.
Backend Developer
Interested in the OAuth 2.0 flow, retry strategy, webhook integration, AMQP queue access and operation idempotency.
Key sections: Authentication, Webhooks, SAPI, Rate limiting.
Support / Operations
Needs to quickly check document status, read events, monitor reporting submissions and troubleshoot issues.
Key sections: Events, Responses, Reporting, Inbox.

Quickstart

4 steps to your first integration

01
Authentication
Call POST /sapi/v1/auth/token with client_credentials. You receive a JWT access token (15 min) and a refresh token (30 days). Use the token in the Authorization: Bearer <token> header. s client_credentials. Získate JWT access token (15 min) a refresh token (30 dní). Token používajte v hlavičke Authorization: Bearer <token>.
Result: authorized access to all API endpoints.
02
Validate / Precheck
Before sending, call POST /api/v1/documents/validate or /precheck. Validate checks XML, Schematron and business rules. Precheck additionally verifies participant existence and routability. alebo /precheck. Validate overí XML, Schematron a business rules. Precheck navyše overí existenciu participanta a routovateľnosť.
Result: fewer runtime errors and fewer support incidents.
03
Send document
Call POST /api/v1/documents/send. The API returns HTTP 202 with status QUEUED. The document is processed asynchronously — QUEUED does not mean final delivery.. API vráti HTTP 202 so statusom QUEUED. Dokument sa spracuje asynchrónne — QUEUED neznamená finálne doručenie.
Result: document queued in the processing pipeline.
04
Track status & responses
Poll GET /api/v1/documents/{id}/status for the current status. Use /events for the timeline and /responses for counterparty responses (MLR, IMR). pre aktuálny stav. Použite /events pre časovú os a /responses pre odpovede protistrany (MLR, IMR).
Result: complete visibility into document delivery.

Reference

REST API Reference

POST Existing core

/api/v1/documents/send

Queues a business document into the asynchronous send pipeline. Returns HTTP 202 with status QUEUED.
Purpose
Accepts a UBL document and queues it for asynchronous processing. An HTTP 202 response with QUEUED status means the document was accepted for processing, not that it was delivered. Lifecycle: QUEUED → PROCESSING → DELIVERED / RETRYING → DEAD_LETTER.
When to call
  • after a successful precheck or validation
  • for automated batch sending
  • on explicit user request to send an invoice
Async behavior
The document goes through states: QUEUED → PROCESSING → DELIVERED or RETRYING → DEAD_LETTER. Retry uses exponential backoff, up to 5 attempts. Track status via the /status endpoint. endpoint.
Typical errors
  • 400 — missing required field or invalid payload — chýbajúci povinny udaj alebo nevalidný payload
  • 401 — invalid or expired token — neplatný alebo expirovaný token
  • 422 — invalid UBL document — nevalidný UBL dokument
Input fields
Name
Description
Status
senderParticipantId
Peppol ID of the sender
required
receiverParticipantId
Peppol ID of the recipient
required
documentTypeId
Peppol document type
required
processId
Peppol process ID
required
ublDocument
UBL XML document in Base64 encoding
required
Output fields
Name
Description
documentId
UUID identifier of the sent document
status
Initial status — QUEUED
submittedAt
Request reception time (ISO 8601)
GET Existing core

/api/v1/documents/{documentId}/status

Retrieves the current delivery status of a sent document. Use for polling.
Purpose
Simple endpoint for retrieving the current status of a document. Possible values: QUEUED, PROCESSING, DELIVERED, RETRYING, FAILED, DEAD_LETTER.
When to call
  • in polling mode after sending a document
  • in a document list to display status
  • when deciding whether an error needs to be handled
Status values
QUEUED — waiting for processing
PROCESSING — AS4 sending in progress
DELIVERED — successfully delivered
RETRYING — temporary error, retrying
FAILED — permanent failure
DEAD_LETTER — moved to DLQ after all retries exhausted — čaká na spracovanie
PROCESSING — prebieha AS4 odosielanie
DELIVERED — úspešne doručený
RETRYING — dočasná chyba, opakovaný pokus
FAILED — trvale zlyhanie
DEAD_LETTER — presunuté do DLQ po vyerpani pokusov
Typical errors
  • 404 — document does not exist — dokument neexistuje
  • 401 — invalid token — neplatný token
Parameters
Name
Description
Status
documentId
Document UUID (path parameter)
required
Output fields
Name
Description
documentId
Document UUID identifier
status
Current delivery status
submittedAt
Original submission time
POST Existing core

/api/v1/documents/validate

Validates a UBL document without sending. Three layers: XML Schema, EN 16931 Schematron, Peppol BIS 3.0 rules.
Purpose
Validates the syntactic and rule correctness of a UBL document before sending it to the Peppol network. Supports Invoice and Credit Note. Three validation layers: XML Schema → EN 16931 Schematron → Peppol BIS 3.0 business rules.
When to call
  • when generating an invoice before submission
  • when testing integration and debugging XML templates
  • when validating batch imports or migrations
Validation layers
1. XML Schema — formal structure validation
2. EN 16931 Schematron — European e-invoicing standard
3. Peppol BIS 3.0 — Peppol-specific business rules — formálna validácia štruktúry
2. EN 16931 Schematron — európska norma pre e-invoicing
3. Peppol BIS 3.0 — Peppol-špecifické business pravidlá
Typical errors
  • 400 — invalid XML or incorrect payload — nevalidné XML alebo nesprávny payload
  • 422 — validation rule violation — porušenie validačných pravidiel
Input fields
Name
Description
Status
ublDocument
UBL XML document (string)
required
documentTypeId
Peppol document type
optional
Output fields
Name
Description
valid
Overall validation result (boolean)
schemaValid
XSD validation result
schematronValid
EN 16931 validation result
businessRulesValid
Peppol BIS 3.0 rules result
errors[]
Array of errors with details
warnings[]
Array of warnings
documentType
Recognized document type
documentId
ID from the document
issueDate
Issue date
supplierName
Supplier name
customerName
Customer name
totalAmount
Total amount
currencyCode
Currency code
POST Existing core

/api/v1/documents/precheck

Combined check of document validity, participant existence and routability before sending. Three checks in one call.
Purpose
Combines three checks: 1) document validation, 2) participant existence verification via SMP/SML, 3) routability verification (doctype support). Result networkReady = valid AND participantExists AND canSend. = valid AND participantExists AND canSend.
When to call
  • immediately before sending a document to the Peppol network
  • when implementing a "Send" business button
  • during bulk sending to filter out problematic documents
Error categories
VALIDATION — errors in the UBL document
PARTICIPANT — recipient does not exist in SMP/SML
ROUTING — recipient does not support the given doctype/process

Warning: CERT_EXPIRING_SOON — recipient certificate expiring soon — chyby v UBL dokumente
PARTICIPANT — prijemca neexistuje v SMP/SML
ROUTING — prijemca nepodporuje daný doctype/proces

Varovanie: CERT_EXPIRING_SOON — certifikát príjemcu čoskoro vyprší
Typical errors
  • 400 — missing required field — chýbajúci povinny udaj
  • 422 — validation errors in the document — validačné chyby v dokumente
  • 404 — participant not found in SMP/SML — participant nenájdený v SMP/SML
Input fields
Name
Description
Status
senderParticipantId
Peppol ID of the sender
required
receiverParticipantId
Peppol ID of the recipient
required
documentTypeId
Peppol document type
required
processId
Peppol process ID
required
ublDocument
UBL XML document (Base64)
required
Output fields
Name
Description
networkReady
Whether the document is ready to send (valid AND participantExists AND canSend)
valid
Overall validation result
participantExists
Whether the recipient exists in SMP/SML
canSend
Whether the recipient supports the given document type
errors[]
Array of errors with category (VALIDATION/PARTICIPANT/ROUTING)
warnings[]
Array of warnings (e.g. CERT_EXPIRING_SOON)
checkedAt
Time of checks
GET Existing inbound

/api/v1/documents/inbox

List of received documents. Paginated (offset/limit), sorted by receivedAt DESC.
Purpose
The inbox serves as the integration surface for clients who want to read received documents in pull mode. Supports filtering by status: RECEIVED, VALIDATED, DELIVERED, FAILED, REJECTED.
When to call
  • when integrating received invoices into the ERP
  • when the client prefers polling over webhooks
  • when looking up a specific inbound document
Pagination
Uses offset/limit model. Default limit is 20, maximum 100. Response contains total for the overall record count. pre celkový počet záznamov.
Typical errors
  • 400 — invalid filter or parameter — neplatný filter alebo parameter
  • 401 — invalid token — neplatný token
Query parameters
Name
Description
Status
status
Filter by status (RECEIVED, VALIDATED, DELIVERED, FAILED, REJECTED)
optional
offset
Pagination offset (default 0)
optional
limit
Number of records (default 20, max 100)
optional
Output fields
Name
Description
items[]
Array of received documents
total
Total record count
offset
Current offset
limit
Current limit
GET Existing inbound

/api/v1/documents/inbox/{documentId}

Detail of a received document including the complete UBL XML payload.
Purpose
Returns the complete received document including all metadata and UBL XML payload for processing in the ERP system.
When to call
  • when downloading a specific document to the ERP
  • when displaying invoice details
Output fields
documentId, senderParticipantId, receiverParticipantId, documentTypeId, processId, receivedAt, status, ublDocument (XML payload), senderParticipantId, receiverParticipantId, documentTypeId, processId, receivedAt, status, ublDocument (XML payload)
Typical errors
  • 404 — document does not exist — dokument neexistuje
  • 401 — invalid token — neplatný token
POST Existing inbound

/api/v1/documents/inbox/{documentId}/acknowledged

Acknowledges receipt of a document. Sets status to DELIVERED. Idempotent operation, returns 204 No Content.
Purpose
After processing a received document in the ERP system, call this endpoint to acknowledge receipt. The document transitions to DELIVERED status. The operation is idempotent — repeated calls have no side effect.
When to call
  • after successfully processing the document in the ERP
  • after importing an invoice into the accounting system
Response
HTTP 204 No Content — successful acknowledgement. No response body.
Typical errors
  • 404 — document does not exist — dokument neexistuje
  • 409 — document already acknowledged (conflict) — dokument už bol potvrdený (conflict)
GET Existing ops

/api/v1/documents/{documentId}/events

Complete chronological list of events for both sent and received documents.
Purpose
Returns all document events in chronological order. Event categories: Lifecycle, Validation, SMP lookup, AS4 transport, Storage, Retry/queue, TDD/C5. Each event contains technical details and a timestamp.
When to call
  • when disputing delivery — timeline of what happened
  • for detailed analysis of document behaviour
  • when exporting an audit trail
Event categories
Lifecycle — document status changes
Validation — validation results
SMP lookup — participant resolution
AS4 transport — Peppol sending
Storage — document storage
Retry/queue — retry attempts and DLQ
TDD/C5 — testing framework — zmeny stavu dokumentu
Validation — výsledky validácie
SMP lookup — dohľadanie participanta
AS4 transport — odosielanie cez Peppol
Storage — uloženie dokumentu
Retry/queue — retry pokusy a DLQ
TDD/C5 — testovaci framework
Typical errors
  • 404 — document does not exist — dokument neexistuje
Parameters
Name
Description
Status
documentId
Document UUID (path parameter)
required
Output fields (each event)
Name
Description
id
Unique event identifier
messageId
Message ID in the AS4 context
eventType
Event type (category)
eventCode
Event code
eventMessage
Human-readable event description
technicalDetails
Technical details
stacktrace
Stack trace on error
createdAt
Event creation time
GET Existing ops

/api/v1/documents/{documentId}/responses

Odpovede na aplikačnej úrovni prijaté od protistrany (MLR, IMR, ORDER_RESPONSE, RECEIPT_ADVICE).
Purpose
Returns a list of responses received for a sent document. Response types: MLR (Message Level Response), IMR (Invoice Message Response), ORDER_RESPONSE, RECEIPT_ADVICE.
Response codes
AP — Accepted
RE — Rejected
CA — Conditionally Accepted
UQ — Under Query
IP — In Process — Accepted (akceptovane)
RE — Rejected (zamietnuté)
CA — Conditionally Accepted
UQ — Under Query (v riešení)
IP — In Process (spracováva sa)
When to call
  • when disputing delivery — checking whether a response arrived
  • for auditing and proving document exchange
  • when resolving a delivery dispute
Typical errors
  • 404 — document does not exist or has no responses — dokument neexistuje alebo nemá odpovede
Parameters
Name
Description
Status
documentId
Document UUID (path parameter)
required
Output fields (each response)
Name
Description
responseId
Unique response identifier
responseType
Response type (MLR/IMR/ORDER_RESPONSE/RECEIPT_ADVICE)
responseCode
Response code (AP/RE/CA/UQ/IP)
summary
Response summary
respondedAt
Response receipt time
issues[]
Array of issues from the response
GET Existing participants

/api/v1/participants/lookup/dic

Vyhľadanie participanta podľa DIC (VAT number). Rozlíšenie: lokálna DB → SMP/SML pri cache miss → 404 ak nenájdený.
Purpose
Looks up a Peppol participant by VAT ID. First searches the local DB; on cache miss, queries SMP/SML. Schema values: 9950 (SK), 9910 (AT), 9919 (DE), 9955 (CZ).
When to call
  • in an onboarding form or when selecting a business partner
  • before a capability check in the precheck flow
  • for automatic partner auto-fill in the ERP
Resolution logic
1. Local database (cache)
2. SMP/SML lookup on cache miss
3. HTTP 404 if participant does not exist
Response includes source field (LOCAL or SMP) indicating where the data came from. Lokálna databáza (cache)
2. SMP/SML lookup pri cache miss
3. HTTP 404 ak participant neexistuje

Odpoveď obsahuje source pole: LOCAL alebo SMP.
Typical errors
  • 400 — missing parameter schema or dic — chýbajúci parameter schema alebo dic
  • 404 — participant does not exist — participant neexistuje
  • 503 — SMP/SML temporarily unavailable — SMP/SML dočasné nedostupný
Query parameters
Name
Description
Status
schema
Identifier schema (e.g. 9950 for SK)
required
dic
VAT ID value (e.g. 2024000001)
required
Output fields
Name
Description
source
Data source — LOCAL or SMP
participantId
Internal participant ID
peppolId
Peppol Participant ID
organizationName
Organization name
countryCode
Country code (SK, AT, DE, CZ)
endpointUrl
AS4 endpoint URL
smpUrl
SMP record URL
enabled
Whether the participant is active
certificate
Certificate object: subject, issuer, serial, fingerprint, notBefore, notAfter, expired
smpMetadataUpdatedAt
Last SMP metadata update
GET Existing participants

/api/v1/participants/lookup/ico

Vyhľadanie participanta podľa ICO (číslo v obchodnom registri). Rezolvuje ICO → DIC → Peppol ID.
Purpose
Looks up a Peppol participant by Company ID. Resolution logic: Company ID → Commercial Register / Finstat → VAT ID → Peppol ID → local DB → SMP/SML.
When to call
  • when we only know the Company ID of the business partner
  • when integrating with an ERP that works with Company IDs
  • for automatic Peppol identity auto-fill
Resolution logic
Company ID (6-8 digits) → lookup in Commercial Register / Finstat → obtain VAT ID → resolve Peppol ID → local DB → SMP/SML lookup.
Typical errors
  • 400 — invalid Company ID format — neplatný format ICO
  • 422 — Company ID could not be resolved to a VAT ID — ICO sa nepodarilo preložiť na DIC
  • 404 — participant does not exist — participant neexistuje
Query parameters
Name
Description
Status
ico
Company ID (6-8 digits)
required
schema
Identifier schema (default 9950)
optional
Output fields
Name
Description
source
Data source — LOCAL or SMP
participantId
Internal participant ID
peppolId
Peppol Participant ID
organizationName
Organization name
countryCode
Country code
endpointUrl
AS4 endpoint URL
certificate
Participant certificate
GET Existing reporting

/api/v1/reporting/statistics

Aggregated document statistics for a selected period. Sent, received, delivery rate, top recipients and senders.
Purpose
Provides an aggregated overview of document traffic. Period: month, quarter, year or custom (from/to). Includes statistics for sent and received documents, delivery rate and top lists.
When to call
  • when generating an operations dashboard
  • for regular management reporting
  • when analysing trends and delivery success rates
Output structure
period — period type and range
sent — total, delivered, failed, deliveryRate, byDocumentType, byCountry
received — same structure
topRecipients[], topSenders[] — top partners
failedDocuments — total, deadLetters, retrying, rejected — typ a rozsah obdobia
sent — total, delivered, failed, deliveryRate, byDocumentType, byCountry
received — rovnaka štruktúra
topRecipients[], topSenders[] — zoznamy top partnerov
failedDocuments — total, deadLetters, retrying, rejected
Typical errors
  • 400 — invalid period or date format — neplatne obdobie alebo format datumu
Query parameters
Name
Description
Status
period
Period type: month, quarter, year
optional
from
Custom period start (ISO 8601)
optional
to
Custom period end (ISO 8601)
optional
Output fields
Name
Description
period
Object with type, from, to
sent
Sent documents statistics
received
Received documents statistics
deliveryRate
Overall delivery rate (%)
topRecipients[]
Top recipients
topSenders[]
Top senders
failedDocuments
Failed documents overview
GET Existing reporting

/api/v1/reporting/submissions

History of submitted EUSR/TSR reports to OpenPeppol. Filter by report type and status.
Purpose
Returns a list of generated and submitted compliance reports (EUSR — End User Statistics Report, TSR — Transaction Statistics Report). Allows tracking the status of each report.
When to call
  • during regular reporting compliance checks
  • when troubleshooting a failed submission
  • when exporting or validating a submitted report
Status values
PENDING — awaiting submission
SUBMITTED — successfully submitted
FAILED — submission failed
VALIDATED — report was validated — čaká na odoslanie
SUBMITTED — úspešne odoslaný
FAILED — odoslanie zlyhalo
VALIDATED — report bol validovany
Typical errors
  • 400 — invalid filter — neplatný filter
Query parameters
Name
Description
Status
reportType
Report type: EUSR or TSR
optional
status
Filter: PENDING, SUBMITTED, FAILED, VALIDATED
optional
offset
Pagination offset
optional
limit
Number of records
optional
Output fields (each item)
Name
Description
id
Report identifier
reportType
Type: EUSR or TSR
periodStart
Reporting period start
periodEnd
Reporting period end
reporterId
Reporter ID (AP)
status
Report status
errorMessage
Error message on failure
submittedAt
Submission time
validatedAt
Validation time
createdAt
Record creation time
POST Existing webhooky

/api/v1/subscriptions

Creates a webhook subscription. Registers an HTTPS endpoint for document receive notifications.
Purpose
Registers an HTTPS endpoint to receive notifications about incoming documents. Notification payload contains: eventType, subscriptionId, receivedCount, documentIds[], notifiedAt. Timeouts: connection 2s, response 2s.
When to call
  • when setting up event-driven integration
  • in inbound scenarios with immediate processing
  • as an alternative to polling via the inbox endpoint
Filters
Webhook can be filtered by document type (documentTypeFilters[]) and sender (senderParticipantFilters[]). Without a filter, notifications are sent for all received documents.) a odosielateľa (senderParticipantFilters[]). Bez filtra sa notifikuje o všetkých prijatých dokumentoch.
Typical errors
  • 400 — invalid URL (must be https://) — neplatná URL (musí byt https://)
  • 422 — invalid filter — nevalidný filter
Input fields
Name
Description
Status
name
Subscription name
required
description
Description
optional
url
HTTPS callback URL
required
active
Whether the subscription is active
optional
documentTypeFilters
Array of document type filters
optional
senderParticipantFilters
Array of sender filters
optional
Output fields
Name
Description
subscriptionId
Subscription UUID
name
Name
url
Callback URL
active
Whether active
documentTypeFilters
Configured filters
senderParticipantFilters
Configured filters
createdAt
Creation time
updatedAt
Last update time
GET Existing webhooky

/api/v1/subscriptions

List of all webhook subscriptions. Paginated overview.
Purpose
Returns a paginated list of all registered webhook subscriptions for the given account.
When to call
  • when displaying the webhook management screen
  • when auditing notification settings
Typical errors
  • 401 — invalid token — neplatný token
GET Existing webhooky

/api/v1/subscriptions/{subscriptionId}

Detail of a single webhook subscription.
Purpose
Returns the complete subscription detail including filters, status and timestamps.
Typical errors
  • 404 — subscription does not exist — subscription neexistuje
PUT Existing webhooky

/api/v1/subscriptions/{subscriptionId}

Updates a webhook subscription (full replace). Replaces the complete subscription object.
Purpose
Complete replacement of a subscription. Used when changing the URL, filters or status (active/inactive). Input fields are the same as for POST creation.
Typical errors
  • 404 — subscription does not exist — subscription neexistuje
  • 400 — invalid URL or filters — neplatná URL alebo filtre
DELETE Existing webhooky

/api/v1/subscriptions/{subscriptionId}

Zmazanie webhook subscription. Nevratná operácia — po zmazani sa notifikácie prestanu posielat.
Purpose
Permanently deletes a webhook subscription. The operation is irreversible. After deletion, notifications for the given endpoint stop immediately.
Typical errors
  • 404 — subscription does not exist — subscription neexistuje
POST Existing webhooky

/api/v1/subscriptions/queue

Creates AMQP queue access. One queue per account; credentials are shown only once.
Purpose
Creates access to an AMQP queue for receiving notifications via RabbitMQ instead of HTTP webhooks. One queue per account. AMQPS on port 5671, durable queue, 7-day message buffer. Credentials are shown only once!
When to call
  • when you prefer AMQP over HTTP webhooks
  • for high-throughput integration
  • when you need guaranteed message delivery
Security notice
Credentials (username, password) are shown only once in the response. Store them securely. If lost, you must create a new queue. v odpovedí. Uložte ich bezpečne. Pri strate je nutne vytvoriť novu queue.
Typical errors
  • 409 — queue already exists for this account — queue už existuje pre daný účet
Output fields
Name
Description
queueId
Queue ID
amqpUrl
AMQPS connection URL
host
Server hostname
port
Port (5671 for AMQPS)
vhost
Virtual host
username
Username (shown once only!)
password
Password (shown once only!)
queueName
Queue name
createdAt
Creation time
securityWarning
One-time credentials notice
POST Existing SAPI auth

/sapi/v1/auth/token

Získanie access a refresh tokenov. OAuth 2.0 client_credentials grant. JWT RS256.
Purpose
Client authentication using the client_credentials grant type. Returns a JWT access token (valid 15 min) and a refresh token (valid 30 days). Uses the OAuth 2.0 client credentials flow. grant type. Vráti JWT access token (platnosť 15 min) a refresh token (platnosť 30 dní). Token je podpísaný algoritmom RS256.
When to call
  • on first login to the API
  • when the access token has expired
  • during integration client initialisation
Security
After 5 failed attempts the account is locked (HTTP 423 Locked). Rate limiting: 200 req/min default. Tokens should be stored securely and reused until expiry. je účet zamknutý (HTTP 423 Locked). Rate limiting: 200 req/min default. Tokeny sa majú uchovávať bezpečne a neprenášať v URL parametroch.
Typical errors
  • 401 — invalid client_id or client_secret — neplatne client_id alebo client_secret
  • 423 — account locked after 5 failed attempts — účet zamknutý po 5 neúspešných pokusoch
  • 429 — rate limit exceeded — prekročený rate limit
Input fields
Name
Description
Status
grant_type
Value: client_credentials
required
client_id
Client identifier
required
client_secret
Client secret
required
Output fields
Name
Description
access_token
JWT access token
token_type
Token type — Bearer
expires_in
Validity in seconds (900 = 15 min)
scope
Permission scope
GET Existing SAPI auth

/sapi/v1/auth/token/status

Introspekcia aktuálneho access tokenu. Overenie platnosti a informácie o expiraci.
Purpose
Checks the validity of the current access token without calling another endpoint. Returns expiry information and a recommendation on whether to renew the token.
When to call
  • before a critical operation to check token validity
  • in the health-check logic of the integration client
Typical errors
  • 401 — token is invalid or expired — token je neplatný alebo expiroval
Output fields
Name
Description
valid
Whether the token is valid (boolean)
token_type
Token type
client_id
Client ID
issued_at
Token issue time
expires_at
Expiry time
expires_in_seconds
Seconds remaining until expiry
should_refresh
Whether it is recommended to renew the token
refresh_recommended_at
Recommended renewal time
POST Existing SAPI auth

/sapi/v1/auth/renew

Obnovenie tokenov pomocou refresh tokenu. Token rotácia — starý refresh token sa zneplatní.
Purpose
Renews the access token using the refresh token. Implements token rotation — the old refresh token is immediately invalidated and a new pair (access + refresh) is issued.
When to call
  • when the access token has expired or is about to expire
  • in the automatic token refresh cycle
Token rotation
After successful renewal the old refresh token is immediately invalid. Using the old refresh token returns a 401 error.. Použitie starého refresh tokenu vráti chybu 401.
Typical errors
  • 401 — invalid or expired refresh token — neplatný alebo expirovaný refresh token
Input fields
Name
Description
Status
refresh_token
Current refresh token
required
Output fields
Name
Description
access_token
New JWT access token
token_type
Bearer
expires_in
Validity in seconds
scope
Permission scope
POST Existing SAPI auth

/sapi/v1/auth/revoke

Zneplatnenie aktívneho tokenu. Idempotentna operácia podľa RFC 7009.
Purpose
Invalidates the active access or refresh token. The operation is idempotent per RFC 7009 — a repeated call with the same token returns success.
When to call
  • on client logout
  • during a security incident
  • during credentials rotation
Typical errors
  • 400 — missing token parameter — chýbajúci token parameter
Input fields
Name
Description
Status
token
Token to revoke
required
Output fields
Name
Description
revoked
Whether the token was revoked (boolean)
message
Result message
POST Existing SAPI core

/sapi/v1/document/send

Synchronous document send to the Peppol network. Validation + SMP lookup + AS4 delivery in a single HTTP request.
Purpose
SYNCHRONOUS endpoint that in a single HTTP call performs: document validation, SMP lookup, AS4 delivery. Unlike the APEX API /documents/send which is asynchronous, SAPI send waits for the delivery result., ktorý je asynchrónny, SAPI send čaká na výsledok doručenia.
When to call
  • when the client needs an immediate delivery response
  • for simple integrations without webhook/polling
  • for SAPI-SK v1.0 compatible integration
Required headers
Idempotency-Key — unique key for idempotent processing (required)
X-Peppol-Participant-Id — Peppol ID of sender (required)

Rate limit: 100 req/min (stricter than default 200 req/min)
Formats: UBL, CII — unikátny kľúč pre idempotentne spracovanie (povinné)
X-Peppol-Participant-Id — Peppol ID odosielateľa (povinné)

Rate limit: 100 req/min (prísnejší ako default 200 req/min)
Formáty: UBL, CII
Typical errors
  • 400 — missing Idempotency-Key or payload — chýbajúci Idempotency-Key alebo payload
  • 422 — validation errors — validačné chyby
  • 429 — rate limit exceeded (100/min) — prekročený rate limit (100/min)
  • 502 — error during AS4 delivery — chyba pri AS4 doručení
Headers & input
Name
Description
Status
Idempotency-Key
Unique key (HTTP header)
required
X-Peppol-Participant-Id
Peppol ID of sender (HTTP header)
required
payload
UBL or CII document
required
Output fields
Name
Description
provider_document_id
Document ID at provider
status
Delivery status
sent_at
Submission time
GET Existing SAPI inbound

/sapi/v1/document/receive

List of received documents with cursor-based pagination. Filter by status (RECEIVED, ACKNOWLEDGED).
Purpose
Returns a list of received documents with cursor-based pagination (pageToken + limit). Filtering by status: RECEIVED (not yet acknowledged), ACKNOWLEDGED (acknowledged).
When to call
  • for regular polling of received documents
  • in integrations using the SAPI interface
Cursor-based pagination
Uses pageToken instead of offset/limit. Response contains next_page_token for the next page. total_count gives the total number of records. namiesto offset/limit. Odpoveď obsahuje next_page_token pre ďalšiu stranu. total_count uvadza celkový počet.
Typical errors
  • 400 — invalid pageToken or filter — neplatný pageToken alebo filter
  • 401 — invalid token — neplatný token
Query parameters
Name
Description
Status
status
Filter: RECEIVED or ACKNOWLEDGED
optional
pageToken
Cursor token for next page
optional
limit
Records per page
optional
Output fields
Name
Description
documents[]
Array of received documents
next_page_token
Token for next page
total_count
Total record count
GET Existing SAPI inbound

/sapi/v1/document/receive/{documentId}

Detail of a received document including metadata, XML payload and checksum.
Purpose
Returns the complete detail of a single received document including metadata, XML payload, format and checksum for integrity verification.
When to call
  • when downloading a specific document
  • when verifying payload integrity
Typical errors
  • 404 — document does not exist — dokument neexistuje
Output fields
Name
Description
provider_document_id
Document ID at provider
status
Document status
received_at
Receipt time
metadata
Metadata object
payload
XML document content
payload_format
Payload format (UBL/CII)
checksum
Checksum for integrity verification
POST Existing SAPI inbound

/sapi/v1/document/receive/{documentId}/acknowledge

Potvrdenie prijatia dokumentu. Prechod RECEIVED → ACKNOWLEDGED. Idempotentna operácia.
Purpose
Confirms receipt of a document by the client. Status transitions from RECEIVED to ACKNOWLEDGED. The operation is idempotent — repeated calls have no side effect.
When to call
  • after successfully processing the document in the client system
  • after importing an invoice into the ERP
Typical errors
  • 404 — document does not exist — dokument neexistuje
Output fields
Name
Description
provider_document_id
Document ID
status
ACKNOWLEDGED
acknowledged_at
Acknowledgement time
Key concepts and service differences
This section explains the fundamental concepts, differences between APEX API and SAPI, status values and technical context.
APEX API (/api/v1/) is the full enterprise REST API for deep integration. Sending is asynchronous (QUEUED); events, responses, webhooks, reporting and participant lookup are available.

APEX SAPI (/sapi/v1/) is a simplified interface per SAPI-SK v1.0. Sending is synchronous, pagination is cursor-based. Suitable for simpler integrations.

Authentication is shared — tokens obtained via SAPI /auth/token are valid for both APIs. (/api/v1/) je plná enterprise REST API pre hlbokú integráciu. Odosielanie je asynchrónne (QUEUED), k dispozícii su events, responses, webhooky, reporting a participant lookup.

APEX SAPI (/sapi/v1/) je zjednodušené rozhranie podľa SAPI-SK v1.0. Odosielanie je synchrónne, stránkovanie je cursor-based. Vhodné pre jednoduchšie integrácie.

Autentifikácia je zdieľaná — tokeny ziskane cez SAPI /auth/token platia pre obe API.
Participant ID is the unique identifier in the Peppol network (format: iso6523-actorid-upis::9950:2024000001). Used for routing and SMP lookup.

VAT ID is the business identifier. Schema: 9950 (SK), 9910 (AT), 9919 (DE), 9955 (CZ).

Company ID is a 6-8 digit number from the business register. The /lookup/ico endpoint automatically resolves Company ID → VAT ID → Peppol ID. je jednoznačný identifikátor v Peppol sieti (format: iso6523-actorid-upis::9950:2024000001). Používa sa na routing a SMP lookup.

DIC (Daňové identifikačné číslo) je business identifikátor. Schema: 9950 (SK), 9910 (AT), 9919 (DE), 9955 (CZ).

ICO (Identifikačné číslo organizácie) je 6-8 miestne číslo z obchodného registra. Endpoint /lookup/ico automaticky prekladá ICO → DIC → Peppol ID.
QUEUED — document accepted for processing (HTTP 202)
PROCESSING — AS4 sending in progress
DELIVERED — successfully delivered to recipient
RETRYING — temporary error, retry in progress (exponential backoff, max 5 attempts)
FAILED — permanent failure
DEAD_LETTER — moved to DLQ after all retries exhausted

Track status via /status, detailed timeline via /events, and counterparty responses via /responses. — dokument prijatý na spracovanie (HTTP 202)
PROCESSING — prebieha AS4 odosielanie
DELIVERED — úspešne doručený príjemcovi
RETRYING — dočasná chyba, opakovaný pokus (exponenciálny backoff, max 5 pokusov)
FAILED — trvale zlyhanie
DEAD_LETTER — presunuté do DLQ po vyčerpaní všetkých pokusov

Sledujte stav cez /status, detailnu časovú os cez /events a odpovede protistrany cez /responses.
RECEIVED — document received via AS4
VALIDATED — validation completed
DELIVERED — acknowledged by client
FAILED — processing error
REJECTED — rejected

SAPI uses a simplified model: RECEIVED → ACKNOWLEDGED. — dokument prijatý cez AS4
VALIDATED — prebehla validácia
DELIVERED — potvrdený klientom (acknowledged)
FAILED — chyba pri spracovaní
REJECTED — odmietnutý

SAPI používa zjednodušený model: RECEIVED → ACKNOWLEDGED.
1. XML Schema (XSD) — formal validation of XML structure against UBL 2.1 schema
2. EN 16931 Schematron — European e-invoicing standard, validates business semantics
3. Peppol BIS 3.0 Rules — Peppol-specific rules beyond EN 16931

The validate endpoint applies all three layers. Precheck additionally checks the participant and routability. — formálna validácia XML štruktúry podľa UBL 2.1 schemy
2. EN 16931 Schematron — európska norma pre elektronickú fakturáciu, overuje business sémantiku
3. Peppol BIS 3.0 Rules — Peppol-špecifické pravidlá nad rámec EN 16931

Validate endpoint aplikuje všetky tri vrstvy. Precheck navyše overuje participanta a routovateľnosť.
MLR (Message Level Response) — receipt acknowledgment at the AS4 transport level
IMR (Invoice Message Response) — business response to an invoice
ORDER_RESPONSE — response to a purchase order
RECEIPT_ADVICE — goods/service receipt confirmation

Response codes: AP (Accepted), RE (Rejected), CA (Conditionally Accepted), UQ (Under Query), IP (In Process) (Message Level Response) — potvrdenie prijatia správy na úrovni AS4 transportu
IMR (Invoice Message Response) — business odpoveď na fakturu
ORDER_RESPONSE — odpoveď na objednávku
RECEIPT_ADVICE — potvrdenie prijatia tovaru/služby

Kódy odpovedí: AP (Accepted), RE (Rejected), CA (Conditionally Accepted), UQ (Under Query), IP (In Process)
Rate limiting: 200 req/min (default), 100 req/min (SAPI send endpoint). Exceeding limits returns HTTP 429.

OAuth 2.0: client_credentials grant, JWT RS256 tokens. Access token 15 min, refresh token 30 days.

Account lockout: after 5 failed authentication attempts the account is locked (HTTP 423).

HTTPS only: all endpoints require HTTPS. Webhook callback URLs must use HTTPS. 200 req/min (default), 100 req/min (SAPI send endpoint). Prekročenie vráti HTTP 429.

OAuth 2.0: client_credentials grant, JWT RS256 tokeny. Access token 15 min, refresh token 30 dní.

Account lockout: po 5 neúspešných pokusoch o autentifikáciu je účet zamknutý (HTTP 423).

HTTPS only: všetky endpointy vyžadujú HTTPS. Webhook callback URL musí byt HTTPS.
Asynchronous sending uses exponential backoff with a maximum of 5 attempts. After all retries are exhausted the document is moved to the Dead Letter Queue (DLQ) with status DEAD_LETTER.

Retry only applies to transient errors (e.g. network timeout, 503). For permanent errors (e.g. 400, 422) the document is immediately marked FAILED without retrying. s maximálnym poctom 5 pokusov. Po vyčerpaní pokusov sa dokument presunie do Dead Letter Queue (DLQ) so statusom DEAD_LETTER.

Retry sa aplikuje len pri dočasných chybach (napr. network timeout, 503). Pri trvalych chybach (napr. 400, 422) sa dokument okamžite označí ako FAILED bez opakovania.
SML (Service Metadata Locator) — DNS-based registry that determines which SMP a participant is registered in.
SMP (Service Metadata Publisher) — holds participant metadata: supported document types, processes, AS4 endpoint URL and certificate.

Participant lookup: VAT/Company ID → Peppol ID → SML DNS query → SMP metadata. Results are cached locally. (Service Metadata Locator) — DNS-based registry, ktorý urcuje, v ktorom SMP je participant registrovany.
SMP (Service Metadata Publisher) — obsahuje metadata participanta: podporovane typy dokumentov, procesy, AS4 endpoint URL a certifikát.

Participant lookup: DIC/ICO → Peppol ID → SML DNS query → SMP metadata. Výsledky su cachované lokalne.
Authentication

OAuth 2.0 — Bearer Token Authentication. Tokeny získate cez SAPI auth endpoint alebo ASOL IAM server.

Authentication flow
Complete flow from obtaining a token through renewal and revocation.

1. Token

2. Usage

3. Refresh

4. Revoke

Important: Access token is valid for 15 minutes. Refresh token is valid for 30 days. On renewal, the old refresh token is immediately invalidated (token rotation). After 5 failed attempts the account is locked. Access token plati 15 minút. Refresh token plati 30 dní. Po obnovení sa starý refresh token okamžite zneplatní (token rotácia). Po 5 neúspešných pokusoch sa účet zamkne.
Authentication example
Token request and usage
1. Obtaining a token
POST /sapi/v1/auth/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&client_id=your-client-id
&client_secret=your-client-secret
Response
{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 900,
  "scope": "peppol:send peppol:receive"
}
2. Using the token in a request
GET /api/v1/documents/inbox
Authorization: Bearer eyJhbGciOiJSUzI1NiIs...
Accept: application/json

Examples

Request / Response examples

POST /api/v1/documents/send
Sending a document
Request
{
  "senderParticipantId": "iso6523-actorid-upis::9950:2024000001",
  "receiverParticipantId": "iso6523-actorid-upis::9950:2024000002",
  "documentTypeId": "urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0::2.1",
  "processId": "urn:fdc:peppol.eu:2017:poacc:billing:01:1.0",
  "ublDocument": "PD94bWwgdmVyc2lvbj0iMS4wIi..."
}
Response (HTTP 202)
{
  "documentId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "status": "QUEUED",
  "submittedAt": "2025-01-15T14:30:00Z"
}
POST /api/v1/documents/precheck
Precheck before sending
Request
{
  "senderParticipantId": "iso6523-actorid-upis::9950:2024000001",
  "receiverParticipantId": "iso6523-actorid-upis::9950:2024000002",
  "documentTypeId": "urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##...",
  "processId": "urn:fdc:peppol.eu:2017:poacc:billing:01:1.0",
  "ublDocument": "PD94bWwgdmVyc2lvbj0iMS4wIi..."
}
Response
{
  "networkReady": true,
  "valid": true,
  "participantExists": true,
  "canSend": true,
  "errors": [],
  "warnings": [],
  "checkedAt": "2025-01-15T14:29:00Z"
}
POST /api/v1/documents/validate
Document validation
Response (valid document)
{
  "valid": true,
  "schemaValid": true,
  "schematronValid": true,
  "businessRulesValid": true,
  "errors": [],
  "warnings": [],
  "documentType": "Invoice",
  "documentId": "INV-2025-001",
  "issueDate": "2025-01-15",
  "supplierName": "Dodavatel s.r.o.",
  "customerName": "Odberatel a.s.",
  "totalAmount": 1200.00,
  "currencyCode": "EUR"
}
GET /api/v1/participants/lookup/dic
Participant lookup
Response
{
  "source": "SMP",
  "participantId": "abc123",
  "peppolId": "iso6523-actorid-upis::9950:2024000002",
  "organizationName": "Partner s.r.o.",
  "countryCode": "SK",
  "endpointUrl": "https://ap.partner.sk/as4",
  "smpUrl": "https://smp.example.com/...",
  "enabled": true,
  "certificate": {
    "subject": "CN=Partner s.r.o.",
    "issuer": "CN=Peppol CA",
    "serial": "ABC123DEF456",
    "fingerprint": "sha256:...",
    "notBefore": "2024-01-01T00:00:00Z",
    "notAfter": "2026-01-01T00:00:00Z",
    "expired": false
  },
  "smpMetadataUpdatedAt": "2025-01-10T08:00:00Z"
}
GET /api/v1/documents/{id}/events
Document events
Response
[
  {
    "id": "evt-001",
    "messageId": "msg-f47ac10b",
    "eventType": "LIFECYCLE",
    "eventCode": "DOCUMENT_QUEUED",
    "eventMessage": "Dokument zaradený do spracovania",
    "technicalDetails": null,
    "stacktrace": null,
    "createdAt": "2025-01-15T14:30:00Z"
  },
  {
    "id": "evt-002",
    "messageId": "msg-f47ac10b",
    "eventType": "AS4_TRANSPORT",
    "eventCode": "AS4_SENT",
    "eventMessage": "Dokument úspešne odoslaný cez AS4",
    "technicalDetails": "MessageId: msg-f47ac10b",
    "stacktrace": null,
    "createdAt": "2025-01-15T14:30:05Z"
  }
]
POST /api/v1/subscriptions
Webhook subscription
Request
{
  "name": "ERP Invoice Notifications",
  "description": "Notifikácie o novych fakturach",
  "url": "https://erp.example.com/webhooks/peppol",
  "active": true,
  "documentTypeFilters": [
    "urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##..."
  ],
  "senderParticipantFilters": []
}
Webhook notification payload
{
  "eventType": "DOCUMENT_RECEIVED",
  "subscriptionId": "sub-abc123",
  "receivedCount": 3,
  "documentIds": [
    "doc-001", "doc-002", "doc-003"
  ],
  "notifiedAt": "2025-01-15T14:35:00Z"
}

APEX AP Developer Portal

Complete documentation of the implemented API

API group overview
APEX API (/api/v1/) — 15 endpoints: Documents (send, validate, precheck, status, inbox, events, responses), Participants (lookup/dic, lookup/ico), Reporting (statistics, submissions), Webhooks (CRUD + queue). (/api/v1/) — 15 endpointov: Documents (send, validate, precheck, status, inbox, events, responses), Participants (lookup/dic, lookup/ico), Reporting (statistics, submissions), Webhooks (CRUD + queue).
APEX SAPI (/sapi/v1/) — 8 endpoints: Auth (token, status, renew, revoke), Documents (send, receive, detail, acknowledge). (/sapi/v1/) — 8 endpointov: Auth (token, status, renew, revoke), Documents (send, receive, detail, acknowledge).
Authentication — OAuth 2.0 Bearer (JWT RS256), access token 15 min, refresh token 30 days, rate limiting 200 req/min. — OAuth 2.0 Bearer (JWT RS256), access token 15 min, refresh token 30 dní, rate limiting 200 req/min.
Rate limits — 200 req/min (default), 100 req/min (SAPI send). Account lockout after 5 failed attempts. — 200 req/min (default), 100 req/min (SAPI send). Account lockout po 5 neúspešných pokusoch.