eFakturuj / API Docs
eFakturuj Guides

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_id
  • client_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:

CallWhat it does
GET /api/v1/partner/clients/{company_id}/apps/sapi-skInstalled or not, client_id, participant ids, scopes
POST /api/v1/partner/clients/{company_id}/apps/sapi-sk/installIssues client_id and a one-time client_secret (201)
POST /api/v1/partner/clients/{company_id}/apps/sapi-sk/rotate-secretNew secret; the previous one stops working at once
POST /api/v1/partner/clients/{company_id}/apps/sapi-sk/uninstallRevokes 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" }
FactValue
Access token lifetime900 s (15 minutes)
Refresh token lifetime30 days
Scopesdocument: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 submission
  • X-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.

FieldNotes
payloadPlain UTF-8 XML string. Max 10 MB.
payloadFormat"XML" — the only accepted value.
payloadEncodingOptional, defaults to UTF-8. Only UTF-8 is supported.
checksumOptional. Lowercase SHA-256 hex of the payload bytes. If present it must match, or you get SAPI-VAL-CHECKSUM.
metadata.documentTypeIdMust 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 read FAILED as "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 standard GET /document/receive[/{documentId}]). SENT is 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 C5fs.statusfs.submissionIdfs.acknowledgedAtfs.errorMessage
nothing has reached FS yet: queued, in flight, retrying between attempts, or C5 not enabled on this stageNOT_SUBMITTEDnullnullnull
C5 acknowledged the AS4 messageSUBMITTEDTDD UUIDnullnull
C5 confirmed the document (positive MLS)ACKNOWLEDGEDTDD UUIDsetnull
C5 rejected the document (MLS RE)FAILEDTDD UUIDnullFS's reasons: the description plus up to three line issues, ; -joined, at most 1000 characters
transmission failed permanently (attempts exhausted, build or transport error)FAILEDTDD UUIDnullthe 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.
  • FAILED is not always final: an eFakturuj operator can retry the filing, which moves fs.status back to NOT_SUBMITTED and then forward again.
  • fs.reportDeadline is reserved and always null.
  • On a stage where the C5 filing is not enabled (production until Finančná správa's PROD go-live) fs.status stays NOT_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 }
ParameterMeaning
documentIdrepeatable; matches providerDocumentId or your clientDocumentId
sentFrom / sentTosend-date range, YYYY-MM-DD, both days included
limit1–100, default 50
pageTokencursor 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 at POST /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=" }
QueryMeaning
issuedFromOptional date. Documents with an earlier issue date are left out.
limit1 to 100, default 20.
pageTokenThe 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.

CodeMeaning
SAPI-AUTH-001Authentication failed (401)
SAPI-AUTH-LOCKEDClient locked after repeated auth failures (15 minutes)
SAPI-AUTH-PARTICIPANTParticipant not permitted for these credentials
SAPI-AUTH-SCOPE / SAPI-VAL-SCOPEToken lacks the required scope
SAPI-AUTH-IPRequest from an IP outside the client's allowlist
SAPI-VAL-001Generic validation failure (bad XML, unsupported root, metadata mismatch, missing header)
SAPI-VAL-CHECKSUMchecksum does not match the payload
SAPI-VAL-VALIDATION-UNAVAILABLEValidator bundles unavailable and strict validation is on — fail-closed
SAPI-IDEMPOTENCY-CONFLICTIdempotency-Key reused with a different body
SAPI-VAL-DUPLICATE-NUMBERThe company already has this invoice number (400) — see A repeated invoice number is refused
SAPI-DOC-NOT-FOUNDUnknown document id (404)
SAPI-DOC-NO-PAYLOADAn issued document's file cannot be read or made (422, retryable: false): ask again later, do not acknowledge
SAPI-QUOTA-INVOICE-LIMITMonthly plan invoice quota exceeded (402, category PERMANENT, retryable: false)
SAPI-DISABLEDSAPI 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 on category needs no special case; a client that switches on the HTTP status should treat 402 like PERMANENT.

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