/ docs
ProduktZnalostiVývojári
Platforma Control
Odoslanie self-billing faktúry cez API

Implementácia self-billingu: variant NLCIUS a BIS Self-Billing 3.0, kontrola capabilities.

Ako kupujúci môžete cez PSB API vystaviť a odoslať self-billing faktúru v mene Vášho dodávateľa. Tento článok krok za krokom popisuje, ako to urobiť pre oba varianty: variant NLCIUS a Peppol BIS Self-Billing 3.0.

Pred začatím: kontrola capabilities

Vždy najprv skontrolujte, či dodávateľ môže prijať požadovaný self-billing formát:

GET /api/v1/queryRecipientParty?identifier={schemeID}:{leverancierKvK} HTTP/1.1
Host: psb.econnect.eu
Authorization: Bearer {access_token}

V odpovedi vyhľadajte podporovaný profil. Pri NLCIUS je to štandardný faktúrový profil; pri BIS Self-Billing 3.0 špecifický self-billing profil.

Variant 1: NLCIUS (zjednodušený)

Toto je najjednoduchší spôsob odoslania self-billing faktúry. Používate rovnaký CustomizationID a ProfileID ako pri bežnej NLCIUS faktúre, ale zmeníte InvoiceTypeCode na 389:

<Invoice xmlns="urn:oasis:names:specification:ubl:schema:xsd:Invoice-2">
  <CustomizationID>urn:cen.eu:en16931:2017#compliant#urn:fdc:nen.nl:nlcius:v1.0</CustomizationID>
  <ProfileID>urn:fdc:peppol.eu:2017:poacc:billing:01:1.0</ProfileID>
  <ID>SB-2026-001</ID>
  <IssueDate>2026-03-05</IssueDate>
  <InvoiceTypeCode>389</InvoiceTypeCode>
  <!-- AccountingSupplierParty = dodávateľ (príjemca faktúry) -->
  <AccountingSupplierParty>
    <Party>
      <EndpointID schemeID="0106">87654321</EndpointID>
      <PartyName><Name>Leverancier B.V.</Name></PartyName>
      ...
    </Party>
  </AccountingSupplierParty>
  <!-- AccountingCustomerParty = kupujúci (vystaviteľ faktúry) -->
  <AccountingCustomerParty>
    <Party>
      <EndpointID schemeID="0106">12345678</EndpointID>
      <PartyName><Name>Koper B.V.</Name></PartyName>
      ...
    </Party>
  </AccountingCustomerParty>
  ...
</Invoice>

Dokument odošlite cez SalesInvoice endpoint:

POST /api/v1/{partyId}/salesInvoice/send HTTP/1.1
Host: psb.econnect.eu
Authorization: Bearer {access_token}
Content-Type: application/xml
X-EConnect-DocumentId: {uuid}

PSB automaticky rozpozná InvoiceTypeCode 389 a nasmeruje dokument ako self-billing faktúru dodávateľovi.

Tip: Pre self-billing dobropis použite InvoiceTypeCode 261 namiesto 389.

Variant 2: BIS Self-Billing 3.0

Pri tomto variante používate špecifický self-billing profil s vlastnými identifikátormi:

<Invoice xmlns="urn:oasis:names:specification:ubl:schema:xsd:Invoice-2">
  <CustomizationID>urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:selfbilling:3.0</CustomizationID>
  <ProfileID>urn:fdc:peppol.eu:2017:poacc:selfbilling:3.0</ProfileID>
  <ID>SB-2026-001</ID>
  <IssueDate>2026-03-05</IssueDate>
  <InvoiceTypeCode>389</InvoiceTypeCode>
  <AccountingSupplierParty>
    <Party>
      <EndpointID schemeID="0106">87654321</EndpointID>
      <PartyName><Name>Leverancier B.V.</Name></PartyName>
      ...
    </Party>
  </AccountingSupplierParty>
  <AccountingCustomerParty>
    <Party>
      <EndpointID schemeID="0106">12345678</EndpointID>
      <PartyName><Name>Koper B.V.</Name></PartyName>
      ...
    </Party>
  </AccountingCustomerParty>
  ...
