Poštár

Dokumentace API

Jak začít jako dodavatel SaaS

  1. Zaregistrujte se na https://app.peppos.cz/register.
  2. Otevřete Nastavení / Klíče API, vyberte Pouze tenant a nastavte oprávnění.
  3. Vytvořit účastníka: POST https://api.peppos.cz/api/participants?autoregister=true.
  4. Zahájit ověření: POST https://api.peppos.cz/api/participants/{participantId}/verify/initiate?callback=https%3A%2F%2Fyour-saas.example.com%2Fverification%2Fdone. Vrácené verificationUrl otevře proces registrace a přesměruje zpět na adresu URL zpětného volání, když uživatel skončí nebo zruší.
  5. Zkontrolujte stav ověření: GET https://api.peppos.cz/api/participants/{participantId}/verify/status.
  6. Zaregistrujte se v Peppol: POST https://api.peppos.cz/api/participants/{participantId}/peppol/register. (Tento krok lze přeskočit, pokud jste v prvním kroku použili ?autoregister=true.)
  7. Zaregistrujte webhooky: POST https://api.peppos.cz/api/participants/{participantId}/webhooks.
  8. Odesílejte dokumenty a používejte koncové body doručené pošty.

Všechny příklady koncových bodů níže používají absolutní adresy URL s produkční doménou.

const CLIENT_ID = process.env.CLIENT_ID!;
const CLIENT_SECRET = process.env.CLIENT_SECRET!;

async function getAccessToken(): Promise<string> {
  const res = await fetch('https://api.peppos.cz/api/auth/token', {
    method: 'POST',
    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
    body: new URLSearchParams({
      grant_type: 'client_credentials',
      client_id: CLIENT_ID,
      client_secret: CLIENT_SECRET,
      scope: 'admin',
    }),
  });
  if (!res.ok) throw new Error(`Token error: ${await res.text()}`);
  const { access_token } = await res.json();
  return access_token;
}

const token = await getAccessToken();

const headers = {
  Authorization: `Bearer ${token}`,
  'Content-Type': 'application/json',
};

async function jsonFetch(url: string, init: RequestInit = {}) {
  const res = await fetch(url, {
    ...init,
    headers: { ...headers, ...(init.headers ?? {}) },
  });
  if (!res.ok) throw new Error(`HTTP ${res.status}: ${await res.text()}`);
  return res.json();
}

const participant = await jsonFetch('https://api.peppos.cz/api/participants?autoregister=true', {
  method: 'POST',
  body: JSON.stringify({
    name: 'Firma s.r.o.',
    registrationNumber: '123',
    vatId: 'CZ123',
    countryCode: 'cz',
  }),
});

const participantId = participant.id; // or 9929:123
const callback = encodeURIComponent('https://your-saas.example.com/verification/done');

const verification = await jsonFetch(
  `https://api.peppos.cz/api/participants/${participantId}/verify/initiate?callback=${callback}`,
  { method: 'POST' },
);
console.log('Verification URL:', verification.verificationUrl);

const status = await jsonFetch(`https://api.peppos.cz/api/participants/${participantId}/verify/status`);
console.log('Verification status:', status);

await jsonFetch(`https://api.peppos.cz/api/participants/${participantId}/peppol/register`, { method: 'POST' });

await jsonFetch(`https://api.peppos.cz/api/participants/${participantId}/webhooks`, {
  method: 'POST',
  body: JSON.stringify({
    url: 'https://your-saas.example.com/webhooks/peppol',
    events: ['document.received', 'document.status.changed'],
  }),
});

# Send document and wait for processing result. You can repeat this request on error until you get a successful response if processing takes too long.
await jsonFetch(`https://api.peppos.cz/api/participants/${participantId}/documents/send?wait-for-result`, {
  method: 'PUT',
  body: 'XML PAYLOAD HERE',
});

const inbox = await jsonFetch(`https://api.peppos.cz/api/participants/${participantId}/documents/inbox`);
for (const doc of inbox.items ?? []) {
  await jsonFetch(`https://api.peppos.cz/api/documents/${doc.id}/acknowledge`, { method: 'POST' });
}