Изпращане и получаване на фактури чрез Peppol

Peppol е европейската мрежа за обмен на структурирани електронни фактури между фирми и държавни организации. Всяка фактура пътува от точката за достъп на подателя до точката за достъп на получателя. Nordlet генерира фактури и кредитни известия във формат Peppol BIS Billing 3.0 и ги изпраща и получава чрез акаунта на вашата собствена точка за достъп.

Peppol определя правилата за това как точките за достъп обменят документи помежду си, но не и как вашият софтуер комуникира с вашата точка за достъп: всеки доставчик има собствен API. Nordlet работи със следните доставчици:

Доставчик	Изпращане	Статус на доставка	Получаване
Recommand	да	чрез уебхук (webhook) и при поискване	да
Storecove	да	само чрез уебхук (webhook)	да
e-invoice.be	да	чрез уебхук (webhook) и при поискване	да

Без точка за достъп Nordlet все пак създава Peppol файла за всяка издадена фактура и кредитно известие, за да можете да го изтеглите и изпратите по друг начин; в този случай програмата не изпраща и не получава нищо автоматично.

Какво ви е необходимо

• Акаунт при някой от горните доставчици, като вашата компания е регистрирана в Peppol през него. Всеки доставчик таксува услугата си според собствената си ценова листа.
• В Nordlet: ДДС номерът, регистрационният номер или Peppol идентификаторът (Peppol ID) на компанията (от меню Акаунт (Account) → Компании (Companies) → 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 има собствен уебхук адрес (Webhook URL).

Nordlet приема уебхук заявка само когато тя докаже, че познава вашия уебхук секрет (webhook secret), така че заявка, която не идва от акаунта ви при доставчика, се отхвърля. Nordlet се свързва с публични интернет адреси само когато изпраща заявка към вашата точка за достъп.

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 адреса за уебхук, показан в Nordlet, и същия уебхук секрет.

Recommand подписва всяка уебхук заявка с този секрет.

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 уебхук с URL адреса за уебхук, показан в Nordlet, защитен с HTTP Basic удостоверяване: произволно потребителско име и уебхук секрета като парола.

Storecove няма метод за проверка на статуса на изпратен документ, затова при този доставчик статусът на доставката идва само от уебхука му и страницата на фактурата няма бутон Проверка на Peppol статуса (Check Peppol status). Тестовият акаунт (sandbox) в Storecove изпраща документи в тестовата мрежа на Peppol, докато производствените API ключове се получават от поддръжката на 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 адреса за уебхук, показан в Nordlet, и събитията document.received, document.sent и document.sent.failed.
3. Копирайте secret стойността, която API връща за новия уебхук, в полето Уебхук секрет (Webhook secret) в Nordlet и запазете отново.

e-invoice.be подписва всяка уебхук заявка с този секрет. Тестовата компания (sandbox) в 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 показва причината и фактурата остава неизпратена.

Бутонът Peppol XML в горната част на страницата на фактурата изтегля същия Peppol файл, без да го изпраща.

При вътреобщностна доставка за дата на данъчното събитие (дата на доставка) се попълва датата на издаване, а за държава на доставка - държавата на клиента, съгласно изискванията на правилата на Peppol.

Получаване на фактури

Когато точката за достъп докладва за получен документ чрез своя уебхук, Nordlet изтегля Peppol файла от точката за достъп. Получените от вашата компания фактури и кредитни известия се появяват в Покупки (Purchases) → Обработка на документи (Document capture), маркирани като получени през Peppol от Peppol идентификатора на подателя. Nordlet разчита Peppol файла самостоятелно, така че за получаването не се хабят кредити за разпознаване на документи.

1. Отворете получения документ.
2. Проверете доставчика, датите и редовете; изберете доставчика от вашите партньори или го създайте.
3. Щракнете върху Запази като чернова (Save draft). Nordlet създава чернова на входяща фактура (purchase invoice) или чернова на входящо кредитно известие (purchase credit note) за получено кредитно известие, с приложен оригинален Peppol файл. Регистрирайте я както всяка друга входяща фактура.

Редовете на входящите фактури в Nordlet не могат да бъдат отрицателни суми. Отстъпките, таксите за целия документ и отрицателните редове се разпределят пропорционално между редовете със същата данъчна ставка. Сума, която не може да бъде поета от никой ред с тази данъчна ставка (например върнат артикул с данъчна ставка, за която фактурата няма друг ред), се показва в втора таблица: Редове на кредитното известие (Credit note lines) за получена фактура или Редове на фактурата (Invoice lines) за получено кредитно известие. Тези редове се записват като втори документ за същия доставчик: входящо кредитно известие към новата фактура с номер „<номер на документ>-CR“ или входяща фактура с номер „<номер на документ>-INV“. Двата документа заедно образуват общите суми на получения документ.

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

Заявка POST /v1/peppol/participants/lookup с параметър partnerId или participantId (във формат „<схема>:<идентификатор>“) проверява в мрежата на Peppol дали получателят е регистриран и какви документи приема. Тази функция работи и без свързана точка за достъп.

Извършване на същите действия чрез 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 (API conventions) относно грешките, идемпотентността и уебхуковете.