Ako na to?

API Elektronického poštára

Pre Pohodu, Money, vlastný ERP alebo e-shop: váš program pošle e-faktúru do siete Peppol a prevezme prijaté faktúry cez jednoduché REST API s JSON. Program Alena nepotrebujete. Začnete v skúšobnom prostredí, kde sa doklady nikomu nedoručujú, a na ostrú prevádzku prepnete len adresu a kľúč.

Skúšobný kľúč pripravujeme OpenAPI (YAML)

Postup krok za krokom

  1. Skúšobný kľúč. Po prihlásení v Môj účet → Skúšobný prístup k API zadáte DIČ a názov programu a hneď dostanete kľúč. Nič neplatíte a nič sa nedoručuje.
  2. Overenie dokladu bez odoslania – POST /outbound/documents/validate vráti zoznam chýb podľa pravidiel Peppol BIS a slovenských pravidiel.
  3. Odoslanie – POST /outbound/documents; v skúšobnom prostredí si výsledok vyberiete príjemcom (doručené, odmietnuté, zlyhalo).
  4. Stav – GET /messages/{id} alebo webhook s overením podpisu.
  5. Prijaté faktúry – skúšobnú prijatú vytvoríte POST /sandbox/inbound, prevezmete ju ako v ostrej prevádzke a potvrdíte ack.
  6. Ostrý kľúč. Objednajte balík poštára; v Môj účet → Služby kliknete na Zobraziť kľúč API. V programe zmeníte adresu API a kľúč, volania sú rovnaké.

Adresy a kľúč

Ostrá prevádzkahttps://postar.seup.sk/api/v1
Kľúčv každom volaní hlavička Authorization: Bearer <kľúč>
FormátJSON (UTF-8), dokument faktúry ako UBL 2.1 podľa Peppol BIS Billing 3.0 zakódovaný v Base64
Váš účastníkiso6523-actorid-upis::0245:<DIČ> – DIČ firmy, 10 číslic bez SK (presný tvar je pri kľúči)
Odberateľ na Slovenskuiso6523-actorid-upis::0245:<DIČ odberateľa>
ČasyISO 8601 v UTC, napr. 2026-11-09T08:30:00Z
export POSTAR=https://postar.seup.sk/api/v1
export POSTAR_KLUC='…kľúč z portálu…'
curl "$POSTAR/usage" -H "Authorization: Bearer $POSTAR_KLUC"

Kľúč je heslo k vašej e-fakturácii: nedávajte ho do kódu na webe ani do e-mailu. Ak unikne, na portáli ho obnovte – starý prestane platiť hneď.

Skúšobné prostredie

Skúšobný kľúč funguje rovnako ako ostrý, ale doklady nikdy neodídu do siete Peppol – žiadne doručenie, potvrdenie od príjemcu ani hlásenie finančnej správe. Správy majú "simulated": true, limit je 200 odoslaných dokladov mesačne. Výsledok odoslania určuje príjemca:

Príjemca (receiverParticipantId)Výsledok
iso6523-actorid-upis::0245:0000000001SENT → REJECTED, v issues[] je MLS_REJECTED (príjemca odmietol)
iso6523-actorid-upis::0245:0000000002DEAD_LETTER (doručenie zlyhalo)
ktorýkoľvek inýSENT → DELIVERED

Neplatný doklad skončí INVALID s rovnakými chybami ako v ostrej prevádzke.

Skúšobná prijatá faktúra: POST /sandbox/inbound (len so skúšobným kľúčom, inak 403 sandbox_tenant_required). Telo je nepovinné – bez neho príde vzorová faktúra od 0245:0000000009 na vášho účastníka.

curl -X POST "$POSTAR/sandbox/inbound" \
  -H "Authorization: Bearer $POSTAR_KLUC" -H 'Content-Type: application/json' \
  -d '{"example": "credit-note"}'
