For developers: API reference

The Verteco API is REST over HTTPS. Both request and response are JSON (UTF-8). Start by creating an account, then an API token, and make your first call within a minute. All paths are relative to the base URL below.

The complete test environment (sandbox) is available at test.peppol.verteco.digital. It behaves the same as production and additionally offers test tools (webhook of the Financial Administration of the Slovak Republic (Finančná správa, FS), verification token (Verifikačný údaj), company removal) and a simulated provider selection instead of the FS portal (VPDS).

Base URL

https://peppol.verteco.digital/api/v1

Version

v1 (in the path). Backward-incompatible changes will ship under a new version.

Protocol

HTTPS only · TLS 1.2+ · TLS A+

Format

application/json (UTF-8)

Auth

cookie session (portal) or Bearer token (server-to-server)

Timestamps

ISO-8601 (UTC), e.g. 2026-06-03T09:40:27Z

You create both the account and the API token in the portal (via the browser). The integration then runs exclusively through the API token. Your app does not need to handle registration, login or passwords.

1. 1

   Create an account in the portal

   Sign up with your e-mail and confirm it via the link in the e-mail.
2. 2

   Generate an API token

   In the portal, go to API tokeny → Vytvoriť (API tokens → Create). The vpt_… token is shown only once. Store it securely.
3. 3

   Make your first call

   Use the token in the Authorization header:

   javascriptKopírovať

   const res = await fetch('https://peppol.verteco.digital/api/v1/companies', {
   headers: { Authorization: 'Bearer vpt_8f2a…' },
   });
   const companies = await res.json();

4. 4

   Select the provider on the Financial Administration portal

   In production, selecting Verteco on the FS portal (vpds.financnasprava.sk) is needed even for send-only use: it unlocks sending (the verification token) and activates the company. Receiving may stay with your accounting program's provider: a company has exactly one receiver in the network but may have several senders.

export BASE=https://test.peppol.verteco.digital   # production: https://peppol.verteco.digital
export KEY=vpt_…        # step 1

In addition to the SAPI mock sandbox (below), we also operate a full-featured test environment, a complete copy of this portal with separate data, where you can try the entire flow (registration → company → sending → receiving → notifications) end-to-end without any impact on production.

URL

https://test.peppol.verteco.digital

Registration

no confirmation e-mail; the account is usable immediately

Company approval

automatic, directly in the UI or via the API; there is no provider selection on the portal of the Financial Administration of the Slovak Republic (Finančná správa, FS) and no FS portal login; right after creating a company with a VAT ID (IČ DPH) you can both send and receive

Network registration

automatic, into the Peppol test network. Note the two layers of the identifier: the API and the portal use the same format as production (peppolParticipantId = 0245:<DIČ digits>, where DIČ is the Slovak tax identification number; your integration code does not change); in the test SMP/SML the company is technically registered as 9950:SK<DIČ>, because the 0245 scheme requires a Financial Administration verification code that does not exist in the test environment. In production, 0245:<DIČ digits> is registered in the live Peppol network only after the provider selection on the FS portal (login with eID or the portal credentials)

Validation

real: EN 16931 + Peppol BIS 3.0 rules, the same as in production

Delivery

real, over the Peppol test network (AS4, test certificate, test SML/SMP): a recipient registered in the test network receives the invoice as a received invoice (including the e-mail, PDF and webhook); nothing leaves for the live network

Delivery receipt (MLS)

a real MLS receipt from the test network

E-mails

are really sent (to the addresses you enter), with the [TEST] prefix

Fault simulation

