Peppol ile e-fatura gönderme ve alma

Peppol, işletmeler ve kamu kurumları arasında yapılandırılmış e-faturaların değişimi için kullanılan Avrupa ağıdır. Her fatura, gönderenin erişim noktasından alıcının erişim noktasına iletilir. Nordlet; Peppol BIS Billing 3.0 standartlarında faturalar ve alacak dekontları (credit note) oluşturur, bunları şirketinizin kendi erişim noktası hesabı aracılığıyla gönderir ve alır.

Peppol; erişim noktalarının birbirleriyle nasıl belge alışverişi yapacağına ilişkin kuralları belirler, ancak yazılımınızın kendi erişim noktasıyla nasıl iletişim kuracağına karışmaz; her sağlayıcının kendine ait bir API'si vardır. Nordlet şu sağlayıcılarla çalışır:

Sağlayıcı	Gönderim	İletim durumu	Alım
Recommand	evet	webhook ile ve talep üzerine	evet
Storecove	evet	yalnızca webhook ile	evet
e-invoice.be	evet	webhook ile ve talep üzerine	evet

Bir erişim noktası olmasa bile Nordlet, düzenlenen her fatura ve alacak dekontunun Peppol dosyasını indirip başka bir yolla iletmeniz için hazırlar; ancak kendisi hiçbir şey gönderemez veya alamaz.

İhtiyacınız olanlar

• Yukarıdaki sağlayıcılardan birinde açılmış bir hesap ve şirketinizin bu sağlayıcı üzerinden Peppol'e kaydedilmiş olması. Her sağlayıcı kendi hizmeti için ücret tahsil eder; ilgili fiyat listesini inceleyin.
• Nordlet'ta şirketin KDV numarası, tescil numarası veya Peppol kimliği (Hesap (Account) → Şirketler (Companies) → Peppol Kimliği (Peppol ID)). Fatura gönderdiğiniz her müşterinin de iş ortağı kartında (partner card) bu bilgilerden birine sahip olması gerekir.

Erişim noktanızı bağlama

Hesap (Account) → Mevzuata Uyumluluk (Compliance) → AB (EU) → Peppol erişim noktası (Peppol access point) bölümünü açın, Sağlayıcı (Provider) alanından sağlayıcınızı seçin, ilgili sağlayıcı için aşağıda açıklanan alanları doldurup kaydedin. Sağlayıcınız size farklı bir adres vermediyse API temel URL'si (API base URL) alanını boş bırakın. Kaydettikten sonra sayfada şirketinizin Webhook URL adresi görünür: https://api.nordlet.com/v1/peppol/webhooks/{provider}/{companyId}. Burada {provider} değeri recommand, storecove veya e-invoice-be, {companyId} ise şirketinizin kimlik numarasıdır. Her Nordlet şirketinin kendi webhook URL'si vardır.

Nordlet, bir webhook çağrısını yalnızca webhook gizli anahtarınızı (webhook secret) bildiğini kanıtladığı takdirde kabul eder; dolayısıyla erişim noktası hesabınızdan gelmeyen çağrılar reddedilir. Nordlet, yalnızca erişim noktanızı çağırırken kamusal internet adresleriyle iletişim kurar.

Recommand

1. Recommand'da şirketinizi açın ve şirket kimliğini (company ID) kopyalayarak Erişim noktasındaki hesap kimliği (Account ID at the access point) alanına yapıştırın.
2. Recommand'da bir API anahtarı (API key) oluşturun; anahtarı ve gizli anahtarını kopyalayarak sırasıyla API anahtarı (API key) ve API gizli anahtarı (API secret) alanlarına yapıştırın.
3. Yalnızca sizin ve Recommand'ın bileceği uzun ve rastgele bir metin oluşturun ve bunu Webhook gizli anahtarı (Webhook secret) alanına girin. Kaydedin.
4. Recommand'da, Nordlet'ın gösterdiği Webhook URL adresini ve aynı webhook gizli anahtarını kullanarak şirketiniz için bir webhook oluşturun.

Recommand, her webhook çağrısını bu gizli anahtarla imzalar.

Storecove