Pole (všetky nepovinné)Hodnota
exampleinvoice (predvolené) alebo credit-note
receiverParticipantIdváš účastník (predvolene prvý)
senderParticipantIdodosielateľ, predvolene iso6523-actorid-upis::0245:0000000009
documentvlastný UBL v Base64 namiesto vzoru
documentTypeIdentifier, processIdentifierpri vlastnom dokumente; typ sa inak odvodí z koreňového elementu

Odpoveď 202 vráti prijatú správu; po kontrole dostane stav MLS_SENT (neplatná MLS_NEG_SENT) a webhook. Ďalej ju čítate bežnými volaniami príjmu.

Overenie dokladu bez odoslania

POST /outbound/documents/validate – rovnaké telo ako odoslanie, documentId je nepovinné. Nič sa neuloží, neodošle ani nezapočíta do limitu.

curl -X POST "$POSTAR/outbound/documents/validate" \
  -H "Authorization: Bearer $POSTAR_KLUC" -H 'Content-Type: application/json' \
  -d '{
    "senderParticipantId": "iso6523-actorid-upis::0245:2020123456",
    "receiverParticipantId": "iso6523-actorid-upis::0245:2020654321",
    "documentTypeIdentifier": "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",
    "processIdentifier": "urn:fdc:peppol.eu:2017:poacc:billing:01:1.0",
    "document": "'"$(base64 -w0 faktura.xml)"'"
  }'
{ "valid": false,
  "issues": [ { "code": "BR-CO-15", "severity": "error",
                "message": "Invoice total amount with VAT = total without VAT + VAT amount",
                "location": "/Invoice[1]" } ] }

valid je false práve vtedy, keď by odoslaný doklad skončil INVALID; v issues[] sú aj varovania ("severity": "warning"). Limit 60 overení za minútu na kľúč – potom 429 s "code": "validation_rate_limit" a hlavičkou Retry-After.

Odoslanie faktúry

POST /outbound/documents

PoleHodnota
senderParticipantIdváš účastník, iso6523-actorid-upis::0245:<vaše DIČ>
receiverParticipantIdúčastník odberateľa, na Slovensku iso6523-actorid-upis::0245:<DIČ odberateľa>
documentTypeIdentifierfaktúra: 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
dobropis: urn:oasis:names:specification:ubl:schema:xsd:CreditNote-2::CreditNote##urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0::2.1
processIdentifierurn:fdc:peppol.eu:2017:poacc:billing:01:1.0
documentIdčíslo dokladu vo vašom programe – podľa neho sa doklad nikdy neodošle dvakrát
documentUBL XML faktúry v Base64
curl -X POST "$POSTAR/outbound/documents" \
  -H "Authorization: Bearer $POSTAR_KLUC" -H 'Content-Type: application/json' \
  -d '{
    "senderParticipantId": "iso6523-actorid-upis::0245:2020123456",
    "receiverParticipantId": "iso6523-actorid-upis::0245:2020654321",
    "documentTypeIdentifier": "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",
    "processIdentifier": "urn:fdc:peppol.eu:2017:poacc:billing:01:1.0",
    "documentId": "FA2026001",
    "document": "'"$(base64 -w0 faktura.xml)"'"
  }'

Odpoveď 202 Accepted vráti stav dokladu s jeho id. Poštár doklad skontroluje, nájde odberateľa v sieti a doručí mu ho. Opakované podanie s rovnakým documentId vráti ten istý doklad – po výpadku ho teda môžete pokojne poslať znova. V vzorovej faktúre je predávajúci 0245:2020123456 – nahraďte ho vaším DIČ (element EndpointID predávajúceho aj senderParticipantId).

Kupujúci mimo siete Peppol (napr. občan): ako receiverParticipantId (aj EndpointID kupujúceho v dokumente) uveďte iso6523-actorid-upis::0245:9970300001. Doklad nikam neodíde – kupujúcemu ho doručíte sami (napr. e-mailom); poštár len nahlási údaje Finančnej správe, ak máte IČ DPH. Koncový stav je TDD_SENT (bez IČ DPH TDD_SKIPPED).

