Для посередників: партнерська модель

Що має звичайний мультитенантний обліковий запис

• Один API-токен для всіх компаній облікового запису (заголовок X-Peppol-Participant-Id у SAPI-SK).
• Вебхук сповіщень, налаштований для кожної компанії окремо (GET/PUT /api/v1/companies/{id}/notifications), з тим самим підписом X-Verteco-Signature.
• Скасування реєстрації власної компанії (POST /api/v1/companies/{id}/deregister) та огляд використання за компаніями (GET /api/v1/companies/usage).
• Компаніями завжди керує їхній власник, а не партнер: одностороннього від’єднання клієнта та блокування відправлення у звичайній моделі немає.

Як стати посередником

Заявку заповнюєте на сторінці Станьте цифровим поштарем; форму Фінансової адміністрації ми підписуємо та подаємо за Вас. Плата становить 99 € на рік без ПДВ. Після публікації у виборі Фінансової адміністрації клієнти обирають Вас під Вашим брендом, їхні компанії автоматично створюються під Вашим партнерським обліковим записом і реєструються в центральному SMP, якщо їхній запис не тримає інший провайдер (тоді ви отримаєте подію company.smp_registered_elsewhere і процедуру з кодом міграції). У тестовому середовищі реєстрація посередника безкоштовна, і Ви одразу отримуєте тестову партнерську кінцеву точку.

• Станьте цифровим поштарем (заявка)
• Умови посередництва
• Наші посередники
• Клієнт від іншого провайдера: код міграції (інструкція)
• Договори: загальні умови, DPA, SLA, NDA

Якщо Ви розвиваєте застосунок для рахунків, ERP або платформу і хочете підключити кількох своїх клієнтів (tenants) до Peppol через нас, Ви інтегруєтесь один раз і обслуговуєте N компаній. Модель є проксі: Ваш бекенд тримає один API-токен (vpt_…) лише на стороні сервера (ніколи в браузері), і кожен Ваш tenant = одна компанія в нас (один токен → N компаній). Розширена публічна інструкція з прикладами коду, підписами вебхуків і чеклистом go-live: peppol.verteco.digital/saas.

1. 1

   Один токен, на стороні сервера

   Створіть API-токен і зберігайте його в захищеному бекенд-середовищі. Усі виклики виконує Ваш сервер (Bearer), а не браузер клієнта.
2. 2

   Підключення tenant = створення компанії

   Для кожного клієнта викличте POST /companies з його ідентифікаційним номером (IČO) / номером платника ПДВ (IČ DPH); повертається { id, status: "pending_verification" }; збережіть id разом із tenant (докладніше в розділі Компанії).

   bashKopírovať

   curl -X POST https://peppol.verteco.digital/api/v1/companies -H 'Authorization: Bearer vpt_8f2a…' \
   -H 'Content-Type: application/json' \
   -d '{"ico":"53412834","dic":"SK2121358349","legalName":"Firma s.r.o.",
        "street":"Príkladná 12","postalCode":"010 01","city":"Žilina","iban":"SK…"}'

3. 3

   Активація в Peppol (крок, який клієнт робить перед державою)

   pending_verification ≠ активна в Peppol. Щоб компанія могла отримувати, клієнт має обрати Verteco своїм постачальником на порталі Фінансової адміністрації Словаччини (Finančná správa, FS) увійшовши через eID або за обліковими даними порталу ФА; після цього ми реєструємо компанію в SMP, і її статус змінюється на active. Щоб компанія могла відправляти, передайте її верифікаційний токен (Verifikačný údaj) через Верифікацію для відправлення (POST /companies/{id}/verification). Якщо клієнт уже мав іншого провайдера, після вибору компанія активується, але запис у SMP лишається у старого поштаря і потрібен код міграції: див. розділ Клієнт переходить від іншого провайдера.
