Отправка и получение счетов с помощью Peppol

Peppol — это европейская сеть для обмена структурированными электронными счетами между компаниями и государственными органами. Каждый счет проходит путь от точки доступа отправителя до точки доступа получателя. Nordlet формирует счета и кредитовые ноты по стандарту Peppol BIS Billing 3.0, а также отправляет и получает их через учетную запись точки доступа вашей компании.

Peppol устанавливает правила обмена документами между точками доступа, но не регламентирует взаимодействие вашего программного обеспечения с собственной точкой доступа: у каждого провайдера свой API. Nordlet работает со следующими провайдерами:

Провайдер	Отправка	Статус доставки	Получение
Recommand	да	через вебхук и по запросу	да
Storecove	да	только через вебхук	да
e-invoice.be	да	через вебхук и по запросу	да

Если точка доступа не подключена, Nordlet все равно формирует файл Peppol для каждого выписанного счета и кредитовой ноты, чтобы вы могли скачать его и передать иным способом, однако отправка и получение документов в этом случае не производятся.

Что вам понадобится

• Учетная запись у одного из указанных выше провайдеров, через которую ваша компания зарегистрирована в сети Peppol. Каждый провайдер взимает плату за свои услуги, ознакомьтесь с его тарифными сетками.
• В системе Nordlet: ИНН, регистрационный номер компании или ее идентификатор Peppol (пункт меню Аккаунт (Account) -> Компании (Companies) -> Идентификатор Peppol (Peppol ID)). Данные реквизиты также должны быть указаны в карточке каждого контрагента, которому вы отправляете документы.

Подключение вашей точки доступа