the header X-Sandbox-Simulate: 503 (or 502, 500, 429) on any /sapi/document/* call with a valid token returns the matching error; nothing is processed or stored. For 500 (SAPI-PROC-500) and 429 (SAPI-SYS-003 with Retry-After) you get the SAPI error envelope; 503 and 502 pass through the network edge (DigitalOcean, Cloudflare) as HTTP 504 with an HTML body and no envelope, exactly how a real outage looks from outside, so you also test handling of a non-JSON response. Validation errors come from invalid XML, 429 also from exceeding 300 calls per minute. Production ignores the header

Price

free, with no limits for testing

Everything that works here works there: the portal, the REST API, SAPI-SK 1.0, e-shop plugins and webhooks. Just switch the domain in your integration to test.peppol.verteco.digital and use the tokens created in the test environment. Ideal for integration development, CI tests and training accountants before the production rollout. Test documents belong there only: in production every domestic document between VAT payers is reported to the Financial Administration and the report cannot be withdrawn. In the production portal test only with the „Poslať skúšobnú faktúru“ button (send a test invoice, 0,00 €); from 1 January 2027 production refuses TEST-/VITAJTE- numbers (test_document_in_production).

Note: the edge protection of the test domain blocks the generic headers User-Agent: Python-urllib and User-Agent: Java/1.8.x (the default User-Agent of HttpsURLConnection in Java 8) with HTTP 403 "error code: 1010" before the request even reaches our API; the production domain peppol.verteco.digitallets them through. Set your own User-Agent: in Java either with the JVM flag -Dhttp.agent=my-app/1.0 (no code change; Java appends "Java/1.8", and the resulting "my-app/1.0 Java/1.8.0_xxx" passes, only a header starting with "Java/1.8" is blocked) or on the connection with conn.setRequestProperty("User-Agent", "my-app/1.0"). Common clients (requests, httpx, Java 11+, Apache HttpClient, okhttp, axios, Go, PHP, curl) work unchanged.

Why companies are approved automatically

The Financial Administration has no test environment for the VPDS portal: provider selection on vpds.financnasprava.sk runs only in production and is verified by logging in to the FS portal (eID or FS portal credentials), so in production you cannot “select” an arbitrary company that is not your own. So that you can still test your integration, we simulate this step in the test environment: every company you create is approved automatically (without selection at FS), so you can set up both a sender and a recipient and go through the entire flow.

For testing FS webhooks (provider selection) we have our own counterpart to the Financial Administration tool: test.peppol.verteco.digital/sandbox-nastroje. There you can generate a valid FS-style verification token (Verifikačný údaj) and send a complete webhook to your endpoint, exactly as the FS portal does during a real selection. Companies created for testing can in turn be deregistered (from the portal and from the test SMP), precisely because of the missing test mode on the Financial Administration side.

Your integration authenticates with an API token in the header Authorization: Bearer vpt_…. You create the token in the portal (API tokens); it has the format vpt_ + 40 hex characters, we store only its SHA-256 hash, and it has the same access as your account. Test it via /auth/me:

curl https://peppol.verteco.digital/api/v1/auth/me -H 'Authorization: Bearer vpt_8f2a…'
# 200 → { "id": "…", "email": "vy(at)firma.sk" }   (token works)

With a missing or invalid token the API returns:

// 401 Unauthorized
{ "error": "unauthorized", "message": "Authentication required" }

Pagination & idempotency

• The contract only grows: new fields (omitted when null), new optional parameters, new endpoints and events. Existing field names, enum values and status codes do not change.
• A new enum value or webhook event may appear at any time; ignore what you do not know and answer an unknown event with 2xx.
• Timestamps are ISO 8601 UTC with a variable number of fractional digits; parse them, never compare them as text. Amounts arrive as strings with two decimals.
• Should a change ever be non-additive, we announce it in the changelog (e-mail subscription available) at least 90 days ahead and keep the old shape during a transition period.
• API-key security model (since 3 October 2026): a key reads and sends documents and manages companies, notifications and webhooks. Account and key management (creating, scoping or revoking keys, MFA, password, sessions, invitations, company transfer, contract signatures) is done by a signed-in person only; a key gets 403 token_not_allowed there. GET /api/v1/tokens stays open to keys.
• The contract version is info.version in openapi.json and every change has a changelog line tagged API or Webhooks.

/changelog · /changelog/odber · openapi.json

Errors have a uniform shape with a machine-readable error code. Validation errors add a fields map (first error per field).

// business error
{ "error": "invalid_credentials", "message": "Invalid email or password" }

// validation error (400); field messages are returned in Slovak ("IČO musí byť 8 číslic" = "IČO must be 8 digits")
{ "error": "validation_failed", "message": "Some fields are invalid",
"fields": { "ico": "IČO musí byť 8 číslic" } }

HTTP statuses

200 / 201 / 204

success (OK / Created / No Content)

400

invalid input (see error / fields)

401

missing or invalid authentication

403

insufficient permission (role)

404

the resource does not exist or you have no access to it

405

HTTP method not supported for this path

409

conflict (IČO / e-mail already exists)

415

unsupported Content-Type (XML endpoints expect application/xml)

429

rate limit exceeded (RateLimit-* and Retry-After headers, JSON body rate_limited)

Most common error codes

Access Point outage and retries

• If the API answers 502, 503 or 504, or does not answer at all, we did not take the document over: repeat the call later with the same Idempotency-Key, nothing is sent twice.
• A document the API accepted (202 ACCEPTED, also with retrying: true) leaves on its own after recovery: the Access Point retries the delivery and you see the state via GET /sapi/document/sent or a webhook; if it finally gives up, the document ends as failed and the same key sends it again.
• Receiving at network level does not depend on the portal: a delivery that did not get through during a portal outage is retried by the sending Access Point under the Peppol rules and the document appears in the portal after recovery. FS reports that did not leave because of the outage are back-filled by an automatic recovery run (a transport failure is retried, a content rejection is not).
• Status and availability history are on /status; in the test environment you simulate an outage with the X-Sandbox-Simulate header (section Test environment).

The API is protected by rate limiting in a 60-second window (per instance). The limit and the remaining quota are returned in every response via headers; when exceeded, the API returns 429 Too Many Requests with Retry-After.

Regular calls

dynamic limit with a large headroom, per API token (or session, otherwise IP); the current value is returned in the RateLimit-Limit header

Auth (/auth/*)

stricter limit per IP (anti brute-force; except /auth/me and /auth/logout)

RateLimit-Limit

limit in the window

RateLimit-Remaining

how many requests remain

RateLimit-Reset

seconds until the window resets

Retry-After

seconds until the next attempt (on 429)

HTTP/2 429 Too Many Requests
RateLimit-Limit: <limit in the window>
RateLimit-Remaining: 0
RateLimit-Reset: 37
Retry-After: 37

{ "error": "rate_limited", "message": "Too many requests. Slow down." }

HTTP/2 200
RateLimit-Limit: 300
RateLimit-Remaining: 287
RateLimit-Reset: 41
RateLimit-Policy: 300;w=60

Opaque vpt_… tokens for server-to-server access. The plaintext is shown only once at creation. Save it. We store only the SHA-256 hash and a 12-character prefix for display.

curl -X POST https://peppol.verteco.digital/api/v1/tokens -b cookies.txt \
-H 'Content-Type: application/json' -d '{"name":"moja-appka"}'
# 201 Created
{ "id":"…","name":"moja-appka","token":"vpt_8f2a…","prefix":"vpt_8f2a3b…","createdAt":"…" }

Companies, identified by company registration number (IČO) / VAT ID (IČ DPH), that you manage. Access is tied to membership: you only see companies you are a member of. The creator of a company becomes its owner.

curl -X POST https://peppol.verteco.digital/api/v1/companies \
-H 'Authorization: Bearer vpt_8f2a…' -H 'Content-Type: application/json' \
-d '{"ico":"53412834","dic":"SK2121358349","legalName":"Verteco digital services, s. r. o."}'

# 201 Created
{ "id":"08dd…","ico":"53412834","dic":"SK2121358349","legalName":"…",
"registeredAddress":null,"peppolParticipantId":null,
"status":"pending_verification","role":"owner","createdAt":"2026-06-03T09:40:27Z" }

The status field

pending_verification

after creation; sending is not yet unlocked

active

verified, sending unlocked

Member role

owner

company creator (full access)

admin

administrator (edits, webhooks, verification)

member

member (read)

viewer

read-only

Before sending, the company must be verified using the verification token (Verifikačný údaj, VÚ), a signed token issued by the Financial Administration of the Slovak Republic (Finančná správa, FS). After successful verification, the status of the company changes to active and sending is unlocked.

curl -X POST https://peppol.verteco.digital/api/v1/companies/{id}/verification \
-H 'Authorization: Bearer vpt_8f2a…' -H 'Content-Type: application/json' \
-d '{"token":"<1024-hex VÚ>"}'

# 200 OK
{ "companyId":"08dd…","status":"active","sendingVerified":true,
"verificationMethod":"self","verifiedAt":"2026-06-15T…Z" }

Log of Peppol documents (received and sent) for a company. It fills up as invoices flow through the Access Point. Tied to company membership, sorted by createdAt descending.

curl 'https://peppol.verteco.digital/api/v1/companies/{id}/documents?direction=received' \
-H 'Authorization: Bearer vpt_8f2a…'
# 200 OK
[ { "id":"…","direction":"received","peppolMessageId":"…","docTypeId":"…",
  "senderId":"0088:7300010000001","receiverId":"0245:2121358349",
  "invoiceNumber":"2026001","issueDate":"2026-06-03",
  "currency":"EUR","totalAmount":120.00,"status":"received","createdAt":"…" } ]

SAPI-SK is the standardized national REST interface between a client/ERP system and an Access Point (sapi-sk.sk). We implement it in full. This means you are not tied to our proprietary API shape, and you write the integration once for any SAPI-SK Access Point.

Base URL

https://peppol.verteco.digital/sapi

Authentication

OAuth2 client_credentials → short-lived access token (JWT)

client_id

UUID of your API token (listed in the API tokens section / dashboard)

client_secret

the vpt_… token itself from the portal

Version

1.3 (10 operations: 4× auth, 6× documents)

Sandbox (trial environment)

Want to try SAPI-SK without registering and without any risk? Use the public sandbox credentials. The sandbox validates requests exactly like production, but never sends anything to the Peppol network and does not work with real data; it returns realistic mock responses. Ideal for development, CI and integration onboarding.

client_id

sandbox

client_secret

sandbox

send

full contract validation + mock 202 (nothing is delivered)

receive

1 sample document sandbox-doc-0001 for testing parsing and acknowledge

# 1) sandbox token (no registration required)
curl -X POST https://peppol.verteco.digital/sapi/auth/token \
-H 'Content-Type: application/json' \
-d '{ "client_id": "sandbox", "client_secret": "sandbox",
      "grant_type": "client_credentials" }'

# 2) mock send: it is validated, but NOTHING is actually delivered
curl -X POST https://peppol.verteco.digital/sapi/document/send \
-H 'Authorization: Bearer <sandbox access_token>' \
-H 'X-Peppol-Participant-Id: 0245:0000000000' \
-H 'Content-Type: application/json' \
-d '{ "metadata": { "documentId": "TEST-1",
        "documentTypeId": "urn:…::Invoice##…::2.1",
        "senderParticipantId": "0088:sandbox-sender",
        "receiverParticipantId": "0088:sandbox-receiver" },
      "payload": "<Invoice>…</Invoice>", "payloadFormat": "XML" }'
# 202 { "providerDocumentId": "sandbox-…", "status": "ACCEPTED", … }

# 3) sample inbox + detail of the sample document
curl https://peppol.verteco.digital/sapi/document/receive \
-H 'Authorization: Bearer <sandbox access_token>'
curl https://peppol.verteco.digital/sapi/document/receive/sandbox-doc-0001 \
-H 'Authorization: Bearer <sandbox access_token>'

Authentication

curl -X POST https://peppol.verteco.digital/sapi/auth/token \
-H 'Content-Type: application/json' \
-d '{ "client_id": "<token UUID>", "client_secret": "vpt_8f2a…",
      "grant_type": "client_credentials" }'
# 200 OK
{ "access_token": "eyJhbGciOi…", "token_type": "Bearer",
"expires_in": 900, "refresh_token": "eyJhbGciOi…" }

// body
{ "refresh_token": "eyJhbGciOi…" }

Sending a document

curl -X POST https://peppol.verteco.digital/sapi/document/send \
-H 'Authorization: Bearer eyJ…' \
-H 'X-Peppol-Participant-Id: 0245:2121358349' \
-H 'Idempotency-Key: 7b1f0e2a-…' \
-H 'Content-Type: application/json' \
-d '{ "metadata": {
        "documentId": "INV-2026-001",
        "documentTypeId": "urn:…::Invoice##…::2.1",
        "processId": "urn:…:bis:billing:3.0",
        "senderParticipantId": "0245:2121358349",
        "receiverParticipantId": "0088:7300010000001",
        "creationDateTime": "2026-06-17T10:00:00Z" },
      "payload": "<Invoice …>…</Invoice>",
      "payloadFormat": "XML" }'
# 202 Accepted
{ "providerDocumentId": "…", "status": "ACCEPTED",
"receivedAt": "2026-06-17T10:00:01Z", "timestamp": "…" }
# when status is "REJECTED", the response also carries a "detail" field
# with the rejection reason (validation rules, e.g. BR-CO-15)

curl -X POST https://peppol.verteco.digital/sapi/document/validate \
-H 'Authorization: Bearer eyJ…' \
-H 'Content-Type: application/xml' \
--data-binary @invoice.xml
# 200 OK
{ "valid": false,
  "errors": [ "BR-CO-15: Invoice total amount with VAT (BT-112) = … " ],
  "warnings": [],
  "checkedAt": "2026-09-10T12:00:00Z" }

Receiving documents

// 200 OK
{ "documents": [ { "documentId":"…","documentTypeId":"…",
  "senderParticipantId":"0088:…","receiverParticipantId":"0245:…",
  "creationDateTime":"2026-06-17T…Z" } ],
"nextPageToken": "50" }

Status of sent documents

// 200 OK
{ "documents": [ {
  "documentId": "…",
  "receiverParticipantId": "0245:1084695645",
  "peppolMessageId": "befc9112-…",
  "status": "delivered",
  "statusDateTime": "2026-07-09T14:52:31Z",
  "creationDateTime": "2026-07-09T14:52:12Z" } ],
"nextPageToken": null }

MLS receipt and delivery evidence

The MLS receipt (Peppol Message Level Status) is the receiving Access Point's answer to our transmission: AP = accepted and delivered, AB = delivered without business confirmation, RE = rejected with a reason. The portal stores it with the sent document and flips the status accordingly: AP and AB both mean delivered (with AB the statusDetail starts with "MLS AB: " and mls.responseCode is AB; under SPOG on MLS that is delivery without a business confirmation, not a reservation), RE means rejected. Under § 76a(2)(d) of Act 222/2004 the provider must be able to prove the date and time of sending, delivery and receipt; every row of GET /sapi/document/sent and every webhook carries those three times: sentAt (hand-over to the delivery service, which under § 85o(11) fulfils the issuer's duty), deliveredAt (the receiver's Access Point confirmed by MLS) and fsReportedAt (tax data reported to FS). A foreign Access Point may never send an MLS: the document then stays delivered with the detail as4_receipt_only and no receipt.

// 200 OK
{ "document": {
    "documentId": "…", "peppolMessageId": "befc9112-…", "status": "delivered",
    "sentAt": "2026-09-17T08:00:12Z", "deliveredAt": "2026-09-17T08:00:31Z", "fsReportedAt": null,
    "hasMls": true,
    "links": { "detail": "…/sapi/document/sent/…", "mls": "…/sapi/document/sent/…/mls" } },
  "mls": { "responseCode": "AP", "receivedAt": "2026-09-17T08:00:31Z", "url": "…/sapi/document/sent/…/mls" } }

FS report evidence, integrity and timeline (SAPI 1.8.14)

Since 1.8.14 every row of GET /sapi/document/sent, the sent detail and the received list/detail carry an fsReport object: state = reported (the report was handed to the C5 collection point, reportedAt = fsReportedAt), pending (the report is owed, the hand-over failed and is retried automatically, reason = c5_unavailable) or not_required (no report arises; reason says why: cross_border, self_send_test, issuer_without_vat_id, recipient_without_vat_id, not_billing_document, tdd_disabled, before_2026_09_01, not_recorded). After the hand-over tddMessageId (the report's SBDH InstanceIdentifier) appears and after C5 answers c5ResponseCode (AP/AB/RE), c5ResponseAt, c5Detail and the summary outcome: accepted (AP), accepted_with_reservations (AB), rejected (RE) or null until C5 answers. outcome = rejected means the report was handed over but the Financial Administration refused it (c5Detail carries the violated rule, e.g. BR-AE-08); state stays reported because the hand-over happened, and the portal re-sends the corrected report automatically (outcome becomes accepted once C5 accepts it). Sent rows also carry statusReason (a machine code behind statusDetail: network_retrying, network_retrying_sent, as4_receipt_only, recipient_not_registered, transport_failed, mls_rejected, validation_failed), xmlSha256 (SHA-256 of the handed-over XML, kept after the content wipe), retention and receiptRetention = permanent (the MLS receipt is never deleted). The receipt in the detail has mls.sha256 and mls.messageId. Received documents gained peppolMessageId, status (received/acknowledged), receivedAt, acknowledgedAt and xmlSha256 (SHA-256 of the business document bytes exactly as links.xml serves them, without the SBDH transport envelope; computed on receipt and kept after the content wipe). Both lists filter with ?fsReport=reported|pending|not_required|rejected (rejected = outcome rejected), sent also with ?status=undeliverable. The POST /sapi/document/send response carries peppolMessageId at acceptance. Everything is additive; existing fields are unchanged.

// POST { "documentIds": ["7c1e…", "9af0…", "unknown"] }  (max 200)
{ "documents": [ {
    "documentId": "7c1e…", "status": "delivered", "statusReason": null, "peppolMessageId": "befc9112-…",
    "sentAt": "2026-09-21T08:00:12Z", "deliveredAt": "2026-09-21T08:00:31Z", "fsReportedAt": "2026-09-21T08:05:40Z",
    "fsReport": { "state": "reported", "reportedAt": "2026-09-21T08:05:40Z", "reason": null, "outcome": "accepted",
                  "tddMessageId": "3f2a…", "c5ResponseCode": "AP", "c5ResponseAt": "2026-09-21T08:06:02Z", "c5Detail": null },
    "xmlSha256": "9b74…", "retention": { "mode": "storage", "contentAvailableUntil": null }, "receiptRetention": "permanent",
    "hasMls": true, "links": { "detail": "…", "mls": "…" },
    "mls": { "responseCode": "AP", "receivedAt": "2026-09-21T08:00:31Z", "url": "…", "sha256": "e1c0…", "messageId": "mls-…" } } ],
  "missing": ["9af0…", "unknown"] }

Batch sending

// request
{ "documents": [ {
  "itemId": "fa-2026-001",
  "idempotencyKey": "fa-2026-001",
  "metadata": { "documentId": "2026001", "documentTypeId": "…", "processId": "…",
                "senderParticipantId": "0245:2121358349", "receiverParticipantId": "0245:1084695645" },
  "payload": "<Invoice …>", "payloadFormat": "XML" } ] }

// 202 Accepted
{ "total": 2, "accepted": 1, "rejected": 1, "failed": 0,
"results": [
  { "itemId": "fa-2026-001", "ok": true,  "providerDocumentId": "…", "status": "ACCEPTED" },
  { "itemId": "fa-2026-002", "ok": false, "errorCode": "SAPI-AUTH-003", "errorMessage": "…" } ] }

Error model

All SAPI errors share a uniform envelope with a category, a stable code, a retryable flag and a correlation_id for support. On a credentials error (SAPI-AUTH-001) the envelope also carries hint (a human-readable explanation of what belongs into Client Id and Client Secret) and docs (a link to the guide; MK-soft programs are sent straight to /navody/mksoft#prepojenie). Both fields are optional and absent elsewhere (1.8.20).

{ "error": {
  "category": "AUTH",
  "code": "SAPI-AUTH-001",
  "message": "Invalid client credentials.",
  "retryable": false,
  "correlation_id": "b4191dfc-…" } }

For a received invoice we can notify the company by e-mail or by webhook (POST to your URL). Delivery is durable: it is stored in an outbound queue and delivered asynchronously (15 s timeout); on failure we retry up to 12× with exponential backoff (30 s → max 8 h, about 16 hours in total), then dead-letter. HTTP 401/403 means your endpoint requires an authentication we do not send; verify the webhook-signature header instead and answer 2xx. An outage of your server therefore does not lose the notification; we deliver it on the next attempt. SSRF protection blocks loopback/local addresses; the webhook URL must be public.

curl -X PUT https://peppol.verteco.digital/api/v1/companies/{id}/webhook \
-H 'Authorization: Bearer vpt_8f2a…' -H 'Content-Type: application/json' \
-d '{"url":"https://vas-system.sk/peppol/webhook"}'
# 200 OK { "url":"https://vas-system.sk/peppol/webhook", "hasSecret": true }

// 200 OK
{ "secret": "vpt_8f2a…" }

// 200 OK
{
"sent":     { "url": "https://vas-system.sk/peppol/webhook", "event": "webhook.test",
              "signed": true, "payload": "{…}" },
"received": { "status": 200, "body": "OK", "durationMs": 142, "error": null }
}
// 400 webhook_not_configured if no webhook URL is stored

Webhook payload

For both a received (invoice.received) and a sent (invoice.sent) invoice we send a POST with this body; the event field distinguishes the type.

Two further events announce the network's verdict on an invoice you have sent: invoice.delivered (the recipient's Access Point confirmed delivery with a delivery receipt (MLS)) and invoice.rejected (rejected, either by the network or during validation before sending); invoice.undeliverable reports a recipient without a record in the Peppol network (accepted, reported to the FS, not delivered). They carry the identification of the document and the company (documentId, invoiceNumber, receiverId, peppolMessageId, companyDic, peppolParticipantId) plus status, statusDetail with the rejection reason, and statusDateTime. If the first delivery attempt failed and the Access Point retries it on its own (usually within an hour), the document stays submitted and statusDetail starts with network_retrying: ; a delivery then yields delivered, giving up yields rejected with a network_gave_up: prefix. Thanks to them you do not need to poll for the status of sent invoices.

The company.activated event arrives when a customer completes provider selection on the portal (VPDS) of the Financial Administration of the Slovak Republic (Finančná správa, FS); body: event, companyId, companyDic, peppolParticipantId, status, verifiedAt. company.deactivated in turn arrives when a company is deregistered from the network (same body without verifiedAt). company.smp_registered_elsewhere arrives when a company completed the FS selection but its national SMP record is held by another provider (body as company.activated plus action: "migration_code_required" and migrateUrl). The partner procedure is in the intermediary documentation. Until the customer enters a migration code the network delivers to the old provider. Details in the guide /saas:

{
"event": "invoice.received",
"eventId": "7f1c2d9e-4b1a-4e3d-9c1f-0a2b3c4d5e6f",
"occurredAt": "2026-09-03T15:04:05Z",
"companyId": "08dd…",
"documentId": "…",
"invoiceNumber": "2026001",
"senderId": "0088:7300010000001",
"supplierName": "Dodávateľ s.r.o.",
"receiverId": "0245:2121358349",
"issueDate": "2026-06-03",
"dueDate": "2026-06-17",
"deliveryDate": "2026-06-03",
"currency": "EUR",
"totalAmount": "120.00",
"peppolMessageId": "…",
"companyDic": "SK2121358349",
"peppolParticipantId": "0245:2121358349"
}

The companyDic and peppolParticipantId fields identify the company the event relates to (important for partners that use a single webhook URL for all of their clients).

Network verdict on a sent invoice:

{
"event": "invoice.delivered",          // or "invoice.rejected"
"occurredAt": "2026-09-03T15:04:05Z",
"companyId": "08dd…",
"companyDic": "SK2121358349",
"peppolParticipantId": "0245:2121358349",
"documentId": "…",
"invoiceNumber": "2026001",
"receiverId": "0245:2120049096",
"peppolMessageId": "…",
"status": "delivered",                 // or "rejected"
"statusDetail": null,                  // for rejected: the rejection reason
"statusDateTime": "2026-06-03T10:15:42Z"
}

Company activation after provider selection on the FS portal (VPDS):

{
"event": "company.activated",          // company.deactivated has the same body without verifiedAt
"occurredAt": "2026-09-03T15:04:05Z",
"companyId": "08dd…",
"companyDic": "SK2121358349",
"peppolParticipantId": "0245:2121358349",
"status": "active",
"verifiedAt": "2026-06-03T10:02:11Z"
}

The event name is also carried in the X-Verteco-Event header. Full list of events: invoice.received, invoice.sent, invoice.delivered, invoice.rejected, invoice.undeliverable, invoice.reported, invoice.report_pending, invoice.report_rejected, company.activated, company.deactivated, company.smp_registered_elsewhere and the test event webhook.test. We recommend setting an unknown event type aside and logging it; we always announce a new type in advance. Every event also carries occurredAt (event time, ISO-8601 UTC) for ordering, and eventId (the same value as the X-Verteco-Delivery-Id header): unique per event and unchanged on every retry, so it is the right de-duplication key (peppolMessageId repeats across invoice.sent, invoice.delivered and invoice.reported). invoice.* events also carry the times sentAt, deliveredAt, receivedAt and fsReportedAt (ISO-8601 UTC, null until the fact exists). invoice.reported arrives when the tax report to the Financial Administration (TDD) for the document was handed to the delivery network (§ 85o par. 11), possibly days later during a C5 outage. Formal schemas of all events are in the webhooks section of the OpenAPI specification.

Signature verification

If the company has a secret, we send the X-Verteco-Signature header in the form sha256=HMAC-SHA256(secret, raw body) (lowercase hex). Always compute the HMAC over the exact bytes of the body:

import crypto from 'node:crypto';

// rawBody = the exact bytes of the request body (not re-serialized JSON)
function verify(rawBody, header, secret) {
const expected = 'sha256=' +
  crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
return crypto.timingSafeEqual(Buffer.from(header), Buffer.from(expected));
}

Headers of every delivery: X-Verteco-Event (event name), X-Verteco-Delivery-Id (= eventId in the body, identical on every retry), X-Verteco-Signature (the HMAC above) and, in parallel, the Standard Webhooks headers: webhook-id (= eventId), webhook-timestamp (unix seconds of this attempt) and webhook-signature = v1,base64(HMAC-SHA256(secret, id + "." + timestamp + "." + body)). The key is the UTF-8 bytes of your secret; a standardwebhooks library expects it as whsec_ + base64(secret). Recommended handling: verify the signature, refuse a delivery whose webhook-timestamp is older than 5 minutes (replay protection), process idempotently by eventId, answer 2xx within 15 seconds and defer heavy work to your own queue. A failed delivery is retried 12 times, 30 s to 8 h apart (about 16 hours in total); then it is dead-lettered with an e-mail alert and stays visible in the Realtime log. A production webhook URL must be https://; the test environment also accepts http://.

Bulk setup: one token, multiple companies

A single API token (bound to your account/e-mail) manages all companies it owns: whoever creates a company via POST /companies becomes its owner and can configure its webhook. The webhook is per company (its own URL and secret), so with the same token you can connect any number of companies:

# 1) list of your companies (paginated, see Companies)
curl 'https://peppol.verteco.digital/api/v1/companies?page=0&limit=100' -H 'Authorization: Bearer vpt_8f2a…'

# 2) for EACH company {id}: set the webhook (and/or e-mail)
curl -X PUT https://peppol.verteco.digital/api/v1/companies/{id}/notifications \
-H 'Authorization: Bearer vpt_8f2a…' -H 'Content-Type: application/json' \
-d '{"webhookUrl":"https://vas-system.sk/peppol/webhook","notificationEmail":"faktury@firma.sk"}'

# 3) fetch the signing secret (returned ONLY ONCE) and store it for signature verification
curl -X POST https://peppol.verteco.digital/api/v1/companies/{id}/webhook/secret -H 'Authorization: Bearer vpt_8f2a…'
# → { "secret": "…" }

• The token must be owner/admin of the given company; for a company where it is only member/viewer, it returns 403 forbidden (no cross-tenant access).
• You can give each company a different URL or the same one for all; in the payload you distinguish them by companyId (and receiverId).
• With hundreds of companies, respect the per-token rate limit (the current value is returned in the RateLimit-Limit header); batch with backoff on 429 (Retry-After header).
• The webhook is actually fired only once the company is active in Peppol (after selecting Verteco as provider with the Financial Administration) and therefore actually receives documents.

Fields of the objects returned by the API.

Company

Document

User · Token · Webhook

DIČ

Slovak tax identification number (10 digits). The Slovak Peppol ID is 0245: + the DIČ digits, without SK.

IČ DPH

VAT identification number (SK + DIČ). Only VAT payers have one; a non-payer issues with tax category O.

IČO

Company registration number (8 digits). Field ico in the API, BT-30 in UBL.

Verification token (VÚ)

A signature of the Financial Administration created when the taxpayer selects a provider on the FS portal; it unlocks sending for the company.

VPDS

The FS application where a taxpayer selects its delivery-service provider (us).

TDD

Tax Data Document, the invoice report to the Financial Administration; we build and send it for you.

C5 / C6

The fifth and sixth corner of the Peppol model: the Financial Administration’s access point that receives TDDs (0242:001180).

MLS

Message Level Status, the receipt from the recipient’s access point (AP = accepted, RE = rejected, AB = acknowledged).

SBDH

Standard Business Document Header, the envelope a document travels in; its InstanceIdentifier is the peppolMessageId.

SML / SMP

The network directory: SML finds the recipient’s SMP, the SMP says which access point and document types the recipient accepts.

Beyond Peppol BIS Billing 3.0, Slovak ERP and invoicing software vendors are gradually converging on a shared interpretation of optional fields (the discussion takes place in a Slack channel run by the Financial Administration of the Slovak Republic, Finančná správa, FS). Below are the conventions our portal already respects today: all of them are valid BIS constructs, they pass through our API unchanged, and received documents display them in the human-readable preview and PDF as well.

• Deduction of a taxed advance payment on a line: a negative line with cac:DocumentReference, where cbc:ID carries the number of the tax document for the received payment and cbc:DocumentTypeCode is 130 (BIS: invoice line object identifier, max. 1 per line). A received invoice with such a line is shown in our preview with the note „odpočet zálohy – daňový doklad č. …" (advance deduction, tax document no. …).
• Tax document for a received payment: according to the Financial Administration FAQ, the code InvoiceTypeCode 388 (Tax invoice) is used. It passes both our API and validation; the deduction of an unpaid (untaxed) advance is expressed via cbc:PrepaidAmount.
• Invoice cancellation: a credit note 381 (CreditNote) with cac:BillingReference to the original invoice, not a negative 380 invoice. Note: the network rejects code 384 for Slovak parties (rule PEPPOL-EN16931-P0112 allows it only between German entities); for an upward correction use debit note 383.
• BT-83 PaymentID: Slovak practice is converging on the payer reference format /VS…/SS…/KS…; a bare variable symbol (variabilný symbol) is also common. Our processing passes the value through unchanged and displays it with the payment details.
• Additional item data (batches, serial numbers, expiration dates) via cac:AdditionalItemProperty with established names such as BatchNumber, SerialNumber, ExpirationDate.

Attachments (PDF, images) can be attached to an e-invoice as base64 in the cac:AdditionalDocumentReference element (BT-125). For received documents we process attachments up to 25 MB each; when sending, the whole XML including base64 attachments must stay under 10 MB via SAPI-SK and under 2 MB via the portal tab Odoslať súborom. Peppol does not define a single network-wide limit; individual providers set their own (FS FAQ 9/DPH/2025/IM, example no. 67), so for very large attachments also check the limit of the other party's provider.

Two helper endpoints without authentication: the same validation core and the same SML lookup our Access Point uses. They are suitable for CI and for pre-send checks; a stricter public rate limit applies to them.

curl -X POST https://peppol.verteco.digital/api/v1/public/peppol-validate \
-H "Content-Type: application/xml" \
--data-binary @faktura.xml

// 200 OK
{
"valid": false,
"errors": [
  "BR-CO-09: [BR-CO-09]-The Seller VAT identifier (BT-31) … shall have a prefix in accordance with ISO code…"
],
"warnings": []
}
// 400 = empty body (empty_document) or document over 3 MB (document_too_large)

// 200 OK
{
"registered": true,
"participantId": "0245:2121358349",
"smp": "sml.peppol-smp.sk",
"capabilities": ["Faktúra (BIS Billing)", "Dobropis", "Self-billing", "MLS doručenky"], // Slovak labels: Invoice (BIS Billing), Credit note, Self-billing, MLS delivery receipts
"lastCheckedAt": "2026-08-31T…Z"
}

The portal runs its own server for the Model Context Protocol, the open standard through which AI assistants (Claude Code, Claude Desktop, Cursor, VS Code Copilot and others) connect to external systems. The assistant signs in with an ordinary API key of the account and gets six tools; it never sees more than that account and every call appears in the key's API log.

Address: https://peppol.verteco.digital/api/mcp. Transport: Streamable HTTP, JSON-RPC 2.0, stateless (POST /api/mcp, no SSE stream, GET answers 405). Sign-in with the header Authorization: Bearer <API key>. Supported methods: initialize, ping, tools/list, tools/call, resources/list, prompts/list.

Tools

• list_companies: the account's companies with Peppol ID, status and role (start of every conversation)
• list_documents: sent/received invoices of a company with delivery and tax-report state, paged
• get_document: one invoice in detail including the MLS receipt and tax report, optionally the UBL XML (up to 1 MB)
• check_participant: live recipient check in the Peppol network (SML)
• validate_document: UBL validation against EN 16931 + Peppol BIS 3.0
• send_document: send an invoice on behalf of the company, requires confirm = true and the Verifikačný údaj gate applies

Connecting in Claude Code

claude mcp add --transport http verteco-peppol https://peppol.verteco.digital/api/mcp \
  --header "Authorization: Bearer vpt_..."

Claude Desktop (through the mcp-remote bridge, needs Node.js)

{
  "mcpServers": {
    "verteco-peppol": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://peppol.verteco.digital/api/mcp", "--header", "Authorization: Bearer vpt_..."]
    }
  }
}

Sending an invoice is legally binding: the tool refuses a call without confirm = true and the server instructions tell the assistant to obtain the user's explicit consent to the exact invoice and recipient. Ready-made configurations for Cursor and VS Code and a button that creates the key are in the portal: API keys → MCP server tab. API keys → MCP server

In the portal a company switches on its own address <24 random characters>@peppol.send.verteco.app. An e-mail with a UBL XML attachment sent to that address from an allowed mailbox is sent through the Peppol network exactly as if the file had been uploaded on the Send by file tab; the sender gets one reply with the result per attachment and the document is in the portal and the API with its delivery status, MLS receipt and FS report. Set-up: Connections and integrations → Sending by e-mail (company owner or administrator, signed in). /dashboard/integrations/email

Processing rules

• Only mail from an address on the company's allow-list (up to 20) is accepted; everything else is discarded without a reply.
• By default the sender domain must pass SPF or DKIM at the delivering server (DMARC-style relaxed alignment). The delivering server additionally refuses mail that fails both SPF and DKIM and mail against the sender's DMARC policy. The check can be switched off in the settings; not recommended.
• Attachment: UBL 2.1 Invoice or CreditNote (Peppol BIS Billing 3.0), .xml extension, optionally in an SBDH envelope; at most 10 attachments per message, 15 MB per attachment, 200 messages per address per day. PDF and the message text are not processed.
• IFS Finvoice 2.0: an .xml attachment with the IFS SOAP envelope (IFSFinvoice) or a bare Finvoice is converted to UBL and then processed the same way. Conversion rules: INV02 or a negative total = credit note (381) with positive amounts and the preceding invoice reference (OriginalInvoiceNumber, with IFS OrderIdentifier); seller and buyer by their Slovak VAT id (SellerOrganisationTaxCode, BuyerOrganisationTaxCode → 0245:DIČ), a buyer outside Slovakia is not converted; VAT breakdown from VatSpecificationDetails, 0 % rows as category E with the reason from VatFreeText, otherwise “Oslobodené od DPH”; IFS tax-rounding rows (net 0,00, VAT 0,01) are dropped and a unit price that does not match the row net is recomputed; units per UN/ECE (kg → KGM, pcs → H87, h → HUR, unknown → C62 with the original text in the line note); the embedded invoice image (InvoiceAttachments, PDF) is attached to the document up to 5 MB; EUR only. The conversion result is stated in the reply and in the company log.
• Results address: when a system mailbox sends the invoices, choose another address for the reply with the results in the settings (replyTo in PUT /companies/{id}/email-send, empty = reply to the sender).
• The seller in the XML (supplier EndpointID, BT-34) must be this company, otherwise the message is rejected (a forwarded invoice from your own supplier is never sent as yours). The buyer must have an EndpointID with a scheme (BT-49).
• The same message (Message-ID) is processed once. The document carries origin = email in the API and webhooks, actor = the sender address.

Public health-check endpoint, suitable for monitoring.

// 200 OK
{ "service": "peppol-portal-backend", "status": "ok", "timestamp": "2026-06-17T…Z" }

A live overview of all components is available on the system status page.

Already in production (often assumed missing)

• POST /companies/{id}/documents/send is a stable portal interface; for ERP integrations SAPI-SK with Idempotency-Key remains the recommendation.
• SMP registration happens automatically after the FS portal selection; moving from another provider via POST /companies/{id}/smp-migrate with a migration code.
• MLS receipts, delivery evidence and FS reports (fsReport) on every /sapi/document/sent row; webhook replay for a time window.
• Keys limited to selected companies; MCP server for AI assistants; UBL samples on /vzory; public validator.

In preparation (ordered by integrator demand)

• Asynchronous batch: POST /sapi/document/batch answers 202 with a job link and per-item status.
• Change feed GET /sapi/document/changes?since&cursor with a cursor instead of offset paging.
• Key expiry and rotation in the portal, read-only keys.
• Several webhook endpoints per company with an event filter.