SAPI-SK connector
The SAPI-SK connector is an alternative front door for integrators who already
generate their own UBL. Instead of posting structured JSON to
/api/v1/invoices and letting eFakturuj build the UBL, you send a ready-made
UBL 2.1 document and eFakturuj validates, delivers, and files it — while
remaining your Access Point and Service Provider.
Use it if your ERP or accounting system already emits compliant UBL. If you want eFakturuj to generate the UBL from your data, use the native API instead — start at Getting started.
SAPI routes are mounted at the API host root (/sapi), not under /api/v1:
- Production:
https://api.efakturuj.sk/sapi - Sandbox:
https://api.sandbox.efakturuj.sk/sapi
The base_url shown on the connector install screen is the API host —
append /sapi to it when configuring your ERP.
Sandbox delivery is a closed loop: documents sent in sandbox never reach a
real recipient's Access Point, even though the status reaches SENT. To test
delivery end-to-end, send between two sandbox companies — see
End-to-end delivery in sandbox.
Auth is a Bearer access token obtained from client credentials — not the
efk_ API key used by the native API.
The flow at a glance
POST /sapi/auth/token → access_token (15 min)
POST /sapi/document/send → 202 { providerDocumentId, status: ACCEPTED }
GET /sapi/document/status/{documentId} → ACCEPTED → PROCESSING → SENT (eFakturuj extension)
GET /sapi/document/status?documentId=…&sentFrom=… → the same, for many documents (eFakturuj extension)
GET /sapi/participant/check?identifier=… → is this recipient on Peppol? (eFakturuj extension)
GET /sapi/document/receive → inbound documents
POST /sapi/document/receive/{id}/acknowledge → mark inbound as ACKNOWLEDGED
GET /sapi/document/issued → invoices the company issued (eFakturuj extension)
POST /sapi/document/issued/{id}/acknowledge → "this file is safely on my side" (eFakturuj extension)
A single send performs the same full Slovak 5-corner exchange as the native
API: the invoice to the buyer's Access Point, plus the SK Tax Data Document
(TDD) filed with Finančná správa's C5 corner over Peppol, tracked on the C5
ledger and reported in the status endpoint's fs object. You never build
the TDD.
1. Get credentials
Install the SAPI-SK Connector for your company in the dashboard (Firmy → Apps → SAPI-SK Connector). Installing issues:
client_idclient_secret— shown once; store it securely- the connector
base_url - the participant ID the credentials are locked to (taken from the company's configured Peppol participant ID)
Credentials are scoped to one company and its participant ID. A send whose
metadata or X-Peppol-Participant-Id header names a different participant is
rejected with SAPI-AUTH-PARTICIPANT.
Partners provision the same credentials for their managed client companies
from their own system, without a console session. A partner API key holding the
apps:manage scope manages the connector of any company the partner owns:
| Call | What it does |
|---|---|
GET /api/v1/partner/clients/{company_id}/apps/sapi-sk | Installed or not, client_id, participant ids, scopes |
POST /api/v1/partner/clients/{company_id}/apps/sapi-sk/install | Issues client_id and a one-time client_secret (201) |
POST /api/v1/partner/clients/{company_id}/apps/sapi-sk/rotate-secret | New secret; the previous one stops working at once |
POST /api/v1/partner/clients/{company_id}/apps/sapi-sk/uninstall | Revokes the credentials and their tokens |
The credentials stay locked to that one client company and its participant id,
so a partner with many clients stores one secret per client. A company the
partner does not manage answers 404, and a key without apps:manage answers
403 insufficient_scope.
2. Get an access token
POST /sapi/auth/token takes a JSON body (not form encoding).
curl -X POST https://api.efakturuj.sk/sapi/auth/token \
-H 'Content-Type: application/json' \
-d '{
"client_id": "your-client-id",
"client_secret": "…",
"grant_type": "client_credentials"
}'
# → { "access_token": "…", "token_type": "Bearer", "expires_in": 900,
# "refresh_token": "…", "scope": "document:send document:receive" }
| Fact | Value |
|---|---|
| Access token lifetime | 900 s (15 minutes) |
| Refresh token lifetime | 30 days |
| Scopes | document:send, document:receive (both granted unless you request narrower) |
Optionally pass scope to narrow the grant. document:send covers both sending
and reading status; document:receive covers the inbound endpoints.
Renew with POST /sapi/auth/renew ({"refresh_token": "…"}) and revoke with
POST /sapi/auth/revoke ({"token": "…"}).
GET /sapi/auth/token/status reports whether the current token is still valid
and when to refresh — it sets should_refresh: true once fewer than 180
seconds remain.
3. Send a document
POST /sapi/document/send returns 202 Accepted. Two headers are
required:
Idempotency-Key— your unique key for this submissionX-Peppol-Participant-Id— must match your credentials' participant
The body carries the UBL as a plain UTF-8 XML string in payload — it is
not base64. Wire field names are camelCase.
curl -X POST https://api.efakturuj.sk/sapi/document/send \
-H 'Authorization: Bearer <access_token>' \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: 5f2b…' \
-H 'X-Peppol-Participant-Id: 0245:2020111111' \
-d '{
"metadata": {
"documentId": "2026-0001",
"documentTypeId": "busdox-docid-qns::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": "cenbii-procid-ubl::urn:fdc:peppol.eu:2017:poacc:billing:01:1.0",
"senderParticipantId": "0245:2020111111",
"receiverParticipantId": "0245:2020222222",
"creationDateTime": "2026-07-16T10:30:00Z"
},
"payload": "<Invoice xmlns=\"urn:oasis:names:specification:ubl:schema:xsd:Invoice-2\">…</Invoice>",
"payloadFormat": "XML",
"checksum": "…"
}'
# → 202 { "providerDocumentId": "3f1c9a7e5b2d4c86a0e1f7b9d2c4e6a8", "status": "ACCEPTED",
# "receivedAt": "…", "timestamp": "…" }
Save providerDocumentId — it is your handle for status lookups.
| Field | Notes |
|---|---|
payload | Plain UTF-8 XML string. Max 10 MB. |
payloadFormat | "XML" — the only accepted value. |
payloadEncoding | Optional, defaults to UTF-8. Only UTF-8 is supported. |
checksum | Optional. Lowercase SHA-256 hex of the payload bytes. If present it must match, or you get SAPI-VAL-CHECKSUM. |
metadata.documentTypeId | Must agree with the UBL root element — an Invoice payload declared as a CreditNote is rejected. |
Only UBL Invoice and CreditNote roots are accepted. The declared
senderParticipantId / receiverParticipantId must match the EndpointID
values inside the UBL.
Idempotency
Idempotency-Key is required and scoped to your SAPI client. Replaying the same
key with the same body returns the original response. Replaying it with a
different body fails with SAPI-IDEMPOTENCY-CONFLICT.
A repeated invoice number is refused
A company's invoice numbers are unique on every road into eFakturuj, this one
included. A send whose invoice number (the UBL root's own cbc:ID) the company
already has is refused before anything is stored:
HTTP 400
{ "error": { "category": "VALIDATION", "code": "SAPI-VAL-DUPLICATE-NUMBER",
"message": "Invoice number 'FV-2026-0001' already exists in this company.",
"retryable": false,
"details": [{ "field": "payload", "issue": "duplicate_number", "value": "FV-2026-0001" }] } }
Every invoice of the company holds its number, a draft made in the web app included; a received invoice never does. Two cases belong to SAPI-SK alone:
- A try whose delivery surely failed frees its number. Send the number again
with a new
Idempotency-Key: the new document takes the failed one's place. - A try that may have reached the buyer holds its number, even while its
status reads
FAILED. So do not readFAILEDas "the number is free again": if the next send is refused, the first delivery may have arrived, and the receipt from the buyer's Access Point settles it.
A repeated request (the same Idempotency-Key and body) still gets its first
answer. A send the delivery queue could not take ends as FAILED at once, with
queue_unavailable in errorMessage: send it again with a new
Idempotency-Key.
4. Track delivery
eFakturuj extension.
GET /document/status/{documentId}is not part of SAPI-SK v1.0; the eight standard endpoints are unchanged. It serves your outbound documents (received documents are read through the standardGET /document/receive[/{documentId}]).SENTis the final state of the outbound walk: the receiver's Access Point accepted the AS4 transmission. Receiver confirmation (MLS) and Finančná správa (C5) detail are available in the eFakturuj portal, via the native API (GET /api/v1/companies/{company_id}/invoices/{invoice_id}→c5) and via Connect webhooks (invoice.delivered,invoice.rejected,invoice.fs_acknowledged,invoice.fs_rejected).
curl https://api.efakturuj.sk/sapi/document/status/3f1c9a7e5b2d4c86a0e1f7b9d2c4e6a8 \
-H 'Authorization: Bearer <access_token>' \
-H 'X-Peppol-Participant-Id: 0245:2020111111'
# → { "providerDocumentId": "…", "clientDocumentId": "2026-0001",
# "status": "SENT", "direction": "outbound",
# "peppolMessageId": "…",
# "fs": { "status": "ACKNOWLEDGED", "submissionId": "<TDD UUID>",
# "reportDeadline": null, "acknowledgedAt": "…", "errorMessage": null },
# "updatedAt": "…", "timestamp": "…" }
Outbound status walks:
ACCEPTED → PROCESSING → SENT (or FAILED)
The fs object is the Finančná správa leg: the C5 filing of the tax-data
document (TDD) that eFakturuj builds and sends for you. It mirrors the C5
ledger row of the document's latest transmission:
| What happened at C5 | fs.status | fs.submissionId | fs.acknowledgedAt | fs.errorMessage |
|---|---|---|---|---|
| nothing has reached FS yet: queued, in flight, retrying between attempts, or C5 not enabled on this stage | NOT_SUBMITTED | null | null | null |
| C5 acknowledged the AS4 message | SUBMITTED | TDD UUID | null | null |
| C5 confirmed the document (positive MLS) | ACKNOWLEDGED | TDD UUID | set | null |
C5 rejected the document (MLS RE) | FAILED | TDD UUID | null | FS's reasons: the description plus up to three line issues, ; -joined, at most 1000 characters |
| transmission failed permanently (attempts exhausted, build or transport error) | FAILED | TDD UUID | null | the error classification, for example EBMS:0004 NOT_SERVICED or timeout |
Notes:
- Only states Finančná správa itself confirmed count as progress. In the
healthy case C5 acknowledges within seconds and the MLS follows within
minutes of
SENT. FAILEDis not always final: an eFakturuj operator can retry the filing, which movesfs.statusback toNOT_SUBMITTEDand then forward again.fs.reportDeadlineis reserved and alwaysnull.- On a stage where the C5 filing is not enabled (production until Finančná
správa's PROD go-live)
fs.statusstaysNOT_SUBMITTED.
Look a document up by your own number
{documentId} matches either identifier: our providerDocumentId, or the
metadata.documentId you sent in POST /document/send. If you set
metadata.documentId to your invoice number, you can ask for status by invoice
number and never store our id.
One limit: it is a path segment, so a number containing / cannot go there
(2026%2F000009 is unquoted before routing and matches no route). Use the list
form below for those.
Many documents in one call
eFakturuj extension.
GET /document/status(no path segment) returns the same per-document object as the single form, for several documents at once.
curl -G https://api.efakturuj.sk/sapi/document/status \
--data-urlencode 'documentId=2026/000009' \
--data-urlencode 'documentId=2026/000010' \
-H 'Authorization: Bearer <access_token>' \
-H 'X-Peppol-Participant-Id: 0245:2020111111'
# → { "documents": [ { "providerDocumentId": "…", "clientDocumentId": "2026/000009", … } ],
# "nextPageToken": null }
| Parameter | Meaning |
|---|---|
documentId | repeatable; matches providerDocumentId or your clientDocumentId |
sentFrom / sentTo | send-date range, YYYY-MM-DD, both days included |
limit | 1–100, default 50 |
pageToken | cursor from the previous response's nextPageToken |
Filters combine. With none of them you get your whole outbound history, paged.
Scope and tenancy are those of the single form: document:send, your client's
own documents, sent from the participant in the header. Documents come back
oldest first.
One difference from the single form: if you submitted the same
clientDocumentId more than once, the single form answers with the newest
submission, while the list form returns every submission that carried it.
4b. Check whether a recipient is reachable
eFakturuj extension.
GET /participant/check?identifier=…answers "can I reach this company over Peppol?" for one identifier per call. It is the same verdict as the public tool atPOST /api/v1/tools/peppol-check, with two differences that matter to an integration: it runs on your client's own rate limit (your plan's budget, bucketed per SAPI client, never shared with another integrator behind the same IP), and it reports the receiving access point.
curl -G https://api.efakturuj.sk/sapi/participant/check \
--data-urlencode 'identifier=SK2020123456' \
-H 'Authorization: Bearer <access_token>'
# → { "query": "SK2020123456", "registered": true,
# "companyName": "Example s.r.o.", "vatIdChecked": true,
# "candidates": [ { "peppolId": "0245:2020123456", "scheme": "DIČ",
# "registered": true, "testRegistered": false,
# "name": "Example s.r.o.", "country": "SK",
# "smpUrl": "https://smp…",
# "firstObservedAt": "2026-03-02T04:10:00Z",
# "accessPoint": { "operator": "Example AP s.r.o.", "cn": "PSK000001" } } ] }
identifier is a company name, IČ DPH (SK + 10 digits), DIČ (10 digits), IČO
(8 digits) or a full participant id. A value we cannot turn into a participant id
is 400 SAPI-VAL-IDENTIFIER.
registered is the verdict: true when any derived candidate id resolves in the
production Peppol SML. vatIdChecked is false when no DIČ could be derived, so
only the IČO (0158) scheme was checked — a negative is then inconclusive,
because most Slovak participants register under their VAT id (0245).
accessPoint names the provider receiving for that id, from its SMP
certificate; firstObservedAt is when our sweep first saw it registered, not
the network's registration date.
Budget and caching. There is no batch form, by design: one call, one answer, and the standard rate limit does the fairness. Your SAPI token is bucketed per client at your plan's rate (see Rate limits), so a screen that lists today's invoices can check each recipient on first sight and remember the answer. Verdicts are also cached on our side: a registered participant for ten minutes, an unregistered one for one minute, so a company that has just joined the network goes green promptly. Nothing else is stored and the call is not billable.
5. Receive inbound documents
curl 'https://api.efakturuj.sk/sapi/document/receive?limit=20' \
-H 'Authorization: Bearer <access_token>' \
-H 'X-Peppol-Participant-Id: 0245:2020222222'
# → { "documents": [ { "documentId": "8996b481a5de50cea57f368b144d68a2",
# "documentTypeId": "busdox-docid-qns::…::2.1",
# "processId": "cenbii-procid-ubl::…:1.0",
# "senderParticipantId": "0245:2020111111",
# "receiverParticipantId": "0245:2020222222",
# "creationDateTime": "…",
# "status": "RECEIVED", "receivedAt": "…" } ],
# "nextPageToken": "…" }
List items are flat, exactly as the national SAPI-SK specification defines
them — the six metadata fields sit directly on the item (status and
receivedAt are eFakturuj additions). Only the detail response nests a
metadata object, alongside the full UBL in payload.
Paginate with pageToken; filter with status. Fetch one document:
curl https://api.efakturuj.sk/sapi/document/receive/8996b481a5de50cea57f368b144d68a2 \
-H 'Authorization: Bearer <access_token>' \
-H 'X-Peppol-Participant-Id: 0245:2020222222'
Acknowledge it. The request takes no body:
curl -X POST https://api.efakturuj.sk/sapi/document/receive/8996b481a5de50cea57f368b144d68a2/acknowledge \
-H 'Authorization: Bearer <access_token>' \
-H 'X-Peppol-Participant-Id: 0245:2020222222'
# → { "documentId": "…", "status": "ACKNOWLEDGED", "acknowledgedDateTime": "…" }
Acknowledgement is idempotent — re-acknowledging keeps the original timestamp.
To be told about new documents instead of polling, subscribe a
webhook to invoice.received. Its data.provider_document_id
is this documentId (8996b481a5de50cea57f368b144d68a2), so the webhook leads straight to the
detail call above; it is null when SAPI-SK holds no copy of the document.
6. Invoices you issued at eFakturuj
eFakturuj extension. These three calls are not part of SAPI-SK v1.0. They give a company's key the invoices the company issued at eFakturuj, on the web, through the API, by import or over SAPI-SK, so a program can keep a copy of each one on the company's own computer. Scope
document:receive.
curl 'https://api.efakturuj.sk/sapi/document/issued?issuedFrom=2026-11-17&limit=20' \
-H 'Authorization: Bearer <access_token>' \
-H 'X-Peppol-Participant-Id: 0245:2020111111'
# → { "documents": [ { "documentId": "8a3a3c73-59f1-467f-9b2c-1f8513775f2d",
# "invoiceNumber": "FV-2026-0001", "issueDate": "2026-11-17",
# "typeCode": "380", "status": "SENT_PEPPOL",
# "createdAt": "2026-11-17T09:12:00Z",
# "providerDocumentIds": ["0f8fad5bd9cb469fa16570867728950e"] } ],
# "nextPageToken": "MjA=" }
| Query | Meaning |
|---|---|
issuedFrom | Optional date. Documents with an earlier issue date are left out. |
limit | 1 to 100, default 20. |
pageToken | The nextPageToken of the page before. It is absent on the last page. |
The list holds the company's invoices and credit notes (380, 381, 384,
388) once they can no longer change: issued, sent or delivered, or voided or
rejected after that. Never a draft, a proforma or a received invoice, and only
what this key has not acknowledged yet. providerDocumentIds names the SAPI-SK
send whose file the document comes with, so a program that finds its own send
there may keep the file it sent; it is empty when the file is not a SAPI-SK
send's. The order is createdAt, the same on every call: read every page first,
then acknowledge.
Fetch one document with its Peppol XML:
curl https://api.efakturuj.sk/sapi/document/issued/8a3a3c73-59f1-467f-9b2c-1f8513775f2d \
-H 'Authorization: Bearer <access_token>' \
-H 'X-Peppol-Participant-Id: 0245:2020111111'
# → { "documentId": "…", "invoiceNumber": "FV-2026-0001", "issueDate": "2026-11-17",
# "typeCode": "380", "payload": "<?xml version=\"1.0\" …><Invoice …>", "payloadFormat": "XML" }
payload is the file that went out (for a SAPI-SK send, your own file), or the
file eFakturuj makes from the invoice when none went out. When the file cannot be
read or made, the call answers 422 SAPI-DOC-NO-PAYLOAD: ask again later and do
not acknowledge.
Acknowledge it once the file is safely on your side. The request takes no body:
curl -X POST https://api.efakturuj.sk/sapi/document/issued/8a3a3c73-59f1-467f-9b2c-1f8513775f2d/acknowledge \
-H 'Authorization: Bearer <access_token>' \
-H 'X-Peppol-Participant-Id: 0245:2020111111'
# → { "documentId": "…", "status": "ACKNOWLEDGED", "acknowledgedDateTime": "…" }
An acknowledged document leaves this key's list (another key of the same company still gets it) and can still be fetched. A second acknowledgement keeps the first time. From then on eFakturuj no longer lets the company delete that invoice: it is corrected with a credit note, so a copy on your side never meets its number again with other content.
Errors
SAPI errors use their own envelope — not the native API's error shape:
{
"error": {
"category": "VALIDATION",
"code": "SAPI-VAL-001",
"message": "Document payload is not well-formed XML.",
"retryable": false,
"correlation_id": "…",
"details": [{ "field": "payload", "issue": "…" }]
}
}
category is one of the five SAPI-SK v1.0 categories AUTH, VALIDATION,
PROCESSING, TEMPORARY, PERMANENT. Retry only when retryable is true.
Quote correlation_id in support requests.
| Code | Meaning |
|---|---|
SAPI-AUTH-001 | Authentication failed (401) |
SAPI-AUTH-LOCKED | Client locked after repeated auth failures (15 minutes) |
SAPI-AUTH-PARTICIPANT | Participant not permitted for these credentials |
SAPI-AUTH-SCOPE / SAPI-VAL-SCOPE | Token lacks the required scope |
SAPI-AUTH-IP | Request from an IP outside the client's allowlist |
SAPI-VAL-001 | Generic validation failure (bad XML, unsupported root, metadata mismatch, missing header) |
SAPI-VAL-CHECKSUM | checksum does not match the payload |
SAPI-VAL-VALIDATION-UNAVAILABLE | Validator bundles unavailable and strict validation is on — fail-closed |
SAPI-IDEMPOTENCY-CONFLICT | Idempotency-Key reused with a different body |
SAPI-VAL-DUPLICATE-NUMBER | The company already has this invoice number (400) — see A repeated invoice number is refused |
SAPI-DOC-NOT-FOUND | Unknown document id (404) |
SAPI-DOC-NO-PAYLOAD | An issued document's file cannot be read or made (422, retryable: false): ask again later, do not acknowledge |
SAPI-QUOTA-INVOICE-LIMIT | Monthly plan invoice quota exceeded (402, category PERMANENT, retryable: false) |
SAPI-DISABLED | SAPI facade disabled (503, retryable) |
Quotas
Sends count against your plan's monthly invoice limit, the same counter the
native API uses. Exceeding it returns 402 with SAPI-QUOTA-INVOICE-LIMIT
and the plan tier and limit in details — unless your plan permits overage, in
which case the send proceeds and is billed.
Documented deviation from SAPI-SK v1.0. The standard's HTTP table has no 402 row and no quota category. eFakturuj answers a plan-limit refusal with HTTP 402 and category
PERMANENT(retryable: false): the request is well-formed and authorised, but it will not succeed until the plan changes or the month rolls over. A client that switches oncategoryneeds no special case; a client that switches on the HTTP status should treat 402 likePERMANENT.
Testing
Use the sandbox host (https://api.sandbox.efakturuj.sk/sapi). It has the same
shape and runs against isolated test data without delivering to the real Peppol
network or billing.
Sandbox companies get their participant ID derived automatically as
9950:sk<IČ DPH>efakturujtest (for example 9950:sk2020111111efakturujtest) —
use that value in the examples above instead of the production 0245:<DIČ>
form. The connector install screen always shows the exact participant your
credentials are locked to.
Next steps
- Getting started — the native API alternative
- Sandbox · Webhooks · Errors
End-to-end delivery in sandbox
How sandbox delivery really works, and how to test a full send → receive flow between two sandbox companies.
Partner API
Acting for your client companies with a partner API key - create, validate and send, track Peppol delivery and FS reporting separately, and download the documents as they were sent or received.