Перейдите в раздел Аккаунт (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 вебхука.

Nordlet принимает вызов вебхука только в том случае, если он подтверждает знание вашего секретного ключа вебхука, поэтому запросы, поступающие не из вашей учетной записи у провайдера, отклоняются. Nordlet обращается к адресам общедоступного интернета исключительно при вызове вашей точки доступа.

Recommand

1. В системе Recommand откройте карточку вашей компании и скопируйте ее идентификатор компании в поле Идентификатор аккаунта в точке доступа (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 вебхука, который отображается в Nordlet, и тот же секрет вебхука.

Recommand подписывает каждый вызов вебхука этим секретным ключом.

Storecove

1. Создайте в Storecove юридическое лицо (legal entity) для вашей компании с включенными функциями отправки и получения, после чего скопируйте его идентификатор в поле Идентификатор аккаунта в точке доступа (Account ID at the access point).
2. В разделе Ключи API (API Keys) в Storecove создайте ключ API и скопируйте его в поле Ключ API (API key). Оставьте поле Секрет API (API secret) пустым.
3. Придумайте длинную случайную последовательность символов и введите ее в поле Секрет вебхука (Webhook secret). Сохраните изменения.
4. Настройте в Storecove отправку пуш-вебхуков на URL вебхука из Nordlet, защищенный с помощью базовой аутентификации HTTP (HTTP Basic authentication): в качестве имени пользователя можно указать любое значение, а в качестве пароля — секрет вебхука.

В Storecove отсутствует метод запроса статуса отправленного документа, поэтому статус доставки передается исключительно через вебхук, а на странице счета кнопка Проверить статус Peppol (Check Peppol status) не отображается. Учетная запись песочницы (sandbox) Storecove отправляет документы в тестовую сеть Peppol, а производственные ключи API можно получить через службу поддержки Storecove.

e-invoice.be

1. В приложении e-invoice.be в разделе Настройки API (API Settings) скопируйте ключ API вашей компании в поле Ключ 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 вебхука из Nordlet и события document.received, document.sent и document.sent.failed.
3. Скопируйте значение secret, возвращенное API для нового вебхука, в поле Секрет вебхука (Webhook secret) в Nordlet и повторно сохраните изменения.

e-invoice.be подписывает каждый вызов вебхука этим секретным ключом. Компания в песочнице на платформе e-invoice.be отправляет документы по электронной почте вместо их передачи через сеть Peppol.

Отправка счета

1. Выпишите счет или кредитовую ноту.
2. Убедитесь, что в карточке партнера (клиента) указаны его идентификатор Peppol, ИНН или регистрационный номер.
3. На странице счета в разделе Доставка (Delivery) нажмите кнопку Отправить через Peppol (Send via Peppol) и подтвердите действие. Раздел доставки отображается для неоплаченных выставленных счетов, а сама кнопка появляется только при подключенной точке доступа.

Nordlet формирует файл Peppol и передает его вашей точке доступа. После этого на странице счета появляется раздел Доставка Peppol (Peppol delivery):

Статус	Значение
pending	Передано в точку доступа; точка доступа клиента еще не подтвердила получение
delivered	Точка доступа клиента подтвердила получение счета
rejected	Клиент отклонил счет; причина указана под статусом
failed	Не удалось доставить счет; если точка доступа предоставила информацию, причина указана под статусом

Статус обновляется автоматически при поступлении информации об изменениях от точки доступа через вебхук. Кнопка Проверить статус Peppol (Check Peppol status) позволяет мгновенно запросить актуальный статус у Recommand или e-invoice.be; для e-invoice.be она также считывает ответ клиента по счету, причем отказ (код ответа RE) отображается как отклонение (rejected). Отклоненный или не прошедший отправку счет можно отправить повторно после устранения причины ошибки. Если точка доступа отклоняет счет сразу же (например, из-за того, что клиент не зарегистрирован в сети Peppol), Nordlet выводит причину отказа, а счет остается в статусе не отправленного.

Кнопка XML Peppol (Peppol XML) в верхней части страницы счета позволяет скачать аналогичный файл Peppol без его отправки.

В соответствии с требованиями правил Peppol, для поставок внутри Европейского союза датой поставки указывается дата выписки документа, а страной поставки — страна клиента.

Получение счетов

Когда точка доступа сообщает о полученном документе через вебхук, Nordlet скачивает файл Peppol из точки доступа. Полученные вашей компанией счета и кредитовые ноты появляются в разделе Покупки (Purchases) -> Распознавание документов (Document capture) с отметкой о получении через Peppol от идентификатора Peppol отправителя. Nordlet самостоятельно обрабатывает файл Peppol, поэтому при получении таких документов не расходуются кредиты распознавания.

1. Откройте полученный документ.
2. Проверьте данные поставщика, даты и товарные позиции; выберите поставщика из вашего справочника партнеров или создайте нового.
3. Нажмите Сохранить черновик (Save draft). Nordlet создаст черновик счета от поставщика (или черновик кредитовой ноты от поставщика при получении кредитовой ноты) с прикрепленным оригинальным файлом Peppol. Зарегистрируйте его стандартным для счетов от поставщиков образом.

Строки счетов от поставщиков в Nordlet не могут быть отрицательными. Скидки, наценки на документ в целом и отрицательные строки распределяются по строкам пропорционально ставкам НДС. Суммы, которые невозможно отнести ни к одной строке с соответствующей ставкой НДС (например, возврат товара по ставке НДС, отсутствующей в других строках счета), выводятся в отдельной таблице: Строки кредитовой ноты (Credit note lines) для полученного счета или Строки счета (Invoice lines) для полученной кредитовой ноты. Эти строки сохраняются как второй документ для того же поставщика: кредитовая нота от поставщика к новому счету с номером вида «<номер документа>-CR» либо счет от поставщика с номером вида «<номер документа>-INV». В совокупности оба документа полностью соответствуют итоговым суммам полученного документа.

Проверка регистрации клиента в сети Peppol

Запрос POST /v1/peppol/participants/lookup с параметром partnerId или participantId (в формате «<схема>:<идентификатор>») проверяет в сети Peppol, зарегистрирован ли получатель и какие типы документов он принимает. Эта функция работает и без подключенной точки доступа.

Выполнение аналогичных операций через API

Задача	Вызов API
Подключение точки доступа	POST /v1/declarations/configs/update с параметрами system: "peppol" и объектом config, содержащим поля provider (recommand, storecove или e-invoice-be), accountId, apiKey, apiSecret, webhookSecret и необязательное поле apiBaseUrl
Получение вебхука от точки доступа	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 для второго документа

События вебхуков: sale_invoice.peppol_sent, sale_invoice.peppol_delivered, sale_invoice.peppol_rejected, sale_invoice.peppol_failed и document_capture.peppol_received. Информацию об ошибках, идемпотентности и вебхуках см. в разделе Соглашения об API.