4. 4

   Отримання рахунків: вебхук для кожного tenant

   Налаштуйте вебхук (і/або електронну пошту) для кожної компанії та отримайте секрет для підпису:

   bashKopírovať

   curl -X PUT https://peppol.verteco.digital/api/v1/companies/{id}/notifications -H 'Authorization: Bearer vpt_8f2a…' \
   -H 'Content-Type: application/json' \
   -d '{"webhookUrl":"https://vasa-saas.sk/peppol/webhook","notificationEmail":"…"}'
   
   curl -X POST https://peppol.verteco.digital/api/v1/companies/{id}/webhook/secret -H 'Authorization: Bearer vpt_8f2a…'
   # → { "secret": "…" }   (store it to verify X-Verteco-Signature)

   Після отримання рахунку Ви одержуєте підписаний POST (подія invoice.received; так само invoice.sent, invoice.delivered, invoice.rejected, invoice.undeliverable, invoice.reported та company.* для всіх Ваших клієнтів), надійно, з повторами та dead-letter. Перевірка підпису, payload і кнопка „Otestovať webhook" (Тестувати вебхук): Сповіщення та вебхуки.
5. 5

   Відправлення рахунків

   Відправляйте рахунок (UBL Peppol BIS 3.0) через національний інтерфейс SAPI-SK 1.0: POST /sapi/document/send (OAuth2 client_credentials, client_secret = Ваш токен vpt_). Словацький податковий звіт (TDD/C5) ми додаємо автоматично.
6. 6

   Дані про використання для перевиставлення рахунків

   GET /companies/usage?month=YYYY-MM повертає кількість відправлених і отриманих документів для кожної Вашої компанії окремо та загалом, саме в тих одиницях, на яких побудований прайс, тож Ви можете перевиставляти рахунки клієнтам безпосередньо з нього. Без параметра повертається поточний місяць; період напіввідкритий, а відповідь явно містить поля from/to, щоб не вгадувати межу місяця. Компанії без трафіку показані з нулями.
7. 7

   Масштабування та надійність

   Використовуйте пагінацію списків: GET /companies?page&limit та GET /companies/{id}/documents?page&limit (із заголовками, як X-Total-Count та іншими). Дотримуйтеся ліміту запитів на токен: під час масового підключення групуйте з backoff при 429 (Retry-After) і обробляйте 409 ico_taken (ідемпотентно).

Якщо Ви зареєстровані як посередник (sprostredkovateľ) (заявка через /sprostredkovatel/ziadost), Фінансова адміністрація Словаччини (Finančná správa, FS) надсилає сповіщення на Ваш URL вебхука щоразу, коли клієнт обирає Вас на порталі FS (VPDS). Цей посібник описує точний контракттак, як FS фактично викликає його в продуктивному середовищі (перевірено на живих виборах). FS не публікує власного публічного посібника з вебхуків; це те, що Вам потрібно для реалізації.

1 · Як виглядає сповіщення + 2 · перевірка автентичності

3 · Що з ним робити: перешліть нам сире тіло запиту

Рекомендована (і найпростіша) реалізація: проксі сирих байтів: прийміть POST, швидко відповідайте і перешліть сирі байти тіла на Вашу реєстраційну кінцеву точку в нас. Ця кінцева точка створюється автоматично після заповнення форми /sprostredkovatel/ziadost, вона активна одразу, а її точний URL (з Вашим ключем) Ви бачите після входу через GET /api/v1/resellers/me:

POST https://peppol.verteco.digital/peppol/webhook/reseller/{vas-kluc}
Content-Type: application/json
(body = незмінені сирі байти від FS)

Ми криптографічно перевіряємо verification_token, автоматично створюємо компанію під Вашим партнерським обліковим записом (white-label), реєструємо її в центральному SK SMP і з цього моменту доставляємо їй е-рахунки. Контактні дані з payload Ви можете зберегти для власного онбордингу; більше нічого не потрібно. Виняток: якщо суб’єкт уже мав іншого провайдера, запис у SMP лишається в нього, а ви отримуєте від нас подію company.smp_registered_elsewhere та лист; як це вирішити, описано в окремому розділі.

4 · Правила експлуатації (важливо)

