Rýchly štartQuickstart

Od prázdneho projektu k odoslanej faktúre.From empty project to a sent invoice.

1 min čítania1 min read

#token
#oauth
#odoslanie faktúry
#sapi
#curl

#token
#oauth
#send invoice
#sapi
#curl

Od prázdneho projektu k odoslanej faktúre. Príklady mierime na testovacie prostredie.

Získajte prístupový token

Vymeňte client_id a client_secret za token. Platnosť tokenu je uvedená v poli expires_in.

POST/sapi/auth/token

curl -X POST https://testpostman.slovakodata.com/sapi/auth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "'"$CLIENT_ID"'",
    "client_secret": "'"$CLIENT_SECRET"'"
  }'

# 200 OK
{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6...",
  "token_type": "Bearer",
  "expires_in": 900,
  "refresh_token": "KjxT9m..."
}

const BASE = "https://testpostman.slovakodata.com";

async function getToken(): Promise<string> {
  const res = await fetch(`${BASE}/sapi/auth/token`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      grant_type: "client_credentials",
      client_id: process.env.CLIENT_ID!,
      client_secret: process.env.CLIENT_SECRET!,
    }),
  });

  if (!res.ok) throw new Error(`Auth failed: ${res.status}`);

  const { access_token } = await res.json();
  return access_token;
}

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

const string Base = "https://testpostman.slovakodata.com";

async Task<string> GetTokenAsync(HttpClient http)
{
    var payload = new
    {
        grant_type = "client_credentials",
        client_id = Environment.GetEnvironmentVariable("CLIENT_ID")!,
        client_secret = Environment.GetEnvironmentVariable("CLIENT_SECRET")!,
    };

    using var content = new StringContent(JsonSerializer.Serialize(payload), Encoding.UTF8, "application/json");
    var res = await http.PostAsync($"{Base}/sapi/auth/token", content);
    res.EnsureSuccessStatusCode();

    var body = await res.Content.ReadFromJsonAsync<TokenResponse>();
    return body!.AccessToken;
}

record TokenResponse(
    [property: JsonPropertyName("access_token")] string AccessToken,
    [property: JsonPropertyName("expires_in")]  int ExpiresIn);

Odošlite faktúru

Telom požiadavky je JSON obálka — samotné UBL XML vložíte ako reťazec do poľa payload spolu s metadátami (identifikátory odosielateľa a príjemcu). Okrem tokenu posielate svoj Peppol identifikátor v hlavičke a idempotenčný kľúč.

POST/sapi/document/send

curl -X POST https://testpostman.slovakodata.com/sapi/document/send \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Peppol-Participant-Id: 0245:2020317068" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  --data-binary @envelope.json

# envelope.json — samotné UBL XML je reťazec v poli "payload"
{
  "metadata": {
    "documentId": "INV-2026-0001",
    "documentTypeId": "urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0::2.1",
    "processId": "urn:fdc:peppol.eu:2017:poacc:billing:01:1.0",
    "senderParticipantId": "0245:2020317068",
    "receiverParticipantId": "0245:1234567890",
    "creationDateTime": "2026-07-13T09:14:22Z"
  },
  "payload": "<Invoice ...>...</Invoice>",
  "payloadFormat": "XML"
}

# 202 Accepted — prijaté do spracovania
{
  "providerDocumentId": "9f2c1e84-3b7a-4d16-b0c5-1e8a72d40f31",
  "status": "ACCEPTED",
  "receivedAt": "2026-07-13T09:14:22.310Z"
}

import { randomUUID } from "node:crypto";
import { readFile } from "node:fs/promises";

