E-invoicing in Slovakia: simple and in plain language

You do not need to be a technician. If you are a sole trader, a limited company (s. r. o.) or an accountant, our portal in your browser is all you need: you receive and issue invoices by clicking, no programming required. This is how it works in three steps:

1. 1

   Sign up (free of charge)

   Create an account with your e-mail on the registration page. Receiving invoices is free of charge (up to 1000 per month).

2. 2

   Select us on the Financial Administration portal

   To be able to receive e-invoices, choose us as your certified provider (digital postman, digitálny poštár) on the FS portal (VPDS) of the Financial Administration of the Slovak Republic (Finančná správa, FS); the selection is confirmed via eID. We then register you in the Peppol network automatically and send you a login e-mail.

3. 3

   Receive and issue invoices

   Received invoices arrive in the portal and by e-mail. You issue an invoice in the simple editor (like in Word), or duplicate an existing invoice in a few clicks. We send the tax report to the Financial Administration (TDD) on your behalf automatically.

Detailed guides (in Slovak, for beginners):

All guides in one place: E-invoicing Guide.

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();

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 eID; 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 provider selection via eID

Validation

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

Delivery

simulated: the document never leaves the test server; if the recipient (VAT ID) exists in the test environment, the invoice is delivered to it as a received invoice (including the e-mail, PDF and webhook)

Delivery receipt (MLS)

simulated, explicitly marked as SANDBOX

E-mails

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

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.

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 on every request (Java: conn.setRequestProperty("User-Agent", "my-app/1.0"); -Dhttp.agent alone is not enough, Java appends Java/1.8 to it). Common clients (requests, httpx, Java 11+, 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 via slovensko.sk (eID), 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.

If you run an invoicing app, an ERP or a platform and want to connect several of your customers (tenants) to Peppol through us, you integrate once and serve N companies. The model is a proxy: your backend holds one API token (vpt_…) server-side only (never in the browser), and each of your tenants = one company with us (one token → N companies). The extended public guide with sample code, webhook signatures and a go-live checklist: peppol.verteco.digital/saas.

1. 1

   One token, server-side

   Create an API token and keep it in a secured backend environment. All calls are made by your server (Bearer), not by the customer's browser.
2. 2

   Tenant onboarding = creating a company

   For each customer, call POST /companies with their company registration number (IČO) / VAT ID (IČ DPH); it returns { id, status: "pending_verification" }; store the id with the tenant (for details see Companies).

   bashKopírovať

   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":"Firma s.r.o.",
          "street":"Príkladná 12","postalCode":"010 01","city":"Žilina","iban":"SK…"}'

3. 3

   Activation in Peppol (a step the customer takes with the state)

   pending_verification ≠ live in Peppol. For a company to receive, the customer must select Verteco as their provider on the portal of the Financial Administration of the Slovak Republic (Finančná správa, FS), using eID; we then register the company in the SMP and its status changes to active. For a company to send, submit its verification token (Verifikačný údaj) via Sending verification (POST /companies/{id}/verification).
4. 4

   Receiving invoices: webhook per tenant

   Set up a webhook (and/or e-mail) for each company and fetch the signing secret:

   bashKopírovať

   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://vasa-saas.sk/peppol/webhook","notificationEmail":"…"}'
   
   curl -X POST https://peppol.verteco.digital/api/v1/companies/{id}/webhook/secret -H 'Authorization: Bearer vpt_8f2a…'
   # → { "secret": "…" }   (store it to verify X-Verteco-Signature)

   When an invoice is received, you get a signed POST (event invoice.received), durable with retry/dead-letter. For signature verification, the payload and the „Otestovať webhook" (Test webhook) button, see Notifications & webhooks.
5. 5

   Sending invoices

   Send the invoice (UBL Peppol BIS 3.0) through the national interface SAPI-SK 1.0: POST /sapi/document/send (OAuth2 client_credentials, client_secret = your vpt_ token). We add the Slovak tax report (TDD/C5) automatically.
6. 6

   Usage data for re-invoicing

   GET /companies/usage?month=YYYY-MM returns the counts of sent and received documents for each of your companies separately as well as in total, in exactly the units the price list is built on, so you can re-invoice your clients directly from it. Without the parameter it returns the current month; the period is half-open and the response explicitly contains the from/to fields so you do not have to guess the month boundary. Companies with no traffic are listed with zeros.
7. 7

   Scaling and robustness

   Paginate lists: GET /companies?page&limit as well as GET /companies/{id}/documents?page&limit (with headers such as X-Total-Count and others). Respect the per-token rate limit: during bulk onboarding, batch with backoff on 429 (Retry-After) and handle 409 ico_taken (idempotently).

If you are registered as an intermediary (sprostredkovateľ) (application via /sprostredkovatel), the Financial Administration of the Slovak Republic (Finančná správa, FS) sends a notification to your webhook URL every time a client selects you on the FS portal (VPDS). This manual describes the exact contractas FS actually calls it in production (verified on live selections). FS does not publish its own public manual for the webhooks; this is what you need for the implementation.