Stav dokladu

GET /messages/{id}

{
  "id": "3b9a6c1e-…",
  "direction": "OUTBOUND",
  "senderParticipantId": "iso6523-actorid-upis::0245:2020123456",
  "receiverParticipantId": "iso6523-actorid-upis::0245:2020654321",
  "documentId": "FA2026001",
  "state": "DELIVERED",
  "simulated": true,
  "receivedAt": "2026-11-09T08:30:00Z",
  "issues": []
}
StavVýznam pre odoslaný doklad
RECEIVED, VALIDATEDprijatý, kontroluje sa / skontrolovaný a čaká na odoslanie
SENT, TDD_REQUIRED_EVAL, TDD_SENT, TDD_SKIPPEDodoslaný poskytovateľovi odberateľa, čaká sa na potvrdenie; stavy TDD_* = hlásenie údajov Finančnej správe, ktoré robí poštár za vás
DELIVEREDodberateľ doklad prijal – hotovo
INVALIDdoklad nespĺňa pravidlá; v issues[] je zoznam chýb (code, message, location) – opravte a pošlite pod novým documentId
REJECTEDodberateľ doklad odmietol (MLS_REJECTED v issues[])
DEAD_LETTERdoručenie opakovane zlyhalo; v ostrej prevádzke ho riešime my a ozveme sa vám

Náhľad dokladu ako HTML: GET /messages/{id}/preview, pôvodné XML: GET /messages/{id}/payload.

Výpis: GET /messages?direction=OUTBOUND&state=DELIVERED&from=2026-11-01T00:00:00Z&limit=50. Filtre direction (OUTBOUND / INBOUND), state, documentId, from, to, unacknowledged=true, limit (predvolene 50). Odpoveď {"messages": [...], "nextCursor": "…"}; ďalšia strana s cursor=<nextCursor>, kým nextCursor nie je null. Zoradenie od najnovších.

Prijaté faktúry

Prijaté e-faktúry si program vyzdvihne sám v troch krokoch – napr. každých 5 minút alebo po webhooku:

# 1. neprevzaté prijaté faktúry
curl "$POSTAR/messages?direction=INBOUND&unacknowledged=true" -H "Authorization: Bearer $POSTAR_KLUC"

# 2. stiahnuť UBL XML každej z nich
curl "$POSTAR/messages/$ID/payload" -H "Authorization: Bearer $POSTAR_KLUC" -o prijata.xml

# 3. potvrdiť prevzatie – faktúra zmizne zo zoznamu neprevzatých
curl -X POST "$POSTAR/messages/$ID/ack" -H "Authorization: Bearer $POSTAR_KLUC"

Potvrdenie môžete bez obáv zopakovať (ak program spadol medzi stiahnutím a potvrdením). Potvrdenie doručenia odosielateľovi a hlásenie Finančnej správe posiela poštár sám hneď po prijatí – nečaká na vaše prevzatie. Prijímanie funguje aj po vyčerpaní mesačného limitu.

Čerpanie balíka: GET /usage → {"month": "2026-11", "sent": 42, "received": 17, "total": 59, "monthlyLimit": 100, "remaining": 41, "exhausted": false}. Do limitu balíka sa rátajú len odoslané doklady v kalendárnom mesiaci, príjem je vždy zadarmo.

Webhooky

Namiesto opakovaného pýtania sa môže poštár vášmu programu zmenu oznámiť sám. Adresu (https) zapnete pri kľúči na portáli (skúšobný prístup aj Služby); tam dostanete aj tajomstvo na overenie podpisu (zobrazí sa len raz, dá sa vymeniť).

SmerOznamované stavy
OUTBOUND (odoslané)INVALID, SENT, DELIVERED, REJECTED, DEAD_LETTER
INBOUND (prijaté)MLS_SENT = nová prijatá faktúra na prevzatie, MLS_NEG_SENT = prijatý doklad bol nečitateľný a odmietnutý, DEAD_LETTER
POST /vasa/adresa
Content-Type: application/json
X-Postar-Event: 0f1c2f1e-…
X-Postar-Timestamp: 1794213000
X-Postar-Signature: sha256=9f86d081…

