Odbieranie faktury self-billing przez API

Odbieranie dokumentów self-billing: capabilities SMP i przepływ przetwarzania.

Jako dostawca otrzymują Państwo faktury self-billing od nabywców. Nabywca wystawia fakturę w Państwa imieniu i wysyła ją przez sieć Peppol. Ten artykuł opisuje, jaka rejestracja jest potrzebna i jak przetwarzać odebrane dokumenty.

Jak docierają faktury self-billing?

Faktury self-billing są dostarczane w ten sam sposób co zwykłe faktury zakupowe. PSB wysyła powiadomienie webhook, a dokument można pobrać przez endpoint PurchaseInvoice. Różnica polega na rejestracji i typie dokumentu.

Przepływ odbioru:

  1. Nabywca wysyła fakturę self-billing (InvoiceTypeCode 389) przez PSB
  2. Sieć Peppol kieruje dokument do Państwa Access Point
  3. PSB wysyła zdarzenie InvoiceReceived na Państwa webhook
  4. Państwo pobierają i przetwarzają dokument
Rejestracja SMP

Aby móc odbierać faktury self-billing, Państwa organizacja musi być zarejestrowana w Peppol SMP. Wymagana rejestracja zależy od wariantu:

Wariant NLCIUS

Jeśli są Państwo już zarejestrowani do odbioru zwykłych faktur NLCIUS, nie trzeba robić nic dodatkowego. Faktury self-billing z InvoiceTypeCode 389 są dostarczane przez ten sam profil. PSB automatycznie rozpoznaje typ dokumentu.

BIS Self-Billing 3.0

Dla profilu BIS Self-Billing 3.0 potrzebna jest oddzielna rejestracja. Ten profil ma własny CustomizationID i ProfileID i wymaga specyficznej konfiguracji SMP.

Konfiguracja capability self-billing przez Peppol config API:

PUT /api/v1/peppol/config HTTP/1.1
Host: psb.econnect.eu
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "selfBilling": {
    "state": "on"
  }
}

Bez tej rejestracji nabywcy korzystający z profilu BIS Self-Billing 3.0 nie mogą Państwa znaleźć przez Peppol SMP lookup.

Konfiguracja webhooka

Należy użyć tego samego topicu co dla zwykłych faktur zakupowych:

{
  "action": "https://mijn-systeem.nl/webhook/invoices#mijnSecretKey",
  "topics": ["InvoiceReceived"]
}

Faktury self-billing docierają jako zdarzenia InvoiceReceived. Można je odróżnić od zwykłych faktur, sprawdzając InvoiceTypeCode w dokumencie XML: 389 dla faktury self-billing, 261 dla noty kredytowej self-billing.

Pobieranie i przetwarzanie dokumentu

Dokument pobiera się w ten sam sposób jak zwykłą fakturę zakupową:

GET /api/v1/{partyId}/purchaseInvoice/{documentId}/download HTTP/1.1
Host: psb.econnect.eu
Authorization: Bearer {access_token}

Opcjonalnie za pomocą targetDocumentTypeId można zażądać dokumentu w innym formacie, jeśli system tego wymaga.

Rozpoznawanie faktury self-billing

Po pobraniu można sprawdzić w dokumencie XML, czy jest to faktura self-billing:

<!-- InvoiceTypeCode 389 = self-billing factuur -->
<InvoiceTypeCode>389</InvoiceTypeCode>

<!-- InvoiceTypeCode 261 = self-billing creditnota -->
<InvoiceTypeCode>261</InvoiceTypeCode>

W fakturze self-billing AccountingSupplierParty to Państwa organizacja (dostawca), natomiast AccountingCustomerParty to nabywca, który wystawił fakturę.

Wysyłanie Invoice Response

Po odbiorze mogą Państwo wysłać Invoice Response do nabywcy, aby potwierdzić przetworzenie lub odrzucić fakturę. Przepływ jest identyczny jak dla zwykłych faktur:

POST /api/v1/{partyId}/purchaseInvoice/{documentId}/response HTTP/1.1
Host: psb.econnect.eu
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "status": "AP",
  "clarificationCode": "NON",
  "actionCode": "NOA"
}

Pełny przegląd kodów statusu i kodów wyjaśniających znajduje się w artykule Wysyłanie Invoice Response.

Retencja

Reguły retencji dla dokumentów self-billing są takie same jak dla zwykłych faktur zakupowych: 90 dni przechowywania po odbiorze, 7 dni po pobraniu. Dokumenty należy pobierać terminowo i przechowywać we własnym systemie.

Często zadawane pytania
Czy potrzebuję oddzielnych webhooków dla self-billing?

Nie, self-billing używa tego samego topicu co zwykłe faktury zakupowe: InvoiceReceived. Self-billing rozróżnia się w przetwarzaniu poprzez odczytanie InvoiceTypeCode w XML (389 dla faktury, 261 dla noty kredytowej).

Jaka rejestracja SMP jest potrzebna dla NLCIUS a jaka dla BIS Self-Billing 3.0?

Jeśli już odbierają Państwo faktury zakupowe NLCIUS, ta rejestracja obejmuje również self-billing NLCIUS z kodem 389 lub 261. Dla BIS Self-Billing 3.0 wymagana jest oddzielna capability; należy ustawić selfBilling.state na on przez PUT /api/v1/peppol/config, w przeciwnym razie nabywcy nie znajdą Państwa dla tego profilu w SMP.

Jak pobrać otrzymaną fakturę self-billing i czy mogę zmienić format?

Należy użyć GET /api/v1/{partyId}/purchaseInvoice/{documentId}/download jak dla każdej faktury zakupowej. Za pomocą parametru zapytania targetDocumentTypeId można zażądać innego formatu docelowego, jeśli system back-end tego wymaga. Po pobraniu należy sprawdzić w XML, która strona jest dostawcą, a która nabywcą, zgodnie z AccountingSupplierParty i AccountingCustomerParty.


Czy jako dostawca otrzymają Państwo NLCIUS czy BIS Self-Billing 3.0, zależy od tego, co wysyła nabywca. Należy upewnić się, że mają Państwo właściwą rejestrację SMP dla wariantów używanych przez Państwa nabywców. W razie wątpliwości: rejestracja dla obu wariantów.

Zobacz dokumentację API