• Ідемпотентність: той самий суб’єкт може повторити вибір; обробка того ж DIČ (словацький податковий номер) має бути безпечною (з нашого боку так і є).
• IP-адреса джерела: виклики надходять з інфраструктури FS (спостережено з 194.1.2.13); список дозволених IP радимо лише як доповнення, а не як єдиний захист (FS не гарантує діапазон).
• Відповідь: повертайте 200 навіть при внутрішній помилці обробки (помилку логуйте самі); FS нічого іншого не оцінює.
• Порядок розгортання: вебхук має працювати до подання заявки до FS; перший вибір може надійти невдовзі після публікації.

Еталонна реалізація проксі займає ~30 рядків (прийняти POST → зберегти → переслати сирі байти). Якщо хочете перевірити весь ланцюжок до публікації у FS, надішліть тестовий POST на свою реєстраційну кінцеву точку; на невідомий/непідписаний вміст вона відповідає безпечно і нічого не створює. Запитання: Підтримка.

5 · Розірвання договору посередництва

Договір посередництва можна розірвати й безпосередньо з застосунку: власник партнерського облікового запису в Nastavenia poštára (Налаштування поштаря) заповнює заяву про розірвання (контрольне запитання + підтвердження наслідків) і підтверджує повідомлення за посиланням, надісланим на електронну пошту. Після підтвердження повідомлення вважається доставленим; строк повідомлення один місяць і рахується з 1-го дня наступного місяця (ст. 7.1 Умов посередництва). Заяву про виключення зі списку посередників ми самі подаємо до Фінансової адміністрації протягом 5 робочих днів після закінчення договору (ст. 7.3); наша команда отримує підтверджувальний запис, клієнтам посередника нічого не надсилається. Непідтверджену заяву можна скасувати в застосунку. Програмно: GET/POST/DELETE /api/v1/resellers/me/termination.

Партнерський вебхук сповіщень (посередники)

Якщо Ви зареєстрований посередник (sprostredkovateľ), Вам не потрібно налаштовувати вебхук для кожної компанії окремо: єдиний партнерський вебхук сповіщень отримує всі події компаній під Вашим партнерським обліковим записом і має пріоритет над вебхуками окремих компаній. Ваші клієнти, отже, нічого не налаштовують; компанію Ви розрізняєте за companyDic / peppolParticipantId.

Електронні листи про окремі рахунки: партнерський обліковий запис є учасником кожної компанії клієнта, тому зі стандартними налаштуваннями він отримував би лист про кожен отриманий рахунок кожної з них. White-label клієнтам ми ніколи не надсилаємо листів (канал – вебхук); для решти компаній вимкніть їх для партнерського облікового запису в Nastavenia poštára (налаштування постачальника) → Сповіщення (один перемикач; те саме налаштування є і в Налаштування → Сповіщення облікового запису).

// 200 OK (перше налаштування)
{ "url": "https://vasa-appka.sk/peppol/events", "secret": "vpt_…", "hasSecret": true,
"events": ["company.activated","company.deactivated","company.smp_registered_elsewhere","invoice.received","invoice.sent","invoice.delivered","invoice.rejected"] }

Підпис X-Verteco-Signature обчислюється так само, як для вебхука компанії (нижче), лише з партнерським секретом.

Керування клієнтами через API (одностороннє від’єднання та блокування відправлення)

Клієнт, який залишає партнера, зазвичай нічого не робить, тому ці операції односторонні і не потребують участі клієнта. Отримання рахунків вони не зачіпають: воно прив’язане до реєстрації компанії в центральному SMP, а не до облікового запису, що керує.

Партнерська модель розрахунків

У Nastavenia poštára, вкладка Fakturácia (та через GET/PUT /api/v1/resellers/me/billing) Ви обираєте модель розрахунків (вибір доступний лише зареєстрованим посередникам): per_company = 2 € на місяць за кожну активно відправляючу компанію (IČO), або per_document = 0,01 € за кожен рахунок, відправлений Вашими компаніями (отримані документи безкоштовні), з мінімальною місячною сумою 300 € + ПДВ. Зміна моделі завжди набуває чинності з 1-го дня наступного місяця (у відповіді pendingModel і pendingFrom); відповідь обох викликів також повертає перерахунок поточного місяця за обома моделями, тож Ви перемикаєтеся свідомо.