{ "eventId": "0f1c2f1e-…", "messageId": "3b9a6c1e-…", "direction": "OUTBOUND",
  "state": "DELIVERED", "occurredAt": "2026-11-09T08:31:12Z" }

Webhook nesie len identifikátor a stav, nie obsah faktúry – podrobnosti si program vezme cez GET /messages/{messageId}. Overenie podpisu:

  1. Vezmite telo požiadavky presne tak, ako prišlo (bajty, nie znova zostavený JSON).
  2. Spočítajte HMAC-SHA256 tajomstvom nad reťazcom <X-Postar-Timestamp>.<telo>, výsledok ako malé hexadecimálne znaky s predponou sha256=.
  3. Porovnajte s hlavičkou X-Postar-Signature v konštantnom čase a odmietnite časovú pečiatku staršiu ako 5 minút.
  4. Odpovedzte 2xx do 5 sekúnd; pri chybe poštár volanie zopakuje, rovnaké eventId (X-Postar-Event) spracujte len raz.

Príklady PHP a C#

PHP – overenie, odoslanie a stav

<?php
$api = 'https://postar.seup.sk/api/v1';
$kluc = getenv('POSTAR_KLUC');

function postar(string $metoda, string $cesta, ?array $telo = null): array {
    global $api, $kluc;
    $ch = curl_init($api . $cesta);
    curl_setopt_array($ch, [
        CURLOPT_CUSTOMREQUEST => $metoda,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $kluc, 'Content-Type: application/json'],
        CURLOPT_POSTFIELDS => $telo === null ? null : json_encode($telo),
    ]);
    $odpoved = json_decode((string) curl_exec($ch), true) ?? [];
    $stav = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    if ($stav >= 400) {
        throw new RuntimeException("HTTP $stav: " . ($odpoved['detail'] ?? ''));
    }
    return $odpoved;
}

$doklad = [
    'senderParticipantId' => 'iso6523-actorid-upis::0245:2020123456',
    'receiverParticipantId' => 'iso6523-actorid-upis::0245:2020654321',
    'documentTypeIdentifier' => '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',
    'processIdentifier' => 'urn:fdc:peppol.eu:2017:poacc:billing:01:1.0',
    'documentId' => 'FA2026001',
    'document' => base64_encode(file_get_contents('faktura.xml')),
];

$kontrola = postar('POST', '/outbound/documents/validate', $doklad);
if (!$kontrola['valid']) {
    foreach ($kontrola['issues'] as $i) {
        echo "{$i['severity']} {$i['code']}: {$i['message']}\n";
    }
    exit(1);
}
$sprava = postar('POST', '/outbound/documents', $doklad);
sleep(5);
echo postar('GET', '/messages/' . $sprava['id'])['state'], "\n";   // napr. DELIVERED

PHP – overenie podpisu webhooku

<?php
$telo = file_get_contents('php://input');
$cas = $_SERVER['HTTP_X_POSTAR_TIMESTAMP'] ?? '';
$podpis = $_SERVER['HTTP_X_POSTAR_SIGNATURE'] ?? '';
$ocakavany = 'sha256=' . hash_hmac('sha256', $cas . '.' . $telo, getenv('POSTAR_WEBHOOK_TAJOMSTVO'));
if (!hash_equals($ocakavany, $podpis) || abs(time() - (int) $cas) > 300) {
    http_response_code(401);
    exit;
}
$udalost = json_decode($telo, true);
// … podľa $udalost['eventId'] spracovať len raz, napr. načítať GET /messages/{messageId}
http_response_code(204);

C# (.NET 8) – overenie, odoslanie a stav

using System.Net.Http.Headers;
using System.Net.Http.Json;
using System.Text.Json;

using var http = new HttpClient { BaseAddress = new Uri("https://postar.seup.sk/api/v1/") };
http.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("POSTAR_KLUC"));

