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
- Adresy a kľúč
- Skúšobné prostredie
- Overenie
- Odoslanie
- Stav dokladu
- Prijaté faktúry
- Webhooky
- Príklady PHP a C#
- Chyby a limity
- Na stiahnutie
Postup krok za krokom
- 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.
- Overenie dokladu bez odoslania –
POST /outbound/documents/validatevráti zoznam chýb podľa pravidiel Peppol BIS a slovenských pravidiel. - Odoslanie –
POST /outbound/documents; v skúšobnom prostredí si výsledok vyberiete príjemcom (doručené, odmietnuté, zlyhalo). - Stav –
GET /messages/{id}alebo webhook s overením podpisu. - Prijaté faktúry – skúšobnú prijatú vytvoríte
POST /sandbox/inbound, prevezmete ju ako v ostrej prevádzke a potvrdíteack. - 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ádzka | https://postar.seup.sk/api/v1 |
|---|---|
| Kľúč | v každom volaní hlavička Authorization: Bearer <kľúč> |
| Formát | JSON (UTF-8), dokument faktúry ako UBL 2.1 podľa Peppol BIS Billing 3.0 zakódovaný v Base64 |
| Váš účastník | iso6523-actorid-upis::0245:<DIČ> – DIČ firmy, 10 číslic bez SK (presný tvar je pri kľúči) |
| Odberateľ na Slovensku | iso6523-actorid-upis::0245:<DIČ odberateľa> |
| Časy | ISO 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:0000000001 | SENT → REJECTED, v issues[] je MLS_REJECTED (príjemca odmietol) |
iso6523-actorid-upis::0245:0000000002 | DEAD_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 |
|---|---|
example | invoice (predvolené) alebo credit-note |
receiverParticipantId | váš účastník (predvolene prvý) |
senderParticipantId | odosielateľ, predvolene iso6523-actorid-upis::0245:0000000009 |
document | vlastný UBL v Base64 namiesto vzoru |
documentTypeIdentifier, processIdentifier | pri 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
| Pole | Hodnota |
|---|---|
senderParticipantId | váš účastník, iso6523-actorid-upis::0245:<vaše DIČ> |
receiverParticipantId | účastník odberateľa, na Slovensku iso6523-actorid-upis::0245:<DIČ odberateľa> |
documentTypeIdentifier | faktú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.1dobropis: 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 |
processIdentifier | urn: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 |
document | UBL 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": []
} | Stav | Význam pre odoslaný doklad |
|---|---|
RECEIVED, VALIDATED | prijatý, kontroluje sa / skontrolovaný a čaká na odoslanie |
SENT, TDD_REQUIRED_EVAL, TDD_SENT, TDD_SKIPPED | odoslaný 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 |
DELIVERED | odberateľ doklad prijal – hotovo |
INVALID | doklad nespĺňa pravidlá; v issues[] je zoznam chýb (code, message, location) – opravte a pošlite pod novým documentId |
REJECTED | odberateľ doklad odmietol (MLS_REJECTED v issues[]) |
DEAD_LETTER | doruč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ť).
| Smer | Oznamované 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:
- Vezmite telo požiadavky presne tak, ako prišlo (bajty, nie znova zostavený JSON).
- Spočítajte HMAC-SHA256 tajomstvom nad reťazcom
<X-Postar-Timestamp>.<telo>, výsledok ako malé hexadecimálne znaky s predponousha256=. - Porovnajte s hlavičkou
X-Postar-Signaturev konštantnom čase a odmietnite časovú pečiatku staršiu ako 5 minút. - Odpovedzte
2xxdo 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ód | Kedy |
|---|---|
400 | chýbajúce pole, document nie je Base64, neplatný účastník alebo example |
401 | chýba kľúč, je neplatný, obnovený, zrušený alebo služba skončila |
403 sandbox_tenant_required | /sandbox/inbound s ostrým kľúčom |
404 | doklad neexistuje alebo nie je váš; senderParticipantId nie je váš účastník |
409 sandbox_disabled | skúšobné prostredie je na tomto poštárovi vypnuté |
429 monthly_document_limit | vyč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_limit | viac ako 60 overení za minútu – počkajte podľa hlavičky Retry-After |
429 s Retry-After | priveľa volaní za krátky čas – počkajte uvedený počet sekúnd |
Na stiahnutie
- postar-klient-openapi.yaml – špecifikácia OpenAPI 3.1 klientskeho API (generátory klientov, Postman, Insomnia).
- faktura.xml – vzorová faktúra Peppol BIS 3.0 (predávajúci
0245:2020123456, kupujúci0245:2020654321), prejde overením. - dobropis.xml – vzorový dobropis k faktúre FA2026001.
Pomoc
Otázky k pripojeniu vášho programu: support@seup.sk. Uveďte DIČ firmy a id dokladu, nikdy nie kľúč.