</Invoice>

BIS Self-Billing dokumenty odošlite cez Generic endpoint:

POST /api/v1/{partyId}/generic/send HTTP/1.1
Host: psb.econnect.eu
Authorization: Bearer {access_token}
Content-Type: application/xml
X-EConnect-DocumentId: {uuid}

PSB detekuje self-billing profil na základe CustomizationID a nasmeruje dokument dodávateľovi, ak je registrovaný pre profil BIS Self-Billing 3.0.

Rozdiel v rolách

Pozor na rozdiel v rolách strán pri self-billingu. To je častý zdroj nejasností:

UBL elementPri bežnej faktúrePri self-billing faktúreAccountingSupplierPartyOdosielateľ (dodávateľ)Príjemca (dodávateľ)AccountingCustomerPartyPríjemca (kupujúci)Odosielateľ (kupujúci)

AccountingSupplierParty je vždy dodávateľ, aj keď faktúru vystavuje kupujúci. Kupujúci uvádza svoje údaje v AccountingCustomerParty.

Idempotency

Vždy používajte hlavičku X-EConnect-DocumentId na zabránenie duplicitnému odoslaniu. Pravidlá sú identické s bežnými faktúrami: minimálne 6 znakov, najlepšie UUID, nikdy číslo faktúry. Viac v článku Idempotency.

Spracovanie chýb

Časté chyby pri self-billingu:

ChybaPríčinaRiešenieValidačná chybaInvoiceTypeCode chýba alebo je nesprávnySkontrolujte, že InvoiceTypeCode je 389 alebo 261Príjemca nenájdenýDodávateľ nie je registrovaný pre self-billingSkontrolujte cez queryRecipientParty; pri BIS Self-Billing musí byť dodávateľ samostatne registrovaný409 ConflictDokument s týmto ID bol už spracovanýŽiadna akcia nie je potrebná
Webhook notifikácie

Po odoslaní obdržíte rovnaké webhook eventy ako pri bežných faktúrach:

  • InvoiceSent pri úspešnom doručení
  • InvoiceSentRetry pri novom pokuse (max 8 retries)
  • InvoiceSentError ak doručenie definitívne zlyhalo
Často kladené otázky
Aký endpoint použijem pre NLCIUS self-billing oproti BIS Self-Billing 3.0?

Pre NLCIUS s InvoiceTypeCode 389 alebo 261 a bežnými NLCIUS profilmi odošlite na POST /api/v1/{partyId}/salesInvoice/send s XML telom a voliteľne X-EConnect-DocumentId. Pre BIS Self-Billing 3.0 s príslušným CustomizationID a ProfileID použite POST /api/v1/{partyId}/generic/send; PSB rozpozná profil z dokumentu.

Ako sú v UBL štruktúrované úlohy dodávateľa a kupujúceho?

AccountingSupplierParty je vždy dodávateľ (pri self-billing strana, ktorá faktúru "prijíma"), a AccountingCustomerParty je kupujúci, ktorý dokument vytvára a odosiela v mene dodávateľa. Toto prehodenie oproti bežnej predajnej faktúre je častá implementačná chyba.

Ako zabránim duplicitným self-billing odoslaniam a čo s veľkými prílohami?

Používajte rovnaké pravidlá idempotency ako pri bežných faktúrach: odošlite X-EConnect-DocumentId s UUID, nie s číslom faktúry. Payloady väčšie ako približne 24 MB (vrátane overheadu) sú odmietnuté webovým serverom; zmenšite vložené base64 PDF alebo rozdeľte dodávku, pričom zohľadnite približne 33% overhead base64.

Chcete dokument najprv zvalidovať pred odoslaním? Použite Validate API na kontrolu self-billing faktúry bez skutočného odoslania.

Vyskúšajte to v API

Súvisiace

Prehľad self-billing: varianty a výber
Prijať self-billing faktúru
Idempotency: ako zabrániť duplicitným uploadom
Odoslať faktúru cez API
NLCIUS: holandský štandard elektronickej fakturácie
Self-billing v praxi
PreviousPrehľad self-billingu
NextPrijatie self-billingu