Рекомендована процедура для клієнта, що припинив співпрацю (обмеження витрат з Вашого боку): поточне використання видно в GET /api/v1/companies/usage?month=YYYY-MM (розбивка відправлених/отриманих за компаніями, саме для перевиставлення) та в GET /api/v1/resellers/me/clients (кількість за поточний місяць); крім того, на партнерський вебхук надходить подія про кожен документ, який Ваші компанії відправляють або отримують, тож „припинену” компанію Ви помітите вже на першому документі. Далі просто викличте pause-sending або release.

У Словаччині один центральний SMP для всіх поштарів, і кожен учасник має в ньому один запис. Коли ваш клієнт обирає ваш бренд на порталі Фінансової адміністрації, ми верифікуємо й активуємо компанію, але якщо її запис уже тримає попередній провайдер, мережа й далі доставляє йому. Перемикання виконує одноразовий код міграції, який клієнт отримує від поточного поштаря (стандартний механізм SML, FAQ ФА приклад 46; за правилами PA SK старий поштар мусить зняти клієнта з реєстрації в центральному SMP протягом 3 робочих днів після закінчення договору). Примітка: за FAQ ФА (приклади 36 і 73) клієнт може й далі отримувати в іншого поштаря, а через вас лише відправляти; якщо це його намір, викличте PUT /resellers/me/clients/{id}/receiving-provider з elsewhere=true (стан smpState = "external"), і нагадування та автоматична реєстрація припиняться. Цей розділ показує, як виявити, зберегти й вирішити ситуацію у вашій платформі та що ви отримуєте від нас.

1. 1

   Підготуйте приймач: партнерський вебхук

   Один вебхук для всіх клієнтів налаштовується через PUT /resellers/me/notification-webhook (вище). Перевіряйте X-Verteco-Signature та обробляйте подію company.smp_registered_elsewhere: вона означає «запис тримає інший провайдер, потрібен код міграції». Дедуплікуйте за companyId + event; подія повторюється щотижня, доки клієнт не введе код.

   jsonKopírovať

   // POST на ваш вебхук, заголовки X-Verteco-Event + X-Verteco-Signature
   {
     "event": "company.smp_registered_elsewhere",
     "occurredAt": "2026-09-03T15:04:05Z",
     "companyId": "bb6eb4a7-1a98-48fe-97e6-e5abbaa56e54",
     "companyDic": "SK1028310426",
     "peppolParticipantId": "0245:1028310426",
     "status": "active",
     "action": "migration_code_required",
     "migrateUrl": "https://peppol.verteco.digital/dashboard/companies/migrate"
   }

2. 2

   Додайте перевірку стану: коли запитувати й що читати

   Вебхук може бути відсутнім (ще не налаштований) або втраченим під час збою, тому читайте стан і активно: GET /resellers/me/clients повертає для кожної компанії smpRegistered і smpState; деталі в GET /companies/{id}. Рекомендований ритм: раз на день для всіх клієнтів, при відкритті сторінки клієнта у вашому застосунку та через 2–3 хвилини після події company.activated (реєстрація в SMP зазвичай завершується за хвилину). Перед створенням клієнта варто викликати GET /public/peppol-check?id=0245:<DIČ>: якщо податковий номер уже в мережі, клієнту знадобиться код, і ви можете сказати це заздалегідь.

   smpState	Значення	Що робити
   registered	Запис у SMP під нашим обліковим записом, мережа доставляє нам.	Нічого, клієнт отримує.
   pending	Реєстрація триває (секунди; під час збою SMP години; повторюємо автоматично).	Зачекати, перечитати за кілька хвилин.
   elsewhere	Запис тримає інший провайдер; клієнту потрібен код міграції.	Показати клієнту підказку, отримати код, викликати smp-migrate (крок 4).
   rejected	Верифікаційний токен ФА відхилено.	Клієнт має повторити вибір на порталі ФА.
   null	Не застосовується (компанія ще не верифікована вибором на ФА).	Привести клієнта до вибору на порталі ФА.

