Technická referencia pre všetkých 25+ endpointov implementovaných v APEX AP Service. Obsahuje APEX API pre hlbokú integráciu, SAPI pre zjednodušený prístup podľa SAPI-SK v1.0, autentifikáciu, validáciu, odosielanie, inbox, webhooky, reporting a participant lookup.
APEX Access Point ponúka dve rovnocenné spôsoby integrácie. Výber závisí od toho, kde beží váš systém a aký štýl komunikácie potrebujete. Obe cesty pokrývajú plný Peppol tok (odosielanie aj prijímanie) a môžete ich aj kombinovať.
apex.asseco-peppol.com s OAuth 2.0 tokenom. JSON payload, UBL XML v Base64. Synchronné request/response + status polling alebo webhooky.SynchronizationMessage s entitou PeppolDocument, QHUB ju doručí do APEX-u a prípadné odpovede pošle späť na vašu queue.APEX AP poskytuje dve API skupiny: APEX API (/api/v1/) pre hlbokú enterprise integráciu a APEX SAPI (/sapi/v1/) pre zjednodušené rozhranie podľa SAPI-SK v1.0 špecifikácie.
Technická cesta od prvého requestu po kompletnú integráciu: autentifikácia, validácia, odoslanie a sledovanie stavu.
POST /sapi/v1/auth/token s client_credentials. Získate JWT access token (15 min) a refresh token (30 dní). Token používajte v hlavičke Authorization: Bearer <token>.POST /api/v1/documents/validate alebo /precheck. Validate overí XML, Schematron a business rules. Precheck navyše overí existenciu participanta a routovateľnosť.POST /api/v1/documents/send. API vráti HTTP 202 so statusom QUEUED. Dokument sa spracuje asynchrónne — QUEUED neznamená finálne doručenie.GET /api/v1/documents/{id}/status pre aktuálny stav. Použite /events pre časovú os a /responses pre odpovede protistrany (MLR, IMR).Kompletná dokumentácia všetkých endpointov implementovaných v APEX AP Service. Každý endpoint obsahuje účel, vstupy, vystupy, typické chyby a príklady.
/status endpoint.400 — chýbajúci povinny udaj alebo nevalidný payload401 — neplatný alebo expirovaný token422 — nevalidný UBL dokument404 — dokument neexistuje401 — neplatný token400 — nevalidné XML alebo nesprávny payload422 — porušenie validačných pravidielnetworkReady = valid AND participantExists AND canSend.CERT_EXPIRING_SOON — certifikát príjemcu čoskoro vyprší400 — chýbajúci povinny udaj422 — validačné chyby v dokumente404 — participant nenájdený v SMP/SMLtotal pre celkový počet záznamov.400 — neplatný filter alebo parameter401 — neplatný tokendocumentId, senderParticipantId, receiverParticipantId, documentTypeId, processId, receivedAt, status, ublDocument (XML payload)404 — dokument neexistuje401 — neplatný token404 — dokument neexistuje409 — dokument už bol potvrdený (conflict)404 — dokument neexistuje404 — dokument neexistuje alebo nemá odpovedesource pole: LOCAL alebo SMP.400 — chýbajúci parameter schema alebo dic404 — participant neexistuje503 — SMP/SML dočasné nedostupný400 — neplatný format ICO422 — ICO sa nepodarilo preložiť na DIC404 — participant neexistujeperiod — typ a rozsah obdobiasent — total, delivered, failed, deliveryRate, byDocumentType, byCountryreceived — rovnaka štruktúratopRecipients[], topSenders[] — zoznamy top partnerovfailedDocuments — total, deadLetters, retrying, rejected400 — neplatne obdobie alebo format datumu400 — neplatný filterdocumentTypeFilters[]) a odosielateľa (senderParticipantFilters[]). Bez filtra sa notifikuje o všetkých prijatých dokumentoch.400 — neplatná URL (musí byt https://)422 — nevalidný filter401 — neplatný token404 — subscription neexistuje404 — subscription neexistuje400 — neplatná URL alebo filtre404 — subscription neexistuje409 — queue už existuje pre daný účetclient_credentials grant type. Vráti JWT access token (platnosť 15 min) a refresh token (platnosť 30 dní). Token je podpísaný algoritmom RS256.401 — neplatne client_id alebo client_secret423 — účet zamknutý po 5 neúspešných pokusoch429 — prekročený rate limit401 — token je neplatný alebo expiroval401 — neplatný alebo expirovaný refresh token400 — chýbajúci token parameter/documents/send, ktorý je asynchrónny, SAPI send čaká na výsledok doručenia.Idempotency-Key — unikátny kľúč pre idempotentne spracovanie (povinné)X-Peppol-Participant-Id — Peppol ID odosielateľa (povinné)400 — chýbajúci Idempotency-Key alebo payload422 — validačné chyby429 — prekročený rate limit (100/min)502 — chyba pri AS4 doručenípageToken namiesto offset/limit. Odpoveď obsahuje next_page_token pre ďalšiu stranu. total_count uvadza celkový počet.400 — neplatný pageToken alebo filter401 — neplatný token404 — dokument neexistuje404 — dokument neexistuje/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./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./auth/token platia pre obe API.iso6523-actorid-upis::9950:2024000001). Používa sa na routing a SMP lookup./lookup/ico automaticky prekladá ICO → DIC → Peppol ID./status, detailnu časovú os cez /events a odpovede protistrany cez /responses.
Všetky API endpointy vyžadujú autentifikáciu pomocou Bearer tokenu v hlavičke Authorization.
Tokeny získate cez SAPI auth endpoint alebo ASOL IAM server.
POST /sapi/v1/auth/token s client_credentials
Authorization: Bearer <token> v každom requeste
POST /sapi/v1/auth/renew s refresh tokenom
POST /sapi/v1/auth/revoke pri odhlásení
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
{
"access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
"token_type": "Bearer",
"expires_in": 900,
"scope": "peppol:send peppol:receive"
}
GET /api/v1/documents/inbox Authorization: Bearer eyJhbGciOiJSUzI1NiIs... Accept: application/json
Konkretne príklady JSON payloadov pre kľúčové endpointy.
{
"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..."
}
{
"documentId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"status": "QUEUED",
"submittedAt": "2025-01-15T14:30:00Z"
}
{
"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..."
}
{
"networkReady": true,
"valid": true,
"participantExists": true,
"canSend": true,
"errors": [],
"warnings": [],
"checkedAt": "2025-01-15T14:29:00Z"
}
{
"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"
}
{
"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"
}
[
{
"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"
}
]
{
"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": []
}
{
"eventType": "DOCUMENT_RECEIVED",
"subscriptionId": "sub-abc123",
"receivedCount": 3,
"documentIds": [
"doc-001", "doc-002", "doc-003"
],
"notifiedAt": "2025-01-15T14:35:00Z"
}