async function sendInvoice(token: string, path: string) {
  const xml = await readFile(path, "utf8");

  const res = await fetch(`${BASE}/sapi/document/send`, {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${token}`,
      "X-Peppol-Participant-Id": "0245:2020317068",
      "Idempotency-Key": randomUUID(),
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      metadata: {
        documentId: "INV-2026-0001",
        documentTypeId:
          "urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0::2.1",
        processId: "urn:fdc:peppol.eu:2017:poacc:billing:01:1.0",
        senderParticipantId: "0245:2020317068",
        receiverParticipantId: "0245:1234567890",
        creationDateTime: new Date().toISOString(),
      },
      payload: xml,
      payloadFormat: "XML",
    }),
  });

  // 202 = prijaté. Výsledok doručenia príde webhookom.
  if (res.status !== 202) {
    const { error } = await res.json();
    throw new Error(`${error.code}: ${error.message}`);
  }

  return res.json();
}

async Task<string> SendInvoiceAsync(HttpClient http, string token, string path)
{
    var xml = await File.ReadAllTextAsync(path);

    var envelope = new
    {
        metadata = new
        {
            documentId           = "INV-2026-0001",
            documentTypeId       = "urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0::2.1",
            processId            = "urn:fdc:peppol.eu:2017:poacc:billing:01:1.0",
            senderParticipantId  = "0245:2020317068",
            receiverParticipantId = "0245:1234567890",
            creationDateTime     = DateTimeOffset.UtcNow,
        },
        payload       = xml,
        payloadFormat = "XML",
    };
    var json = JsonSerializer.Serialize(envelope);

    using var req = new HttpRequestMessage(HttpMethod.Post, $"{Base}/sapi/document/send")
    {
        Content = new StringContent(json, Encoding.UTF8, "application/json")
    };

    req.Headers.Authorization = new("Bearer", token);
    req.Headers.Add("X-Peppol-Participant-Id", "0245:2020317068");
    req.Headers.Add("Idempotency-Key", Guid.NewGuid().ToString());

    var res = await http.SendAsync(req);
    res.EnsureSuccessStatusCode();

    var body = await res.Content.ReadFromJsonAsync<SendResponse>();
    return body!.ProviderDocumentId;
}

Prijmite doručené faktúry

Zoznam prijatých dokumentov je stránkovaný kurzorom. Detail vráti JSON obálku — samotné XML je v poli payload a stav dokumentu v poli status.

curl "https://testpostman.slovakodata.com/sapi/document/receive?limit=20" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Peppol-Participant-Id: 0245:2020317068"

# 200 OK
{
  "documents": [
    {
      "documentId": "3c9a77f1-64de-4b02-9f7e-2a1c8d05b4e6",
      "documentTypeId": "urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0::2.1",
      "processId": "urn:fdc:peppol.eu:2017:poacc:billing:01:1.0",
      "senderParticipantId": "0245:1234567890",
      "receiverParticipantId": "0245:2020317068",
      "creationDateTime": "2026-07-13T08:02:11.004Z",
      "status": "RECEIVED"
    }
  ],
  "totalCount": 1,
  "nextPageToken": "eyJjIjoiMjAyNi0wNy0xM1QwODowMjoxMS4wMDRaIiwidCI6MTc..."
}

# Detail vráti JSON obálku — XML vyberieme z poľa payload
curl "$BASE/sapi/document/receive/3c9a77f1-64de-4b02-9f7e-2a1c8d05b4e6" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Peppol-Participant-Id: 0245:2020317068" | jq -r .payload > prijata.xml

curl -X POST "$BASE/sapi/document/receive/3c9a77f1-.../acknowledge" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Peppol-Participant-Id: 0245:2020317068"

From empty project to a sent invoice. Examples target the staging environment.

Get an access token

Exchange your client_id and client_secret for a token. Its lifetime is in the expires_in field.

POST/sapi/auth/token

curl -X POST https://testpostman.slovakodata.com/sapi/auth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "'"$CLIENT_ID"'",
    "client_secret": "'"$CLIENT_SECRET"'"
  }'

# 200 OK
{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6...",
  "token_type": "Bearer",
  "expires_in": 900,
  "refresh_token": "KjxT9m..."
}

const BASE = "https://testpostman.slovakodata.com";

async function getToken(): Promise<string> {
  const res = await fetch(`${BASE}/sapi/auth/token`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      grant_type: "client_credentials",
      client_id: process.env.CLIENT_ID!,
      client_secret: process.env.CLIENT_SECRET!,
    }),
  });

  if (!res.ok) throw new Error(`Auth failed: ${res.status}`);

  const { access_token } = await res.json();
  return access_token;
}

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

const string Base = "https://testpostman.slovakodata.com";

async Task<string> GetTokenAsync(HttpClient http)
{
    var payload = new
    {
        grant_type = "client_credentials",
        client_id = Environment.GetEnvironmentVariable("CLIENT_ID")!,
        client_secret = Environment.GetEnvironmentVariable("CLIENT_SECRET")!,
    };

    using var content = new StringContent(JsonSerializer.Serialize(payload), Encoding.UTF8, "application/json");
    var res = await http.PostAsync($"{Base}/sapi/auth/token", content);
    res.EnsureSuccessStatusCode();

    var body = await res.Content.ReadFromJsonAsync<TokenResponse>();
    return body!.AccessToken;
}

record TokenResponse(
    [property: JsonPropertyName("access_token")] string AccessToken,
    [property: JsonPropertyName("expires_in")]  int ExpiresIn);

Send an invoice

The request body is a JSON envelope — the UBL XML goes as a string into the payload field, alongside metadata (the sender and receiver participant IDs). Besides the token you also send your Peppol identifier in the header and an idempotency key.

POST/sapi/document/send

curl -X POST https://testpostman.slovakodata.com/sapi/document/send \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Peppol-Participant-Id: 0245:2020317068" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  --data-binary @envelope.json

# envelope.json — the UBL XML itself is a string in the "payload" field
{
  "metadata": {
    "documentId": "INV-2026-0001",
    "documentTypeId": "urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0::2.1",
    "processId": "urn:fdc:peppol.eu:2017:poacc:billing:01:1.0",
    "senderParticipantId": "0245:2020317068",
    "receiverParticipantId": "0245:1234567890",
    "creationDateTime": "2026-07-13T09:14:22Z"
  },
  "payload": "<Invoice ...>...</Invoice>",
  "payloadFormat": "XML"
}

# 202 Accepted — taken in for processing
{
  "providerDocumentId": "9f2c1e84-3b7a-4d16-b0c5-1e8a72d40f31",
  "status": "ACCEPTED",
  "receivedAt": "2026-07-13T09:14:22.310Z"
}

import { randomUUID } from "node:crypto";
import { readFile } from "node:fs/promises";

async function sendInvoice(token: string, path: string) {
  const xml = await readFile(path, "utf8");

  const res = await fetch(`${BASE}/sapi/document/send`, {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${token}`,
      "X-Peppol-Participant-Id": "0245:2020317068",
      "Idempotency-Key": randomUUID(),
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      metadata: {
        documentId: "INV-2026-0001",
        documentTypeId:
          "urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0::2.1",
        processId: "urn:fdc:peppol.eu:2017:poacc:billing:01:1.0",
        senderParticipantId: "0245:2020317068",
        receiverParticipantId: "0245:1234567890",
        creationDateTime: new Date().toISOString(),
      },
      payload: xml,
      payloadFormat: "XML",
    }),
  });

  // 202 = accepted. The delivery outcome arrives via webhook.
  if (res.status !== 202) {
    const { error } = await res.json();
    throw new Error(`${error.code}: ${error.message}`);
  }

  return res.json();
}