1. Storecove'da şirketiniz için hem gönderim hem de alım yapabilecek şekilde ayarlanmış bir tüzel kişilik (legal entity) oluşturun ve kimlik numarasını kopyalayarak Erişim noktasındaki hesap kimliği (Account ID at the access point) alanına yapıştırın.
2. Storecove'da API Anahtarları (API Keys) altında bir API anahtarı oluşturun ve bunu API anahtarı (API key) alanına kopyalayın. API gizli anahtarı (API secret) alanını boş bırakın.
3. Uzun ve rastgele bir metin oluşturup Webhook gizli anahtarı (Webhook secret) alanına girin. Kaydedin.
4. Storecove'da, Nordlet'ın gösterdiği Webhook URL adresini kullanarak ve HTTP Temel Kimlik Doğrulaması (HTTP Basic authentication) ile korunan bir anında iletme (push) webhook'u ayarlayın: herhangi bir kullanıcı adı ve şifre olarak webhook gizli anahtarını kullanın.

Storecove'da gönderilen bir belgenin durumunu sorgulayan bir uç nokta (call) bulunmadığından, iletim durumu yalnızca webhook aracılığıyla alınır ve fatura sayfasında Peppol durumunu kontrol et (Check Peppol status) düğmesi yer almaz. Storecove korumalı alan (sandbox) hesabı, gönderimleri Peppol test ağı üzerinden yapar; üretim (production) API anahtarları Storecove destek ekibinden edinilir.

e-invoice.be

1. e-invoice.be uygulamasında API Ayarları (API Settings) altında şirketinizin API anahtarını kopyalayıp API anahtarı (API key) alanına yapıştırın. Erişim noktasındaki hesap kimliği (Account ID at the access point) ve API gizli anahtarı (API secret) alanlarını boş bırakın. Kaydedin.
2. e-invoice.be API'sini kullanarak (POST https://api.e-invoice.be/api/webhooks/) Nordlet'ın gösterdiği Webhook URL adresi ve document.received, document.sent ile document.sent.failed olaylarıyla (events) bir webhook oluşturun.
3. API'nin yeni webhook için döndürdüğü secret değerini kopyalayıp Nordlet'taki Webhook gizli anahtarı (Webhook secret) alanına yapıştırın ve tekrar kaydedin.

e-invoice.be, her webhook çağrısını bu gizli anahtarla imzalar. e-invoice.be üzerindeki korumalı alan (sandbox) şirketi, Peppol üzerinden göndereceği belgeleri gerçek ortamda göndermek yerine e-posta ile gönderir.

Fatura gönderme

1. Faturayı veya alacak dekontunu düzenleyin.
2. Müşterinin iş ortağı kartında bir Peppol kimliği, KDV numarası veya tescil numarası bulunduğunu kontrol edin.
3. Fatura sayfasındaki Teslimat (Delivery) bölümünde Peppol üzerinden gönder (Send via Peppol) seçeneğine tıklayın ve onaylayın. Teslimat bölümü henüz ödenmemiş düzenlenen faturalar için görüntülenir, düğme ise yalnızca erişim noktası bağlı olduğunda görünür.

Nordlet, Peppol dosyasını oluşturur ve erişim noktanıza iletir. Ardından fatura sayfasında bir Peppol teslimatı (Peppol delivery) bölümü görüntülenir:

Durum	Anlamı
pending	Erişim noktasına iletildi; müşterinin erişim noktası henüz onaylamadı
delivered	Müşterinin erişim noktası faturayı aldığını onayladı
rejected	Müşteri faturayı reddetti; gerekçesi durumun altında gösterilir
failed	Fatura iletilemedi; erişim noktası bir gerekçe sunduğunda bu gerekçe durumun altında gösterilir

Erişim noktası webhook aracılığıyla bir değişiklik bildirdiğinde durum otomatik olarak güncellenir. Peppol durumunu kontrol et (Check Peppol status) düğmesi, Recommand veya e-invoice.be sistemlerinden güncel durumu anında sorgular; e-invoice.be kullanıldığında ayrıca müşterinin fatura yanıtı okunur ve reddetme durumu (yanıt kodu RE) reddedildi (rejected) olarak görünür. Reddedilen veya başarısız olan bir fatura, hatanın nedenini düzelttikten sonra tekrar gönderilebilir. Erişim noktası, örneğin müşterinin Peppol'e kayıtlı olmaması nedeniyle faturayı doğrudan reddettiğinde Nordlet gerekçeyi gösterir ve fatura gönderilmemiş olarak kalır.

