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

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

• Один 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.

Безпека для ваших клієнтів: ми сертифікований постачальник Фінансової адміністрації СР (EFSK000031) з власною точкою доступу; сертифікація ISO/IEC 27001:2022 триває в акредитованому органі SKQS, s. r. o., Жиліна (SNAS), обраному у вересні 2026 року, сертифікат плануємо до 1 липня 2027 року; OpenPeppol вимагає його від усіх постачальників з 1 жовтня 2027 року, поки що його не зобов’язаний мати ніхто. Договори (умови, DPA, SLA, NDA) опубліковані повністю на /zmluvy, доступність на /status.

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. Щоб компанія могла отримувати, клієнт активує її вибором постачальника на порталі Фінансової адміністрації Словаччини (Finančná správa, FS), увійшовши через eID або за обліковими даними порталу ФА. Ви зареєстрований посередник: клієнт обирає вашу марку через ваше посилання для вибору (поле vpdsUrl у GET /api/v1/resellers/me), а не Verteco напряму, бо прямий вибір Verteco виводить компанію з вашої програми (подія company.released_to_direct). FS надсилає вибір на ваш вебхук, ви пересилаєте його нам (розділ FS вебхук), а ми активуємо компанію, реєструємо її в SMP і надсилаємо вам company.activated. Ви не зареєстрований посередник: клієнт обирає Verteco постачальником, решта відбувається так само. Перевірений вибір водночас дозволяє компанії відправляти. Якщо прямий вибір Verteco до нас не дійшов, запасний шлях: Верифікація для відправлення (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, invoice.report_pending, invoice.report_rejected та 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 · Що з ним робити: перешліть нам сире тіло запиту

Запис посередника передбачає власну систему, яка приймає вибори клієнтів і пересилає їх нам. Не вказуйте нашу адресу у формі FS: FS має викликати Вас. Без власної системи Ви не посередник; правильний шлях: реєстраційна сторінка з Вашою позначкою та комісія (/affiliate).

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

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

Ми криптографічно перевіряємо verification_token, автоматично створюємо компанію під Вашим партнерським обліковим записом (white-label), реєструємо її в центральному SK SMP і з цього моменту доставляємо їй е-рахунки. Контактні дані з payload Ви можете зберегти для власного онбордингу; більше нічого не потрібно. Виняток: якщо суб’єкт уже мав іншого провайдера, запис у SMP лишається в нього, а ви отримуєте від нас подію company.smp_registered_elsewhere та лист; як це вирішити, описано в окремому розділі. Подія company.client_registered_directly надходить, коли ваш клієнт додає свою компанію безпосередньо на порталі Verteco: linked = true означає, що ми приєднали його обліковий запис як співвласника (контактний e-mail компанії збігся), false лише інформує про спробу (не частіше ніж раз на день); ваші відносини з клієнтом і розрахунки не змінюються. Подія company.released_to_direct надходить, коли ваш клієнт на порталі Фінансової адміністрації обирає Verteco напряму: компанія тоді виходить з вашої програми (ваші облікові записи втрачають доступ, white-label скасовується, контакт із вибору стає власником); клієнта ми повідомляємо з порталу, ви також отримуєте лист. Діє для виборів від 21.09.2026. Зворотний напрямок, вибір під вашою маркою для компанії, якою ваш партнерський обліковий запис уже володіє (наприклад, ваша власна компанія, додана як прямий клієнт), не перереєстровує компанію: точка доступу та запис у центральному SMP лишаються тими самими (повторна реєстрація є лише підтвердженням), компанія просто переходить у режим white-label, відтоді не отримує від нас листів про документи, ви дізнаєтеся про них лише через вебхуки та API, і вона тарифікується за партнерською моделлю; архів і налаштування зберігаються. Це зручний спосіб перевірити інтеграцію на власній компанії.

Транспортний ключ (заголовок x-pds-secret): після публікації Вашого запису FS надсилає zip-архів WebhookSecret_Verteco_<назва>.zip e-mailом заявникові, тобто нам, а пароль до нього SMS на номер телефону, який Ви вказали у формі /sprostredkovatel/ziadost (форма FS від 17. 9. 2026 має для цього окреме поле), тобто Вам. Архів Ви завантажите в партнерській консолі, вкладка FS webhook (кнопка «Завантажити zip від FS»), відкриєте його паролем із SMS і введете 32-символьний ключ із текстового файлу там само, де Ви згодом зможете його показати або завантажити як .txt (кожен перегляд записується в журнал аудиту Вашого облікового запису). Якщо SMS не надійшла, напишіть нам. Для записів, поданих до 17. 9. 2026, пароль надходив нам і ключ ми зберегли самі. З моменту збереження ключа ми перевіряємо, що підпис sha512(тіло + ключ) кожного виклику збігається. Поки ключ не введено, підпис лише записуємо. Під час збереження ключ порівнюється з викликами, які FS уже надіслала на Ваш endpoint, і ключ, що їм суперечить, відхиляється; тому Ваш proxy має пересилати тіло байт у байт (без повторної серіалізації JSON).

3a · Що відповідає наша кінцева точка

Виклик обробляємо одразу (синхронно). Тіло відповіді 200 навмисно не розкриває, чи був токен дійсним і чи активовано фірму, щоб через кінцеву точку не можна було з’ясувати, який DIČ є нашим клієнтом. Результат ви дізнаєтеся з події company.activated на вашому вебхуку сповіщень і будь-коли прочитаєте через GET /api/v1/resellers/me/clients (статус active, заповнений peppolParticipantId).

Якщо після відповіді 200 протягом кількох хвилин не надійде company.activated, надішліть нам час виклику; кожен виклик зберігається в нашому постійному журналі аудиту.

3b · Перевірка запиту на вашому боці перед пересиланням

Радимо, щоб ваш проксі перевіряв кожен запит перед пересиланням. Так ви надсилаєте нам лише справжні вибори FS, а випадкові чи підроблені виклики не витрачають ваш ліміт.

1. Спочатку збережіть увесь запит (сире тіло й заголовки). FS ніколи не надсилає вибір повторно, тож збережена копія – єдиний спосіб його відновити.
2. Перевірте заголовок x-pds-secret: він має дорівнювати hex(SHA-512(сирі байти тіла + ваш ключ FS)), 128 шістнадцяткових символів. Рахуйте хеш від тіла точно в тому вигляді, в якому воно надійшло, до будь-якого розбору JSON; додайте ключ одразу після тіла без роздільника; порівнюйте за сталий час і без урахування регістру.
3. Пересилайте лише збіжні запити, з незміненим тілом і початковим заголовком x-pds-secret. Тіла понад 64 КБ відкидайте; вибір FS має близько 1 КБ.

import crypto from 'node:crypto';

// rawBody = Buffer з тілом точно в тому вигляді, в якому воно надійшло (напр. express.raw({ type: '*/*' }))
function isFromFs(rawBody, header, fsKey) {
  const expected = crypto.createHash('sha512')
    .update(Buffer.concat([rawBody, Buffer.from(fsKey, 'utf8')]))
    .digest('hex');
  const got = String(header || '').trim().toLowerCase();
  return got.length === expected.length
    && crypto.timingSafeEqual(Buffer.from(got), Buffer.from(expected));
}

Та сама перевірка на PHP, Python і C#:

<?php
// $rawBody = file_get_contents('php://input'); $header = $_SERVER['HTTP_X_PDS_SECRET'] ?? null;
function isFromFs(string $rawBody, ?string $header, string $fsKey): bool
{
    $expected = hash('sha512', $rawBody . $fsKey);
    $got = strtolower(trim((string) $header));
    return hash_equals($expected, $got);
}

import hashlib
import hmac

# raw_body = байти тіла точно в тому вигляді, в якому вони надійшли (Flask: request.get_data(), FastAPI: await request.body())
def is_from_fs(raw_body: bytes, header: str | None, fs_key: str) -> bool:
    expected = hashlib.sha512(raw_body + fs_key.encode("utf-8")).hexdigest()
    got = (header or "").strip().lower()
    return hmac.compare_digest(expected, got)

using System.Security.Cryptography;
using System.Text;

// rawBody = байти тіла точно в тому вигляді, в якому вони надійшли (ASP.NET Core: скопіюйте Request.Body у MemoryStream до читання JSON)
static bool IsFromFs(byte[] rawBody, string? header, string fsKey)
{
    byte[] key = Encoding.UTF8.GetBytes(fsKey);
    byte[] data = new byte[rawBody.Length + key.Length];
    Buffer.BlockCopy(rawBody, 0, data, 0, rawBody.Length);
    Buffer.BlockCopy(key, 0, data, rawBody.Length, key.Length);
    string expected = Convert.ToHexString(SHA512.HashData(data)).ToLowerInvariant();
    string got = (header ?? "").Trim().ToLowerInvariant();
    return CryptographicOperations.FixedTimeEquals(Encoding.ASCII.GetBytes(expected), Encoding.ASCII.GetBytes(got));
}

• Ключ: це той самий ключ FS, яким підпис перевіряємо ми (з архіву FS, відкритого паролем із SMS); після введення він є в консолі партнера, вкладка FS вебхук. Зберігайте його лише на сервері. Збіг у вас означає збіг і в нас.
• Іншого механізму немає: FS не підписує транспорт асиметричним ключем, публічного ключа для заголовка немає. verification_token у тілі – це підпис FS над податковими номерами; його перевіряємо ми за сертифікатом FS, ви лише пересилаєте його без змін.
• Ліміт: 600 викликів на хвилину з однієї IP-адреси діють для кожного виклику на /peppol/webhook/…, чинного чи ні. Виклик без чинного заголовка отримує від нас 403 і нічого не обробляється, але спам витрачав би ліміт вашого сервера.
• Якщо підпис не збігається вже на першому реальному виборі, не відкидайте запит: збережіть його й напишіть нам, причину знайдемо разом.

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

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

Еталонна реалізація проксі займає ~30 рядків (прийняти POST → зберегти → переслати сирі байти). URL перевірите запитом GET на свою реєстраційну кінцеву точку (відповідь ready). Після збереження вашого ключа тестовий POST без дійсного заголовка x-pds-secret отримає 403 і нічого не створить; увесь ланцюжок разом з активацією фірми випробуйте в тестовому середовищі test.peppol.verteco.digital (симульований вибір на /register-vpds-test; реєстрація посередника там безкоштовна і без подання до FS, компанія, створена через POST /companies, активується одразу, а симульований вибір надходить на ваш вебхук так само, як від FS). Запитання: Підтримка.

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

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

6 · Як розподілено відповідальність

Стислий виклад ст. 5 Умов посередництва (v1.8), щоб ви знали, чого ми від вас очікуємо на практиці. Саме лише технічне передавання документа вашого клієнта не створює для вас ні договірного штрафу, ні відповідальності за шкоду, і ви не зобов'язані перевіряти господарську реальність чи змістову правильність окремих документів (ст. 5.8). Вибір на порталі Фінансової адміністрації, підтверджений eID або даними для входу, разом із нашим перевіреним верифікаційним даним (Verifikačný údaj) є достатнім підтвердженням права діяти від імені компанії, а надання доступу до API вашим власним клієнтам не вважається наданням доступу третій особі (ст. 5.9). Договірні штрафи обмежено сумою 5 000 EUR за одну подію або серію порушень з однією причиною та 10 000 EUR за календарний рік (ст. 5.3). Санкції та заходи, які органи влади або органи мережі Peppol фактично накладають на нас за дії у вашій сфері, і надалі переносяться без обмеження (ст. 5.2), бо перед Фінансовою адміністрацією та OpenPeppol ми несемо їх без ліміту. Вимога, однак, пропорційно зменшується на нашу частку, ми додаємо до неї відповідне рішення та письмовий розрахунок, ви маєте 15 днів на відповідь, скасовану або зменшену санкцію ми повертаємо вам протягом 15 днів навіть без вимоги, а свої вимоги до клієнта, який її спричинив, передаємо вам разом із документами (ст. 5.5 і 5.7). Тому ст. 4.1 літ. h) вимагає перенести відповідні обов'язки у ваші договори з клієнтами та вести облік того, хто створив який документ; зразок положення надішлемо на запит безкоштовно.

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

Якщо Ви зареєстрований посередник (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","company.client_registered_directly","company.released_to_direct","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 000 документів на місяць у моделі per_document не застосовується, кожен відправлений рахунок тарифікується з першого (кредит-нота є відправленим документом), а отримані безкоштовні без обмеження. Зміна моделі завжди набуває чинності з 1-го дня наступного місяця (у відповіді pendingModel і pendingFrom); відповідь обох викликів також повертає перерахунок поточного місяця за обома моделями, тож Ви перемикаєтеся свідомо.

Калькулятор: яка модель вигідніша за Вашої кількості компаній і документів, разом із річною сумою з реєстрацією та ПДВ, розраховується на сторінці /sprostredkovatel (розділ Kalkulačka).

Щомісячна виписка споживання за клієнтами: GET /api/v1/resellers/me/usage?month=YYYY-MM (без параметра попередній місяць) повертає для кожної компанії під Вашим брендом, якою володіє Ваш обліковий запис, кількість відправлених і отриманих документів, документи понад ліміт 1 000 (відправлені та отримані разом), суму за моделлю A (2 € за компанію, яка в місяці відправила документ, плюс 0,01 € за кожен документ понад ліміт; архів компанії під Вашим брендом ніколи не тарифікується) та за моделлю B (0,01 € за відправлений документ), підсумки обох моделей з доповненням до мінімуму 300 € у моделі B і модель, яка діяла для Вас у цьому місяці (appliedModel); прямі компанії, у яких обліковий запис є учасником, платять зі свого кредиту й у виписці відсутні. Суми в центах без ПДВ, розраховані так само, як щомісячний розрахунок, але з поточного стану компаній на момент читання (обов'язковими є позиції розрахунку у Вашому кредиті), і для компаній понад лімітом вони відрізняються від попереднього перегляду поточного місяця в GET /resellers/me/billing, який рахує модель A як 2 € × активні компанії. З ?format=csv Ви отримаєте те саме як файл для бухгалтерії (UTF-8 з BOM, роздільник крапка з комою, словацькі заголовки, суми з десятковою комою, останній рядок Spolu), а в партнерській консолі виписка є на вкладці Spotreba з вибором останніх 12 місяців.

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

Рекомендований потік для власного порталу або застосунку партнера (за запитаннями партнерів у жовтні 2026 року):

1. Зберігайте копії документів у себе. У компаній під вашим брендом Архів даних типово вимкнений, тому вміст документа (XML, PDF) залишається в нас 14 днів після доставлення, а потім видаляється; докази доставлення (квитанція, часові мітки, стан звіту) залишаються. Тому ваш портал читає з власної копії, а в нас завантажує лише нові документи.
2. Нові документи через вебхук, а не опитуванням. Партнерський вебхук сповіщень (вище) отримує invoice.received для кожної компанії; документ завантажуєте через GET /sapi/document/receive/{id} (XML, PDF, HTML і вкладення мають власні шляхи) і підтверджуєте через POST /sapi/document/receive/{id}/acknowledge. Резервний шлях: посторінкове читання GET /sapi/document/receive?status=received&limit=200 з pageToken (найстаріші першими; підтверджені документи випадають із фільтра).
3. Стани надісланих документів також надходять вебхуком (invoice.sent, invoice.delivered, invoice.rejected, invoice.undeliverable, invoice.reported) і доступні за запитом GET /sapi/document/sent.
4. Власний домен для клієнтів. Ваш застосунок може викликати наш API через власний міст (наприклад api.vash-domen.sk) одним партнерським ключем для всіх компаній під вашим обліковим записом; клієнтам наша адреса не потрібна, а вебхуки ви пересилаєте їм зі свого боку.
5. Ліміти. 300 викликів за хвилину на API-ключ, заголовки RateLimit-* повертають залишок; вищий ліміт встановимо на запит. Ліміт 1 000 документів на місяць на компанію діє в моделі A (надіслані й отримані разом, кожен наступний документ 0,01 €); у моделі B він не застосовується.

Яка модель винагороди: модель B (0,01 € за надісланий документ, мінімум 300 € на місяць, отримані безкоштовно) дешевша за модель A (2 € за кожну компанію, яка надіслала документ у місяці) тоді, коли в місяці надсилає понад 150 компаній і на одну компанію, що надсилає, припадає в середньому менше ніж 200 надісланих документів (150 компаній = до 30 000 документів, 300 компаній = до 60 000); модель змінюєте в партнерській консолі з наступного місяця.

Архів даних клієнта через партнерський API: якщо Ваш портал має ввімкнути або вимкнути архів клієнта, йому не потрібно відправляти клієнта в наш портал.

Що означає ввімкнений архів для ціни компанії під Вашим брендом, точно за кодом розрахунку: ввімкнений Архів даних для компанії під брендом посередника ніколи не запускає базову плату 2 €, тож у моделі A Ви платите 2 € лише за місяць, у якому компанія відправила документ, плюс 0,01 € за кожен документ понад 1 000 (відправлені та отримані разом), а в моделі B 0,01 € за відправлений документ; увімкнення архіву змінює лише те, як довго ми зберігаємо оригінали (протягом дії договору замість терміну), а не суму. Сховище вимірюється раз на ніч, а повідомлення при 80 % і при наступному розпочатому ГБ надходять на контактну електронну адресу партнера (за її відсутності власникові реєстрації), ніколи клієнтові; щомісячний розрахунок не містить позиції за сховище. Поля archiveReceived, archiveSent, wipeDaysReceived, wipeDaysSent і storageUsedBytes видно для кожної компанії також у GET /resellers/me/clients.

У Словаччині один центральний 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 для податкового номера … і введіть його тут. Перемикання миттєве й без простою.

Якщо згодом ви перейдете від нас до іншого сертифікованого провайдера, ваші клієнти перейдуть разом із вами. Технічне передання реєстрацій ми виконуємо масово і без простою; один крок, однак, визначає Фінансова адміністрація, а не ми, і він однаковий для кожного провайдера в Словаччині. Свобода піти є гарантією, а не сценарієм, на який ми розраховуємо: наша партнерська гарантія (плату за запис вирівнюємо аж до нуля, річна ціна за документ на 10 % нижча за будь-яку порівнянну пропозицію) діє протягом усієї співпраці, тож причини йти просто не виникає.

1. 1

   Розірвання з консолі

   У налаштуваннях поштаря ви подаєте заяву про розірвання і підтверджуєте її посиланням з e-mail; строк становить один місяць з 1-го дня наступного місяця (ст. 7.1). До припинення договору все працює як раніше.
2. 2

   Коди міграції масово

   Надішліть нам список ДІЧ ваших клієнтів. Коди з центрального SMP ми видаємо для всіх одразу (не по одному в порталі) і передаємо вам для нового провайдера. Альтернативно ми знімаємо клієнтів з реєстрації у законний строк 3 робочих дні після припинення договору (правила PA SK).
3. 3

   Перейняття в SMP без простою

   Новий провайдер реєструє кожного клієнта у своєму SMP з кодом міграції; SML негайно переприв’язує запис, а наш переходить у стан «Unpublished». Документи весь час надходять без перерви: у Словаччині кожен суб’єкт має один запис у SMP для отримання, але надсилати може через кількох провайдерів, тож новий провайдер може надсилати за клієнта одразу, як матиме його верифікаційне значення, ще до перейняття отримання.
4. 4

   Вибір нового провайдера на порталі Фінансової адміністрації

   Верифікаційне значення, яке ФА видає при виборі провайдера, є її підписом над парою ДІЧ провайдера та ДІЧ клієнта, тобто прив’язане до конкретного провайдера. Центральний SMP вимагає його при кожній реєстрації словацького учасника, також із кодом міграції. Тому новому провайдеру потрібне верифікаційне значення, видане для нього, а воно з’являється лише після вибору на порталі ФА: через eID або з обліковими даними порталу ФА; це може зробити й уповноважена особа (наприклад, бухгалтер). Це та сама довіреність, за якою подають декларацію з ПДВ і контрольний звіт, і та сама дія, що й перший вибір. Код міграції усуває простій і очікування зняття з реєстрації; вибір на ФА він не замінює.
5. 5

   Експорт даних

   На запит ми масово експортуємо оригінальні XML документи, підтвердження доставки та метадані, які зберігаємо на момент припинення; ми не видаляємо їх раніше ніж через 90 днів після припинення або до підтвердження експорту (ст. 7.4).

Договірна основа: ст. 7.1, 7.3 і 7.4 умов посередництва. Протилежний напрям (клієнт приходить від іншого провайдера) описано в попередньому розділі.

Фінансова адміністрація зберігає про вас як посередника дані з форми, яку ми подали за вас (назва, адреса, ІКО, ДІЧ, контактна особа, e-mail, телефон, вебсайт, адреса вашого webhook). Зміну не просять електронним листом: у консолі посередника відкрийте вкладку Дані у ФА, впишіть нові значення поруч із поточними, решту залиште як є та підтвердьте всі зміни разом. Ми надішлемо на peppol​@​financnasprava.sk запит, підписаний директором Verteco, разом з оновленою формою та повідомимо про результат електронною поштою (власника облікового запису та контактну адресу).

У переліку й у виборі ФА ви виступаєте під найменуванням юридичної особи з форми; назви продукту форма не знає. Бренд, вебсайт і опис послуги ви заповнюєте в консолі посередника на вкладці Information, і саме так ми показуємо вас на /partneri і /nasi-sprostredkovatelia (бренд великим шрифтом, найменування під ним); картка існує з дня подання заяви.

Запити надсилаються у робочі дні з 08:00 до 16:00 (без словацьких державних свят), не раніше ніж через 2 години після подання; до того часу (і поза вікном до наступного надсилання) запит очікує, і його можна скасувати. Зміну назви, місцезнаходження або країни спочатку перевіряє наша команда (підтвердний документ, наприклад витяг із реєстру) і надсилає лише після перевірки. Діє правило: один запит на 48 годин і лише один відкритий (в очікуванні або переданий ФА) одночасно, тож включіть у нього всі зміни. Те саме через API: GET /resellers/me/fs-registration (поточні значення, відкритий запит, історія, вікно надсилання), POST /resellers/me/fs-change-requests з changes, note та confirm: true (429 з Retry-After протягом 48 год), DELETE /resellers/me/fs-change-requests/{id}, доки запит очікує.

Зміни Умов посередництва щодо послуги доставки ми публікуємо на сторінці умов (також у PDF) і повідомляємо електронною поштою власнику облікового запису та контактній особі. Згідно з п. 9.1 вони не потребують вашої згоди і діють з дня публікації; консоль партнера не вимагає підтвердження і нічого не блокує. Якщо ви не згодні зі зміною, ви можете розірвати договір за п. 9.2 повідомленням на [email protected] з негайним ефектом і без санкцій.

На вкладці «Умови» вкажіть, де ви опублікували інформацію для клієнтів за п. 4.4 (інформація за Додатком A у ваших умовах, на сайті та у вашому програмному забезпеченні в місці активації е-рахунку); для чинних договорів не пізніше 30 днів від повідомлення про зміну. Наша команда перевірить презентацію (п. 4.5), результат з'явиться на тій самій вкладці.