async Task<string> SendInvoiceAsync(HttpClient http, string token, string path)
{
    var xml = await File.ReadAllTextAsync(path);

    var envelope = new
    {
        metadata = new
        {
            documentId           = "INV-2026-0001",
            documentTypeId       = "urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0::2.1",
            processId            = "urn:fdc:peppol.eu:2017:poacc:billing:01:1.0",
            senderParticipantId  = "0245:2020317068",
            receiverParticipantId = "0245:1234567890",
            creationDateTime     = DateTimeOffset.UtcNow,
        },
        payload       = xml,
        payloadFormat = "XML",
    };
    var json = JsonSerializer.Serialize(envelope);

    using var req = new HttpRequestMessage(HttpMethod.Post, $"{Base}/sapi/document/send")
    {
        Content = new StringContent(json, Encoding.UTF8, "application/json")
    };

    req.Headers.Authorization = new("Bearer", token);
    req.Headers.Add("X-Peppol-Participant-Id", "0245:2020317068");
    req.Headers.Add("Idempotency-Key", Guid.NewGuid().ToString());

    var res = await http.SendAsync(req);
    res.EnsureSuccessStatusCode();

    var body = await res.Content.ReadFromJsonAsync<SendResponse>();
    return body!.ProviderDocumentId;
}

Receive inbound invoices

The inbound list is cursor-paginated. The detail endpoint returns a JSON envelope — the XML itself is in the payload field and the document status in the status field.

curl "https://testpostman.slovakodata.com/sapi/document/receive?limit=20" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Peppol-Participant-Id: 0245:2020317068"

# 200 OK
{
  "documents": [
    {
      "documentId": "3c9a77f1-64de-4b02-9f7e-2a1c8d05b4e6",
      "documentTypeId": "urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0::2.1",
      "processId": "urn:fdc:peppol.eu:2017:poacc:billing:01:1.0",
      "senderParticipantId": "0245:1234567890",
      "receiverParticipantId": "0245:2020317068",
      "creationDateTime": "2026-07-13T08:02:11.004Z",
      "status": "RECEIVED"
    }
  ],
  "totalCount": 1,
  "nextPageToken": "eyJjIjoiMjAyNi0wNy0xM1QwODowMjoxMS4wMDRaIiwidCI6MTc..."
}

# The detail endpoint returns a JSON envelope — pull the XML from payload
curl "$BASE/sapi/document/receive/3c9a77f1-64de-4b02-9f7e-2a1c8d05b4e6" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Peppol-Participant-Id: 0245:2020317068" | jq -r .payload > received.xml

curl -X POST "$BASE/sapi/document/receive/3c9a77f1-.../acknowledge" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Peppol-Participant-Id: 0245:2020317068"