var doklad = new
{
    senderParticipantId = "iso6523-actorid-upis::0245:2020123456",
    receiverParticipantId = "iso6523-actorid-upis::0245:2020654321",
    documentTypeIdentifier = "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",
    processIdentifier = "urn:fdc:peppol.eu:2017:poacc:billing:01:1.0",
    documentId = "FA2026001",
    document = Convert.ToBase64String(await File.ReadAllBytesAsync("faktura.xml")),
};

var kontrola = await (await http.PostAsJsonAsync("outbound/documents/validate", doklad))
    .EnsureSuccessStatusCode().Content.ReadFromJsonAsync<JsonElement>();
if (!kontrola.GetProperty("valid").GetBoolean())
{
    foreach (var i in kontrola.GetProperty("issues").EnumerateArray())
        Console.WriteLine($"{i.GetProperty("code")}: {i.GetProperty("message")}");
    return;
}

var sprava = await (await http.PostAsJsonAsync("outbound/documents", doklad))
    .EnsureSuccessStatusCode().Content.ReadFromJsonAsync<JsonElement>();
await Task.Delay(TimeSpan.FromSeconds(5));
var stav = await http.GetFromJsonAsync<JsonElement>($"messages/{sprava.GetProperty("id").GetString()}");
Console.WriteLine(stav.GetProperty("state").GetString());   // napr. DELIVERED

C# (ASP.NET Core) – overenie podpisu webhooku

using System.Security.Cryptography;
using System.Text;

app.MapPost("/postar/webhook", async (HttpRequest req) =>
{
    using var ms = new MemoryStream();
    await req.Body.CopyToAsync(ms);
    var telo = ms.ToArray();
    var cas = req.Headers["X-Postar-Timestamp"].ToString();
    var podpis = req.Headers["X-Postar-Signature"].ToString();

    if (!long.TryParse(cas, out var sekundy)
        || Math.Abs(DateTimeOffset.UtcNow.ToUnixTimeSeconds() - sekundy) > 300)
        return Results.Unauthorized();

    var tajomstvo = Encoding.UTF8.GetBytes(Environment.GetEnvironmentVariable("POSTAR_WEBHOOK_TAJOMSTVO")!);
    var data = Encoding.UTF8.GetBytes(cas + ".").Concat(telo).ToArray();
    var ocakavany = "sha256=" + Convert.ToHexString(HMACSHA256.HashData(tajomstvo, data)).ToLowerInvariant();
    if (!CryptographicOperations.FixedTimeEquals(Encoding.ASCII.GetBytes(ocakavany), Encoding.ASCII.GetBytes(podpis)))
        return Results.Unauthorized();

    // … udalosť podľa X-Postar-Event spracovať len raz
    return Results.NoContent();
});

Chyby a limity

Chyby majú tvar application/problem+json: {"title": "…", "status": 400, "detail": "…"}, kde to pomôže, aj so strojovým code.

KódKedy
400chýbajúce pole, document nie je Base64, neplatný účastník alebo example
401chýba kľúč, je neplatný, obnovený, zrušený alebo služba skončila
403 sandbox_tenant_required/sandbox/inbound s ostrým kľúčom
404doklad neexistuje alebo nie je váš; senderParticipantId nie je váš účastník
409 sandbox_disabledskúšobné prostredie je na tomto poštárovi vypnuté
429 monthly_document_limitvyčerpaný mesačný limit odoslaných dokladov (used, monthlyLimit); balíky s doplatkom za doklad nad limit sa nezastavia, prijímanie beží vždy
429 validation_rate_limitviac ako 60 overení za minútu – počkajte podľa hlavičky Retry-After
429 s Retry-Afterpriveľa volaní za krátky čas – počkajte uvedený počet sekúnd

Na stiahnutie

Pomoc

Otázky k pripojeniu vášho programu: support@seup.sk. Uveďte DIČ firmy a id dokladu, nikdy nie kľúč.