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

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

• Один 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. У тестовому середовищі реєстрація посередника безкоштовна, і Ви одразу отримуєте тестову партнерську кінцеву точку.

• Станьте цифровим поштарем (заявка)
• Умови посередництва
• Наші посередники
• Договори: загальні умови, 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).
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), надійно, з повторами та 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 Ви можете зберегти для власного онбордингу; більше нічого не потрібно.

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.

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

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

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

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

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

У партнерській консолі (та через 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.