Надсилання та отримання рахунків через Peppol

Peppol є європейською мережею для обміну структурованими електронними рахунками між підприємствами та державними органами. Кожен рахунок прямує від точки доступу (access point) відправника до точки доступу отримувача. Nordlet формує рахунки та кредитові ноти за стандартом Peppol BIS Billing 3.0, а також надсилає й отримує їх через обліковий запис точки доступу (access point) вашої компанії.

Peppol встановлює правила обміну документами між точками доступу (access point), але не визначає, як ваше програмне забезпечення взаємодіє з вашою точкою доступу: кожен провайдер має власний API. Nordlet працює з такими провайдерами:

Провайдер	Надсилання	Статус доставки	Отримання
Recommand	так	через вебхук (webhook) і за запитом	так
Storecove	так	лише через вебхук (webhook)	так
e-invoice.be	так	через вебхук (webhook) і за запитом	так

Якщо точку доступу (access point) не налаштовано, Nordlet усе одно створює файл Peppol для кожного виставленого рахунку та кредитової ноти, щоб ви могли завантажити його й передати іншим способом; у цьому разі надсилання й отримання не виконуються.

Що вам знадобиться

• Обліковий запис у будь-кого з наведених вище провайдерів, через який ваша компанія зареєстрована в мережі Peppol. Кожен провайдер стягує плату за свої послуги згідно з власними тарифами.
• У Nordlet: податковий номер (VAT number) або реєстраційний номер компанії, чи її ідентифікатор Peppol (Обліковий запис (Account) → Компанії (Companies) → Ідентифікатор Peppol (Peppol ID)). Кожен клієнт, якому ви надсилаєте документи, також повинен мати один із цих реквізитів у своїй картці контрагента.

Підключення вашої точки доступу (access point)

Перейдіть до розділу Обліковий запис (Account) → Відповідність вимогам (Compliance) → ЄС (EU) → Точка доступу Peppol (Peppol access point), виберіть потрібного провайдера в полі Провайдер (Provider), заповніть поля для цього провайдера відповідно до інструкцій нижче та збережіть зміни. Залиште поле Базова URL-адреса API (API base URL) порожнім, якщо ваш провайдер не надав іншу адресу. Після збереження на сторінці відобразиться URL-адреса вебхуку (Webhook URL) вашої компанії: https://api.nordlet.com/v1/peppol/webhooks/{provider}/{companyId}, де {provider} — це recommand, storecove або e-invoice-be, а {companyId} — ідентифікатор вашої компанії. Кожна компанія в Nordlet має власну URL-адресу вебхуку (Webhook URL).

Nordlet приймає виклик вебхуку (webhook) лише за умови підтвердження секретного ключа вебхуку (webhook secret), тому запити не від вашої точки доступу (access point) відхиляються. Nordlet звертається до загальнодоступних інтернет-адрес лише під час виклику вашої точки доступу (access point).

Recommand

1. У системі Recommand відкрийте профіль вашої компанії та скопіюйте її ідентифікатор компанії (company ID) у поле Ідентифікатор облікового запису в точці доступу (Account ID at the access point).
2. У Recommand створіть ключ API (API key) і скопіюйте сам ключ та його секретне значення у поля Ключ API (API key) і Секрет API (API secret).
3. Сформуйте довільний довгий рядок символів, відомий лише вам і Recommand, та введіть його в поле Секрет вебхуку (Webhook secret). Збережіть зміни.
4. У Recommand створіть вебхук (webhook) для вашої компанії, вказавши URL-адресу вебхуку (Webhook URL), яку показує Nordlet, та той самий секрет вебхуку (webhook secret).

Recommand підписує кожен виклик вебхуку (webhook) цим секретним ключем.

Storecove

1. У системі Storecove створіть юридичну особу (legal entity) для вашої компанії з активованими правами на надсилання та отримання, після чого скопіюйте її ідентифікатор у поле Ідентифікатор облікового запису в точці доступу (Account ID at the access point).
2. У Storecove у розділі Ключі API (API Keys) створіть ключ API та вставте його в поле Ключ API (API key). Залиште поле Секрет API (API secret) порожнім.
3. Сформуйте довільний довгий рядок символів і введіть його в поле Секрет вебхуку (Webhook secret). Збережіть зміни.
4. У Storecove налаштуйте вхідний вебхук (push webhook), вказавши URL-адресу вебхуку (Webhook URL), яку показує Nordlet, та захистивши її за допомогою базової аутентифікації HTTP (HTTP Basic authentication): будь-яке ім'я користувача та секрет вебхуку (webhook secret) як пароль.

Storecove не підтримує запит статусу надісланого документа, тому для Storecove статус доставки надходить виключно через вебхук (webhook), а на сторінці рахунку немає кнопки Перевірити статус Peppol (Check Peppol status). Тестовий обліковий запис (sandbox) Storecove надсилає документи в тестову мережу Peppol; виробничі ключі API (production API keys) можна отримати через службу підтримки Storecove.

e-invoice.be

