Rejestracja Peppol

Enrollment API to kompleksowe rozwiązanie do rejestracji nowej party w sieci Peppol. W jednym wywołaniu API konfiguruje się usługę Peppol, łączy użytkowników z odpowiednimi uprawnieniami i opcjonalnie konfiguruje hooki. Ten artykuł opisuje endpoint, trzy sekcje enrollment i usuwanie rejestracji.

Wymagania

Enrollment API wymaga roli ApManager. ApUser nie może wykonać enrollment. Przed rozpoczęciem należy sprawdzić, czy dane uwierzytelniające API mają właściwą rolę.

Rola

Uprawnienia

ApUser

Wysyłanie/odbieranie faktur i zamówień, zarządzanie hookami dla własnej party

ApManager

Wszystko z ApUser, plus: rejestracje party, zarządzanie SMP, enrollment

Endpoint Enrollment

PUT /api/v1-beta/{partyId}/enroll

{partyId} to identyfikator Peppol rejestrowanej party, w formacie schemeID:identifier (np. 0106:12345678).

Body żądania zawiera trzy sekcje: Services, Party authorizations i Hooks.

1. Services

W sekcji Services aktywuje się usługę Peppol dla party. Konfiguruje się capability SMP (jakie typy dokumentów party może odbierać) i opcjonalnie businessCard do publikacji w Peppol Directory.

{
  "services": {
    "peppol": {
      "capabilities": {
        "invoices": "on",
        "invoiceResponse": "on",
        "orderOnly": "inherited"
      },
      "businessCard": {
        "names": "Bedrijfsnaam B.V.",
        "geoInfo": "Utrecht, NL",
        "email": "info@bedrijf.nl"
      }
    }
  }
}

BusinessCard jest opcjonalna, ale zalecana. Bez businessCard party nie jest wyszukiwalna w Peppol Directory, nawet jeśli rejestracja SMP jest aktywna.

2. Party authorizations

Tutaj łączy się jednego lub więcej użytkowników z party i definiuje ich uprawnienia. Każda zarejestrowana party musi być połączona z co najmniej jednym ApUser.

{
  "partyAuthorizations": [
    {
      "userId": "gebruiker@bedrijf.nl",
      "permissions": {
        "canSendDocument": true,
        "canReceiveDocument": true,
        "canRemoveDocument": true,
        "canManageHook": true
      }
    }
  ]
}

Uprawnienie

Opis

canSendDocument

Wysyłanie dokumentów w imieniu tej party

canReceiveDocument

Odbieranie dokumentów dla tej party

canRemoveDocument

Usuwanie odebranych dokumentów

canManageHook

Tworzenie i zarządzanie hookami dla tej party

3. Hooks

Opcjonalnie można bezpośrednio zarejestrować hooki dla nowej party. Jest to przydatne, gdy w momencie rejestracji wiadomo już, jakie powiadomienia są potrzebne, na przykład webhook dla otrzymanych faktur.

{
  "hooks": [
    {
      "action": "https://api.bedrijf.nl/webhooks/invoices",
      "topics": ["InvoiceReceived"]
    },
    {
      "action": "mailto:facturatie@bedrijf.nl",
      "topics": ["InvoiceReceived"]
    }
  ]
}

Pełny przykład

Kompletne żądanie enrollment łączące wszystkie trzy sekcje:

{
  "services": {
    "peppol": {
      "capabilities": {
        "invoices": "on",
        "invoiceResponse": "on"
      },
      "businessCard": {
        "names": "Voorbeeld B.V.",
        "geoInfo": "Amsterdam, NL"
      }
    }
  },
  "partyAuthorizations": [
    {
      "userId": "api-user@voorbeeld.nl",
      "permissions": {
        "canSendDocument": true,
        "canReceiveDocument": true,
        "canRemoveDocument": false,
        "canManageHook": true
      }
    }
  ],
  "hooks": [
    {
      "action": "https://api.voorbeeld.nl/leren/peppol/incoming",
      "topics": ["InvoiceReceived"]
    }
  ]
}

Usuwanie rejestracji

Aby całkowicie wyrejestrować party (włącznie ze wszystkimi usługami, uprawnieniami i hookami), należy użyć:

DELETE /api/v1-beta/{partyId}/enroll

Po usunięciu party nie jest już osiągalna w sieci Peppol, a wszystkie powiązane hooki i autoryzacje zostają usunięte.

Ważne uwagi

Enrollment API jest endpointem beta (v1-beta). Funkcjonalność jest stabilna, ale endpoint może ulec zmianom w przyszłych wersjach. W razie pytań dotyczących statusu beta można skontaktować się z TechSupport.

Należy też pamiętać, że rejestracja SMP po enrollment może wymagać kilku minut do synchronizacji w całej sieci Peppol. Jest to nieodłączna cecha protokołu SML/SMP.

Chcą Państwo migrować istniejące rejestracje od innego dostawcy? Artykuł o migracji do eConnect.

Wypróbuj w API

Powiązane