3. 3

   Зберігайте стан у себе

   Для кожного клієнта тримайте companyId, peppolParticipantId, smpState, smpStateAt (коли бачили останній раз) і noticeShownAt (коли поінформували клієнта). За elsewhere показуйте у своєму застосунку постійне повідомлення з полем для коду; не блокуйте відправлення, компанія може відправляти. За registered зніміть повідомлення.

   textKopírovať

   // обробка події у вашому бекенді (псевдокод)
   on webhook(event):
     verify X-Verteco-Signature == sha256=HMAC(secret, rawBody)   // else 401
     if event.event == "company.smp_registered_elsewhere":
         tenant = tenants.byCompanyId(event.companyId)
         tenant.smpState = "elsewhere"; tenant.smpStateAt = event.occurredAt
         showBanner(tenant, "Vyžiadajte si migračný kód od doterajšieho poskytovateľa")   // + input
     if event.event == "company.activated":
         schedule(in 3 min): tenant.smpState = GET /companies/{id}.smpState
   
   daily job:
     for row in GET /resellers/me/clients: tenants[row.companyId].smpState = row.smpState
   
   on code entered by the client:
     r = POST /companies/{id}/smp-migrate { migrationCode }
     if r.status == 200: tenant.smpState = "registered"; hideBanner(tenant)
     else: showError(tenant, r.error)   // 400 migration_code_rejected → ask for a new code

4. 4

   Отримайте код і перейміть запис

   Клієнт запитує у поточного провайдера код міграції SMP для свого податкового номера; код одноразовий і обмежений у часі, використайте одразу. Викличте POST /companies/{companyId}/smp-migrate своїм партнерським токеном (ви власник компанії). Відповідь 200 містить компанію з smpRegistered = true; мережа перемикається миттєво й без простою. Окремої події немає: запишіть стан із відповіді або перечитайте через GET.

   bashKopírovať

   curl -X POST https://peppol.verteco.digital/api/v1/companies/<companyId>/smp-migrate \
     -H 'Authorization: Bearer vpt_8f2a…' -H 'Content-Type: application/json' \
     -d '{ "migrationCode": "MIGR-7K3Q-…" }'
   # 200 { "company": { …, "smpRegistered": true, "smpState": "registered" }, "outcome": "REGISTERED" }

   HTTP · код	Значення	Що робити
   400 migration_code_rejected	Код недійсний, використаний або прострочений.	Запросити новий код у старого провайдера.
   409 registered_elsewhere	SMP не прийняв код; запис і далі в іншого провайдера.	Перевірити, що код належить цьому податковому номеру; повторити з новим кодом.
   403 company_not_verified	Компанія ще не верифікована вибором на ФА.	Спочатку вибір на порталі ФА.
   503 smp_unavailable	Центральний SMP не відповідає.	Повторити за кілька хвилин (код залишається дійсним).

5. 5

   Що надсилаємо вам ми

   При виявленні надсилаємо лист на контактну адресу партнера (з реєстрації посередника) з податковим номером, Peppol ID та порядком дій, потім щотижня до перейняття (не більше чотирьох разів); та сама інформація надходить вебхуком. White-label клієнту ми не пишемо. Якщо код отримаєте ви, але не хочете викликати API, надішліть його на peppol​@​verteco.digital, і ми виконаємо перейняття з адміністрування.

   Текст для клієнта, який можна використати:

   Вашу компанію в нас уже активовано, але запис у національному реєстрі Peppol (SMP) ще тримає ваш попередній провайдер, тому е-рахунки поки що надходять йому. Запросіть у нього код міграції SMP для податкового номера … і введіть його тут. Перемикання миттєве й без простою.