1 · What the notification looks like + 2 · authenticity verification

3 · What to do with it: forward the raw body to us

The recommended (and simplest) implementation is a raw-byte proxy: accept the POST, respond quickly, and forward the raw body bytes to your registration endpoint with us. That endpoint is created automatically once you fill in the /sprostredkovatel form, it is active immediately, and you can see its exact URL (with your key) after logging in via GET /api/v1/resellers/me:

POST https://peppol.verteco.digital/peppol/webhook/reseller/{vas-kluc}
Content-Type: application/json
(body = the unchanged raw bytes from FS)

We cryptographically verify the verification_token, automatically create the company under your partner account (white-label), register it in the central SK SMP, and from that moment on we deliver e-invoices to it. You may store the contact details from the payload for your own onboarding; nothing more is needed.

4 · Operating rules (important)

• Idempotency: the same entity may repeat the selection; processing the same DIČ (Slovak tax identification number) must be safe (it is on our side).
• Source IP: calls come from FS infrastructure (observed from 194.1.2.13); we recommend an IP allowlist only as a supplement, not as the sole protection (FS does not guarantee the range).
• Response: return 200 even on an internal processing error (log the error yourself); FS does not evaluate anything else.
• Deployment order: the webhook must be live before the application is filed with FS; the first selection may arrive shortly after publication.

A reference proxy implementation is ~30 lines (accept POST → store → forward the raw bytes). If you want to verify the whole chain before FS publishes you, send a test POST to your registration endpoint; it responds safely to unknown/unsigned content and creates nothing. Questions: Support.

5 · Terminating the intermediary agreement

The intermediary agreement can also be terminated directly from within the application: the owner of the partner account, in Nastavenia poštára (Postman settings), fills in a termination request (control question + confirmation of the consequences) and confirms the notice via a link sent to them by e-mail. Upon confirmation the notice is deemed delivered; the notice period is one month and runs from the 1st day of the following month (Art. 7.1 of the Terms and Conditions of Intermediation). We file the request for removal from the list of intermediaries with the Financial Administration ourselves within 5 business days after the agreement ends (Art. 7.3); our team receives the supporting record, nothing is sent to the intermediary's clients. An unconfirmed request can be cancelled in the application. Programmatically: GET/POST/DELETE /api/v1/resellers/me/termination.

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

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

409

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

429

rate limit exceeded

Complete error catalog

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." }

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)

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 }

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.

{ "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 8× with exponential backoff (30 s → max 1 h), then dead-letter. 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). 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. 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); details in the guide /saas:

{
  "event": "invoice.received",
  "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"
  "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
  "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, company.activated, company.deactivated 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.

Partner notification webhook (intermediaries)

If you are a registered intermediary (sprostredkovateľ), you do not need to configure a webhook for each company separately: a single partner notification webhook receives all events of the companies under your partner account and takes precedence over the webhooks of individual companies. Your clients therefore configure nothing; you distinguish the company by companyDic / peppolParticipantId.

// 200 OK (first setup)
{ "url": "https://vasa-appka.sk/peppol/events", "secret": "vpt_…", "hasSecret": true,
  "events": ["company.activated","company.deactivated","invoice.received","invoice.sent","invoice.delivered","invoice.rejected"] }

The X-Verteco-Signature signature is computed the same way as for the company webhook (below), only with the partner secret.

Managing clients via the API (unilateral release and sending brake)

A client who leaves a partner usually does nothing, which is why these operations are unilateral and require no cooperation from the client. Invoice reception is not affected by them: it is tied to the company's registration in the central SMP, not to the managing account.

Partner billing model

In the partner console (and via GET/PUT /api/v1/resellers/me/billing) you choose the billing model (the choice is available only to registered intermediaries): per_company = €2 per month per actively sending company registration number (IČO), or per_document = €0.01 for every invoice sent by your companies (received documents are free) with a minimum monthly billing of €300 + VAT. A model change always takes effect from the 1st day of the following month (in the response pendingModel and pendingFrom); the response of both calls also returns a recalculation of the current month under both models, so you switch informed.

Recommended procedure for a terminated client (a cap on costs on your side): you can see current usage in GET /api/v1/companies/usage?month=YYYY-MM (sent/received breakdown per company, exactly for re-billing) and in GET /api/v1/resellers/me/clients (counts for the current month); in addition, an event is sent to the partner webhook for every document your companies send or receive, so you catch a "terminated" company at its very first document. Then simply call pause-sending or release.

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));
}

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

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). Our limit is 25 MB per attachment. 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/SMP 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"
}

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.

• POST/companies/{id}/peppol/register· Manual registration in the Peppol SMP via the API. Today this happens automatically upon provider selection on the FS portal (VPDS) of the Financial Administration of the Slovak Republic (Finančná správa, FS).

Want early access to the integration, a sandbox, or have a question? Get in touch directly:

Your Peppol contact

Miriama Mrkávková

+421 944 488 269·peppol​@​verteco.digital