Fatura sayfasının üst kısmındaki Peppol XML düğmesi, gönderim yapmadan aynı Peppol dosyasını indirmenizi sağlar.

AB içi teslimatlarda Peppol kurallarının gereği olarak fatura tarihi teslim tarihi, müşterinin ülkesi ise teslim ülkesi olarak kabul edilir.

Fatura alma

Erişim noktası, webhook aracılığıyla alınan bir belgeyi bildirdiğinde Nordlet, Peppol dosyasını erişim noktasından indirir. Şirketinizin aldığı faturalar ve alacak dekontları Alışlar (Purchases) → Belge yakalama (Document capture) bölümünde, gönderenin Peppol kimliğinden Peppol üzerinden alınmış olarak işaretlenmiş şekilde görünür. Nordlet Peppol dosyasını doğrudan okur, bu nedenle alım işlemi belge tanıma kredisi (document recognition credits) harcamaz.

1. Alınan belgeyi açın.
2. Tedarikçiyi, tarihleri ve kalemleri kontrol edin; tedarikçiyi ortaklarınız arasından seçin veya yeni bir tedarikçi oluşturun.
3. Taslak olarak kaydet (Save draft) düğmesine tıklayın. Nordlet, ekinde orijinal Peppol dosyası bulunan taslak bir alış faturası (veya gelen alacak dekontu için taslak alış alacak dekontu) oluşturur. Bu belgeyi diğer herhangi bir alış faturası gibi kaydedin.

Nordlet alış faturası kalemleri negatif olamaz. Belgenin tamamına uygulanan indirimler, masraflar ve negatif kalemler, aynı KDV oranına sahip kalemlere dağıtılır. İade edilen bir ürünün faturadaki diğer hiçbir kalemde bulunmayan bir KDV oranına sahip olması gibi, ilgili KDV oranındaki hiçbir kalemin taşıyamayacağı bir tutar ikinci bir tabloda gösterilir: Gelen faturalar için Alacak dekontu kalemleri (Credit note lines) veya gelen alacak dekontları için Fatura kalemleri (Invoice lines). Bu kalemler, aynı tedarikçi için ikinci bir belge olarak kaydedilir: yeni faturaya ilişkin "<belge numarası>-CR" numaralı alış alacak dekontu veya "<belge numarası>-INV" numaralı alış faturası. Bu iki belge birlikte, alınan belgenin toplam tutarlarını tamamlar.

Bir müşterinin Peppol'de kayıtlı olup olmadığını kontrol etme

partnerId veya participantId ("<şema>:<tanımlayıcı>") parametreleriyle yapılan bir POST /v1/peppol/participants/lookup isteği, alıcının kayıtlı olup olmadığını ve hangi belgeleri kabul ettiğini Peppol ağından sorgular. Bu işlem erişim noktası olmadan da çalışır.

Aynı işlemleri API üzerinden yapma

Görev	Çağrı
Erişim noktasını bağlama	system: "peppol" ve sağlayıcı (recommand, storecove veya e-invoice-be), accountId, apiKey, apiSecret, webhookSecret ile isteğe bağlı apiBaseUrl içeren config parametresiyle birlikte POST /v1/declarations/configs/update
Erişim noktası webhook'unu alma	Erişim noktası tarafından çağrılan POST /v1/peppol/webhooks/{provider}/{companyId}
Peppol dosyasını indirme	POST /v1/sales/invoices/peppol-xml
Gönderme	POST /v1/sales/invoices/peppol-send (erişim noktası yoksa 422 hatası döndürür)
İletim durumunu okuma	POST /v1/sales/invoices/peppol-status (Storecove ile 422 hatası döndürür); faturalar peppolMessageId, peppolStatus, peppolDetail, peppolSentAt, peppolCheckedAt alanlarını içerir
Gelen belgeleri bulma	POST /v1/capture/documents/list; alınan belgeler provider: "peppol" ve senderId alanlarına sahiptir
Belgeyi alış faturasına dönüştürme	İkinci belge için oppositeLines parametresiyle birlikte POST /v1/capture/documents/confirm

Webhook olayları: sale_invoice.peppol_sent, sale_invoice.peppol_delivered, sale_invoice.peppol_rejected, sale_invoice.peppol_failed ve document_capture.peppol_received. Hatalar, eşdurumluluk (idempotency) ve webhook'lar için API kuralları sayfasına bakın.