Dokumentace API

Tlačítko Odeslat přes Peppol

Dejte svým uživatelům možnost odesílat dokumenty přímo přes síť Peppol z vašeho webu — jedním tlačítkem. CDN skript badge-sender.js vykreslí tlačítko „Doručit přes Peppol", jehož kliknutím přesměruje na hostovanou stránku web-sender, kde proběhne celé odeslání.

Potřebujete affiliate token (UUID), který získáte v aplikaci v sekci Nastavení → Affiliate. Token identifikuje vašeho účastníka a umožní zobrazení tlačítka.

Jak to funguje

1. Na stránce vykreslíte tlačítko s UUID affiliate tokenu, URL dokumentu faktury (dostupné z internetu) a formátem (např. isdoc, pdf, zugferd).
2. Uživatel klikne na tlačítko — přesměruje se na web-sender na adrese https://app.peppos.cz/web-sender.
3. Web-sender ověří affiliate token, případně vyzve uživatele k přihlášení, stáhne a automaticky rozpozná formát dokumentu (ISDOC, ISDOCX, PDF+ISDOC, ZUGFeRD, Factur-X), zkontroluje, zda je příjemce registrován v síti Peppol, a zobrazí potvrzovací dialog.
4. Uživatel potvrdí a dokument je odeslán přes síť Peppol.

Varianta 1 — HTML atributy data-* (nejjednodušší)

Vložte kontejnerový prvek a přidejte atributy data-* přímo na tag <script>. Skript se automaticky inicializuje po načtení.

<!-- 1. Place a container where the button should appear -->
<div id="peppol-send-btn"></div>

<!-- 2. Load the CDN script with data attributes -->
<script
  src="https://app.peppos.cz/cdn/badge-sender.js"
  data-target="peppol-send-btn"
  data-affiliate-id="YOUR-AFFILIATE-UUID"
  data-url="https://your-server.example/invoice.isdoc"
></script>

Varianta 2 — JavaScript API

Pro větší kontrolu (např. dynamické URL, více tlačítek) zavolejte pepposhShowSendBadge() přímo.

<!-- 1. Container element -->
<div id="peppol-send-btn"></div>

<!-- 2. Load script (no data- attributes needed) -->
<script src="https://app.peppos.cz/cdn/badge-sender.js"></script>

<!-- 3. Call the API -->
<script>
  pepposhShowSendBadge({
    targetId:    "peppol-send-btn",
    affiliateId: "YOUR-AFFILIATE-UUID",
    url:         "https://your-server.example/invoice.isdoc",
    lang:        "cs", // optional: force badge/web-sender language
  });
</script>

Varianta 3 — Inline data (bez veřejné URL)

Pokud vaše dokumenty nejsou veřejně dostupné (např. za autentizací nebo na privátním serveru), můžete obsah dokumentu vložit přímo do URL tlačítka pomocí volby inline / atributu data-inline. Dokument je komprimován metodou deflate-raw a zakódován jako base64url.

Typická ISDOC XML faktura (10–20 KB) se zkomprimuje na 2–5 KB. Vyhněte se inline módu pro dokumenty větší než cca 50 KB.

// Node.js — encode document for inline delivery (no external libraries needed)
// Compression uses Node.js built-in 'zlib'; base64url needs no helper either.
const zlib = require('node:zlib');

/**
 * Compress a document buffer and return a base64url string.
 * Deflate-raw is supported natively by both Node.js and modern browsers.
 */