1. У застосунку e-invoice.be в розділі Налаштування API (API Settings) скопіюйте ключ API (API key) вашої компанії в поле Ключ API (API key). Залиште поля Ідентифікатор облікового запису в точці доступу (Account ID at the access point) та Секрет API (API secret) порожніми. Збережіть зміни.
2. Створіть вебхук за допомогою API e-invoice.be (POST https://api.e-invoice.be/api/webhooks/), вказавши URL-адресу вебхуку (Webhook URL), яку показує Nordlet, і події document.received, document.sent та document.sent.failed.
3. Скопіюйте значення secret, яке повертає API для нового вебхуку, у поле Секрет вебхуку (Webhook secret) у Nordlet і знову збережіть зміни.

e-invoice.be підписує кожен виклик вебхуку (webhook) цим секретним ключем. Тестова компанія (sandbox) на e-invoice.be надсилає документи електронною поштою замість мережі Peppol.

Надсилання рахунку

1. Виставте рахунок або кредитову ноту.
2. Переконайтеся, що в картці контрагента зазначено ідентифікатор Peppol, податковий номер (VAT number) або реєстраційний номер клієнта.
3. На сторінці рахунку в розділі Доставка (Delivery) натисніть Надіслати через Peppol (Send via Peppol) та підтвердьте дію. Розділ доставки відображається для неоплачених виставлених рахунків, а кнопка з'являється лише за умови підключеної точки доступу (access point).

Nordlet формує файл Peppol і передає його вашій точці доступу (access point). Після цього на сторінці рахунку з'являється розділ Доставка Peppol (Peppol delivery):

Статус	Значення
pending	Передано до точки доступу (access point); точка доступу отримувача ще не підтвердила отримання
delivered	Точка доступу отримувача підтвердила отримання рахунку
rejected	Клієнт відхилив рахунок; причина зазначається нижче статусу
failed	Не вдалося доставити рахунок; причина зазначається нижче статусу, якщо її надала точка доступу

Статус оновлюється автоматично, коли точка доступу повідомляє про зміни через вебхук (webhook). Кнопка Перевірити статус Peppol (Check Peppol status) миттєво запитує поточний статус у Recommand або e-invoice.be; для e-invoice.be вона також зчитує відповідь клієнта щодо рахунку, при цьому відмова (код відповіді RE) відображається як статус rejected. Рахунок зі статусом відхилено (rejected) або помилка (failed) можна надіслати повторно після усунення причини. Якщо точка доступу одразу відхиляє рахунок, наприклад, через те, що клієнт не зареєстрований у Peppol, Nordlet показує причину, а рахунок залишається ненадісланим.

Кнопка Peppol XML у верхній частині сторінки рахунку дозволяє завантажити той самий файл Peppol без його надсилання.

Операції з постачання всередині ЄС (intra-EU supply) містять дату виставлення як дату постачання та країну клієнта як країну призначення відповідно до вимог правил Peppol.

Отримання рахунків

Коли точка доступу повідомляє про отриманий документ через вебхук (webhook), Nordlet завантажує файл Peppol із точки доступу. Отримані вашою компанією рахунки та кредитові ноти з'являються в розділі Закупівлі (Purchases) → Обробка документів (Document capture) з позначкою про отримання через Peppol від ідентифікатора Peppol відправника. Nordlet самостійно зчитує файл Peppol, тому для отримання не витрачаються кредити розпізнавання документів.

1. Відкрийте отриманий документ.
2. Перевірте постачальника, дати та позиції; виберіть постачальника зі списку вартих уваги контрагентів або створіть нового.
3. Натисніть Зберегти чернетку (Save draft). Nordlet створює чернетку вхідного рахунку або чернетку вхідної кредитової ноти (для отриманої кредитової ноти) з прикріпленим оригінальним файлом Peppol. Зареєструйте документ так само, як і будь-який інший вхідний рахунок.

Позиції вхідних рахунків у Nordlet не можуть мати від'ємних значень. Знижки та націнки на весь документ, а також від'ємні позиції пропорційно розподіляються між позиціями з однаковою ставкою ПДВ (VAT rate). Сума, яку неможливо розподілити на жодну позицію з відповідною ставкою ПДВ (наприклад, повернення товару зі ставкою ПДВ, для якої немає інших позицій у рахунку), виводиться в другій таблиці: Позиції кредитової ноти (Credit note lines) для отриманого рахунку або Позиції рахунку (Invoice lines) для отриманої кредитової ноти. Ці позиції зберігаються як окремий другий документ для того самого постачальника: вхідна кредитова нота до нового рахунку з номерами у форматі "<номер документа>-CR" або вхідний рахунок з номерами у форматі "<номер документа>-INV". Обидва документи в сумі складають підсумкові показники отриманого документа.

Перевірка реєстрації клієнта в мережі Peppol

Запит POST /v1/peppol/participants/lookup з параметром partnerId або participantId ("<схема>:<ідентифікатор>") перевіряє в мережі Peppol, чи зареєстрований отримувач і які документи він приймає. Ця функція працює без підключеної точки доступу (access point).

Виконання тих самих дій через API

Завдання	Виклик
Підключення точки доступу (access point)	POST /v1/declarations/configs/update з параметрами system: "peppol" та об'єктом config, що містить provider (recommand, storecove або e-invoice-be), accountId, apiKey, apiSecret, webhookSecret і необов'язковий параметр apiBaseUrl
Отримання вебхуку (webhook) від точки доступу	POST /v1/peppol/webhooks/{provider}/{companyId}, викликається точкою доступу
Завантаження файлу Peppol	POST /v1/sales/invoices/peppol-xml
Надсилання	POST /v1/sales/invoices/peppol-send (повертає 422 без підключеної точки доступу)
Читання статусу доставки	POST /v1/sales/invoices/peppol-status (повертає 422 для Storecove); рахунки містять поля peppolMessageId, peppolStatus, peppolDetail, peppolSentAt, peppolCheckedAt
Пошук отриманих документів	POST /v1/capture/documents/list; отримані документи мають поля provider: "peppol" та senderId
Перетворення на вхідний рахунок	POST /v1/capture/documents/confirm із параметром oppositeLines для другого документа

Події вебхуків (webhook): sale_invoice.peppol_sent, sale_invoice.peppol_delivered, sale_invoice.peppol_rejected, sale_invoice.peppol_failed та document_capture.peppol_received. Інформацію про помилки, ідемпотентність і вебхуки (webhooks) дивіться в розділі Угода щодо API.