Registrace Peppol

Enrollment API je jednotné řešení pro registraci nové strany v síti Peppol. V jediném API volání nakonfigurujete službu Peppol, přidělíte uživatelům správná oprávnění a volitelně nastavíte hooky. Tento článek popisuje endpoint, tři části enrollment a zrušení registrace.

Požadavky

Enrollment API vyžaduje roli ApManager. ApUser nemůže enrollment provést. Před začátkem ověřte, zda Vaše API credentials mají správnou roli.

Role

Oprávnění

ApUser

Odesílání a přijímání faktur a objednávek, správa hooků pro vlastní stranu

ApManager

Vše z ApUser, plus: registrace stran, správa SMP, enrollment

Enrollment endpoint

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

{partyId} je identifikátor Peppol registrované strany ve formátu schemeID:identifier (např. 0106:12345678).

Tělo požadavku obsahuje tři sekce: Services, Party authorizations a Hooks.

1. Services

V sekci Services aktivujete službu Peppol pro stranu. Nakonfigurujete SMP capabilities (jaké typy dokumentů může strana přijímat) a volitelně businessCard pro publikaci v Peppol Directory.

{
  "services": {
    "peppol": {
      "capabilities": {
        "invoices": "on",
        "invoiceResponse": "on",
        "orderOnly": "inherited"
      },
      "businessCard": {
        "names": { "value": "Bedrijfsnaam B.V.", "state": "on" },
        "address": { "value": "Voorbeeldstraat 1, 1234 AB, Utrecht, NL", "state": "on" },
        "emailAddress": { "value": "info@bedrijf.nl", "state": "on" },
        "state": "on"
      }
    }
  }
}

BusinessCard je volitelná, ale doporučená. Bez businessCard není strana vyhledatelná v Peppol Directory, i když je SMP registrace aktivní. Pokud businessCard publikujete, jsou names a address s kódem země povinné. PSB tato pole neodvozuje z obchodního rejstříku.

2. Party authorizations

Zde přidělíte jednoho nebo více uživatelů straně a definujete jejich oprávnění. Každá zaregistrovaná strana musí být propojena minimálně s jedním ApUser.

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

Oprávnění

Popis

canSendDocument

Odesílání dokumentů jménem této strany

canReceiveDocument

Přijímání dokumentů pro tuto stranu

canRemoveDocument

Odstraňování přijatých dokumentů

canManageHook

Vytváření a správa hooků pro tuto stranu

3. Hooks

Volitelně můžete přímo registrovat hooky pro novou stranu. Je to praktické, pokud při registraci již víte, jaké notifikace budou potřeba, například webhook pro přijímané faktury.

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

Kompletní příklad

Kompletní enrollment požadavek kombinující všechny tři části:

{
  "services": {
    "peppol": {
      "capabilities": {
        "invoices": "on",
        "invoiceResponse": "on"
      },
      "businessCard": {
        "names": { "value": "Voorbeeld B.V.", "state": "on" },
        "address": { "value": "Keizersgracht 1, 1015 AA, Amsterdam, NL", "state": "on" },
        "state": "on"
      }
    }
  },
  "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"]
    }
  ]
}

Zrušení registrace

Pro úplnou deregistraci strany (včetně všech služeb, oprávnění a hooků) použijte:

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

Po zrušení není strana v síti Peppol více dosažitelná a všechny propojené hooky a autorizace se odstraní.

Důležitá upozornění

Enrollment API je beta endpoint (v1-beta). Funkcionalita je stabilní, ale endpoint se může v budoucích verzích změnit. Při otázkách k beta statusu kontaktujte TechSupport.

Po úspěšném PUT /api/v1-beta/{partyId}/enroll je registrace ihned zpracována v Peppol SML. Odesílatel může mít lookup cache, kterou je třeba nejdřív obnovit. Peppol Directory není hned aktuální, kvůli vlastnímu indexeru. V některých případech to trvá několik minut.

Chcete převzít existující registrace od jiného poskytovatele? Přečtěte si článek o migraci na eConnect.

Vyzkoušejte to v API

Související