function encodeInlineDocument(buffer) {
  const compressed = zlib.deflateRawSync(buffer);
  return compressed
    .toString('base64')
    .replace(/\+/g, '-')   // base64url: + → -
    .replace(/\//g, '_')   //             / → _
    .replace(/=/g,  '');   //  strip padding
}

// Usage example:
const fs = require('fs');
const inlineData = encodeInlineDocument(fs.readFileSync('invoice.isdoc'));
// inlineData is now safe to embed directly in a URL or HTML attribute.

<!-- Inline mode: document content is embedded directly — no server URL needed -->
<div id="peppol-send-btn"></div>

<script
  src="https://app.peppos.cz/cdn/badge-sender.js"
  data-target="peppol-send-btn"
  data-affiliate-id="YOUR-AFFILIATE-UUID"
  data-inline="<!-- YOUR-BASE64URL-ENCODED-DOCUMENT -->"
  data-format="isdoc"
></script>

// Inline mode via JavaScript API
pepposhShowSendBadge({
  targetId:    "peppol-send-btn",
  affiliateId: "YOUR-AFFILIATE-UUID",
  inline:      "<!-- YOUR-BASE64URL-ENCODED-DOCUMENT -->",
  format:      "isdoc",
});

// The 'inline' value is produced server-side:
// zlib.deflateRawSync(buffer).toString('base64')
//   .replace(/\+/g,'-').replace(/\//g,'_').replace(/=/g,'')

Varianta 4 — callback prepareDocument (generování dokumentu při kliknutí)

Použijte prepareDocument, pokud neexistuje předem připravená URL ani inline payload — například když je dokument generován dynamicky v prohlížeči v okamžiku kliknutí. Callback nepřijímá argumenty a musí vrátit obsah dokumentu (např. ISDOC XML) nebo Promise.

Komprese: badge-sender.js vždy zkusí komprimovat vrácený obsah pomocí prohlížečového API CompressionStream (deflate-raw) před sestavením URL. Pokud API není dostupné (starší prohlížeče), použije prosté base64url kódování. Server oba varianty transparentně zpracuje.

Během přípravy dokumentu je tlačítko dočasně deaktivováno (zešedlé), aby se zabránilo vícenásobnému odeslání. Po chybě se automaticky znovu aktivuje.

// Option 4: prepareDocument callback
// Use when neither a public URL nor pre-encoded inline is available
// (e.g. the document is generated on-the-fly in the browser).
pepposhShowSendBadge({
  targetId:       "peppol-send-btn",
  affiliateId:    "YOUR-AFFILIATE-UUID",
  format:         "isdoc",

  // Called when the user clicks the badge.
  // Return the raw document content (ISDOC XML, ZUGFeRD XML, …) as a string.
  // The script compresses it with the browser's CompressionStream API
  // (deflate-raw) and embeds the result in the redirect URL.
  // Falls back to plain base64url if CompressionStream is unavailable.
  prepareDocument: async function () {
    const invoice = await myApp.generateIsdocXml();
    return invoice; // raw XML string — badge-sender.js handles compression
  },
});

// Combine with pepposhUpdateSendBadge to refresh the callback:
pepposhUpdateSendBadge("peppol-send-btn", {
  prepareDocument: async function () {
    return await myApp.generateIsdocXml();
  },
});

// Browser-side compression and large-payload upload (badge-sender.js internal — shown for reference)
//
// badge-sender.js always tries to compress inline / prepareDocument content
// using the browser's built-in CompressionStream API before building the URL.
// This keeps the redirect URL as short as possible.
//
// SIZE-BASED ROUTING (triggered on user click, not on init):
//   < 20 KiB (encoded)  → embedded directly in the redirect URL as ?data=BASE64URL  (GET)
//   ≥ 20 KiB (encoded)  → uploaded to /api/public/web-sender/inline-upload  (POST)
//                          and referenced by a short ?uploadToken=UUID in the URL
//
// The upload happens when the user clicks the badge (not eagerly at init).
// The badge is disabled while the upload is in progress.
// Upload tokens are valid for 15 minutes.
//
// The server-side (Node.js) encoding helper for pre-compressed payloads:
const zlib = require('node:zlib');

function encodeInlineDocument(buffer) {
  return zlib.deflateRawSync(buffer)
    .toString('base64')
    .replace(/\+/g, '-')
    .replace(/\//g, '_')
    .replace(/=/g,  '');
}

// Usage:
const encoded = encodeInlineDocument(fs.readFileSync('invoice.isdoc'));
// Pass as:  inline: encoded

Ověření příjemce (volitelné)

Aby bylo možné odeslat fakturu přes síť Peppol, musí být příjemce v síti registrován. Zadání identity příjemce umožní uživateli okamžitou zpětnou vazbu, zda je odeslání možné ještě před kliknutím.

Zadejte DIČ příjemce v EU nebo kód země + IČ. Tlačítko provede klientský Peppol lookup ihned po vykreslení a přepne se na jednu ze tří variant obrázku podle výsledku:

<!-- Recipient verification using EU VAT ID -->
<div id="peppol-send-btn"></div>

<script
  src="https://app.peppos.cz/cdn/badge-sender.js"
  data-target="peppol-send-btn"
  data-affiliate-id="YOUR-AFFILIATE-UUID"
  data-url="https://your-server.example/invoice.isdoc"
  data-eu-vat-id="CZ12345678"
></script>

<!-- Or using country code + registration number -->
<script
  src="https://app.peppos.cz/cdn/badge-sender.js"
  data-target="peppol-send-btn"
  data-affiliate-id="YOUR-AFFILIATE-UUID"
  data-url="https://your-server.example/invoice.isdoc"
  data-country-code="CZ"
  data-rn="12345678"
></script>

pepposhShowSendBadge({
  targetId:    "peppol-send-btn",
  affiliateId: "YOUR-AFFILIATE-UUID",
  url:         "https://your-server.example/invoice.isdoc",

  // Identify the recipient — provide vatId OR countryCode + rn.
  // These fields are used CLIENT-SIDE ONLY to drive the badge image.
  // They are never included in the URL opened when the user clicks.
  vatId:     "CZ12345678",   // EU VAT ID (preferred)
  // -- or --
  countryCode: "CZ",           // ISO 3166-1 alpha-2 country code
  rn:          "12345678",     // Registration / company number

  // Badge will changed design based on registration status:
  //   Checking / error / no info 
  //   Recipient on Peppol        
  //   Recipient NOT on Peppol    
});

Varianta odznaku

Parametr variant určuje velikost odznaku. Použijte "normal" (výchozí) pro standardní odznak nebo "mini" pro menší verzi.

<!-- Default (normal) badge -->
<div id="peppol-send-btn-normal"></div>
<script
  src="https://app.peppos.cz/cdn/badge-sender.js"
  data-target="peppol-send-btn-normal"
  data-affiliate-id="YOUR-AFFILIATE-UUID"
  data-url="https://your-server.example/invoice.isdoc"
></script>

<!-- Mini badge -->
<div id="peppol-send-btn-mini"></div>
<script
  src="https://app.peppos.cz/cdn/badge-sender.js"
  data-target="peppol-send-btn-mini"
  data-affiliate-id="YOUR-AFFILIATE-UUID"
  data-url="https://your-server.example/invoice.isdoc"
  data-variant="mini"
></script>

// Normal (default)
pepposhShowSendBadge({
  targetId:    "peppol-send-btn-normal",
  affiliateId: "YOUR-AFFILIATE-UUID",
  url:         "https://your-server.example/invoice.isdoc",
  // variant:  "normal", // default — can be omitted
});

// Mini
pepposhShowSendBadge({
  targetId:    "peppol-send-btn-mini",
  affiliateId: "YOUR-AFFILIATE-UUID",
  url:         "https://your-server.example/invoice.isdoc",
  variant:     "mini",
});

Dynamická aktualizace URL

Při vygenerování nové faktury (např. po odeslání formuláře) aktualizujte tlačítko bez znovu-vykreslení celé stránky:

// After generating a new invoice, update the button URL
// without re-rendering the whole badge:
pepposhUpdateSendBadge(
  "peppol-send-btn",
  "https://your-server.example/invoice-20240418.isdoc"
);

// Or pass a full options object to change multiple fields:
pepposhUpdateSendBadge("peppol-send-btn", {
  url:         "https://your-server.example/new-invoice.isdoc",
  affiliateId: "YOUR-AFFILIATE-UUID",
  format:      "isdoc",
  lang:        "en", // optional
});

// In inline mode, update with new encoded data:
pepposhUpdateSendBadge("peppol-send-btn", {
  inline:      newBase64urlEncodedData,
  affiliateId: "YOUR-AFFILIATE-UUID",
  format:      "isdoc",
});

Integrace do React, Vue nebo Angular

Načtěte skript jednou a zavolejte pepposhShowSendBadge po připojení komponenty. Znovu zavolejte při změně URL.

// React / Vue / Angular — render into a ref after mount
import { useEffect, useRef } from "react";

function SendButton({ affiliateId, invoiceUrl }) {
  const ref = useRef(null);

  useEffect(() => {
    if (!invoiceUrl) return;

    const script = document.createElement("script");
    script.src = "https://app.peppos.cz/cdn/badge-sender.js";
    script.onload = () => {
      window.pepposhShowSendBadge({
        targetId:    "peppol-send-btn",
        affiliateId,
        url:         invoiceUrl,
      });
    };
    if (!document.querySelector('script[src*="badge-sender"]')) {
      document.head.appendChild(script);
    } else {
      window.pepposhShowSendBadge?.({
        targetId: "peppol-send-btn",
        affiliateId,
        url: invoiceUrl,
      });
    }
  }, [affiliateId, invoiceUrl]);

  return <div id="peppol-send-btn" />;
}

API reference

Reference atributů data-*

Při použití HTML atributů přidejte tyto na tag <script>:

Podporované formáty dokumentů

Server automaticky detekuje skutečný formát ze staženého obsahu souboru (binární signatura nebo XML jmenný prostor). Parametr format slouží jako nápověda pro UI tlačítka.