Satış Faturası & İrsaliyeAPI v4

Satış Faturası ve İrsaliye Rehberi

Müşteri ve ürün hazırlığından başlayıp satış faturası oluşturma, tahsilat ekleme, e-Arşiv / e-Fatura / e-SMM olarak resmileştirme, PDF'leri müşteriye iletme, irsaliye düzenleme, e-İrsaliye gönderme ve irsaliyeyi faturayla eşleştirme adımlarını uçtan uca anlatır. Tüm örnekler aynı access_token ile çalışır; eğer henüz yoksa OAuth rehberine bakın.

Bu rehber Paraşüt API v4 sürümünü temel alır (base URL https://api.parasut.com/v4). v5 ve v4 → v5 geçiş rehberi yakında yayında.

Başlamadan Önce

ACCESS_TOKENOAuth Authorization Code akışı sonunda alınan Bearer token. Detay.

company_idFaturayı kesecek firma kimliği. GET /me?include=companies ile bulunur.

Base URLhttps://api.parasut.com/v4

Tüm istekler Authorization: Bearer ACCESS_TOKEN header'ı ve Accept: application/json ile gönderilir. POST/PATCH istekleri JSON gövdesi taşır.

Akışa Genel Bakış

Müşteri

Ürün

Fatura

Tahsilat

Resmileştir

PDF

1–3 zorunlu, 4–6 ihtiyaca göre opsiyoneldir. Müşteri ve ürünler bir kez oluşturulup tekrar tekrar kullanılır.

Adım Adım Fatura Akışı

Müşteriyi Hazırla

Faturanın kesileceği müşterinin Paraşüt'te bir id'si olmalı. Müşteri zaten kayıtlıysa arama yapın; yoksa oluşturun. Sonraki adımlarda bu CONTACT_ID kullanılacak.

Mevcut müşteri arama

curl — GET /contacts

curl -X GET "https://api.parasut.com/v4/{company_id}/contacts?filter[name]=Ahmet&filter[tax_number]=12345678901&page[size]=25" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Accept: application/json"

filter[name], filter[email], filter[tax_number] gibi filtrelerle arama yapılabilir.

Yeni müşteri oluşturma

curl — POST /contacts

curl -X POST https://api.parasut.com/v4/{company_id}/contacts \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "data": {
      "type": "contacts",
      "attributes": {
        "name": "Ahmet Yılmaz",
        "account_type": "customer",
        "contact_type": "person",
        "email": "[email protected]",
        "tax_number": "12345678901",
        "tax_office": "Kadıköy"
      }
    }
  }'

Alan	Tip / Örnek	Açıklama
name	string (zorunlu)	Müşteri/tedarikçi ismi
account_type	enum (zorunlu)	`customer` \| `supplier`
contact_type	enum	`person` \| `company`
email	string	E-posta adresi
tax_number	string	VKN veya TCKN
tax_office	string	Vergi dairesi
city	string	İl
district	string	İlçe
iban	string	IBAN

Yanıttaki data.id alanı bir sonraki adımda CONTACT_ID olarak kullanılır.

Ürün / Hizmeti Hazırla

Fatura kalemlerine eklenecek her ürün veya hizmetin bir id'si olmalı. Mevcut bir ürünü GET /products ile bulun ya da aşağıdaki gibi oluşturun.

curl — POST /products

curl -X POST https://api.parasut.com/v4/{company_id}/products \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "data": {
      "type": "products",
      "attributes": {
        "name": "Yazılım Lisansı",
        "code": "SW-001",
        "list_price": "1500.00",
        "currency": "TRL",
        "vat_rate": 20,
        "unit": "adet"
      }
    }
  }'

Alan	Tip / Örnek	Açıklama
name	string (zorunlu)	Ürün/hizmet ismi
code	string	Stok kodu / SKU
list_price	number	Satış fiyatı
currency	enum	`TRL` \| `USD` \| `EUR` \| `GBP`
vat_rate	number	KDV oranı (%)
unit	string	Birim (adet, saat, kg...)
inventory_tracking	boolean	Stok takibi yapılsın mı?

Satış Faturasını Oluştur

Müşteri ve ürün id'leri hazır olunca faturayı tek bir POST isteğiyle açabilirsiniz. details dizisindeki her eleman bir fatura kalemidir ve kendi product ilişkisini taşır.

curl — POST /sales_invoices

curl -X POST https://api.parasut.com/v4/{company_id}/sales_invoices \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "data": {
      "type": "sales_invoices",
      "attributes": {
        "item_type": "invoice",
        "issue_date": "2026-05-18",
        "due_date": "2026-06-17",
        "currency": "TRL",
        "invoice_series": "A",
        "invoice_id": 1
      },
      "relationships": {
        "contact": {
          "data": { "type": "contacts", "id": "CONTACT_ID" }
        },
        "details": {
          "data": [
            {
              "type": "sales_invoice_details",
              "attributes": {
                "quantity": 1,
                "unit_price": "1500.00",
                "vat_rate": 20,
                "discount_type": "percentage",
                "discount_value": "0"
              },
              "relationships": {
                "product": { "data": { "type": "products", "id": "PRODUCT_ID" } }
              }
            }
          ]
        }
      }
    }
  }'

Alan	Tip / Örnek	Açıklama
attributes.item_type	enum (zorunlu)	`invoice` \| `estimate` \| `cancelled` \| `refund` \| `export`
attributes.issue_date	date (zorunlu)	Düzenleme tarihi `YYYY-MM-DD`
attributes.due_date	date	Son tahsilat tarihi
attributes.currency	enum	`TRL` \| `USD` \| `EUR` \| `GBP`
attributes.exchange_rate	number	TRL dışı dövizler için kur
attributes.invoice_series	string	Fatura serisi (örn. `A`)
attributes.invoice_id	integer	Fatura sırası
attributes.order_no	string	Sipariş no; resmileştirmek için `order_date` doluysa zorunludur.
attributes.order_date	date	Sipariş tarihi; resmileştirmek için `order_no` doluysa zorunludur.
relationships.contact.data.id	string (zorunlu)	Müşterinin `id` değeri
relationships.details.data[]	array (zorunlu)	Her biri bir kalem; aşağıya bakın
relationships.external_reference_key.data	object	İdempotans anahtarı (`attributes.key`: UUID); aşağıdaki nota bakın.

Fatura kalemi (`details` elemanı)

Alan	Tip / Örnek	Açıklama
attributes.quantity	number (zorunlu)	Miktar
attributes.unit_price	number (zorunlu)	Birim fiyat
attributes.vat_rate	number (zorunlu)	KDV oranı (%)
attributes.discount_type	enum	`percentage` \| `amount`
attributes.discount_value	number	İndirim değeri
relationships.product.data.id	string	Ürünün `id` değeri

Dikkat: relationships.contact.data.id 1. adımda elde ettiğiniz müşteri id'sidir. details dizisindeki her elemanın relationships.product.data.id alanı, o kalemin ait olduğu ürünün id'sidir.

Tekrar denemede mükerrer faturayı önleme

JSON parçası — data.relationships içine

{
  "external_reference_key": {
    "data": {
      "type": "external_reference_keys",
      "attributes": { "key": "6f1c2a4e-9b3d-4e8a-a1f0-2c5d7e9b3a14" }
    }
  }
}

Tekrar deneme güvenliği: Zaman aşımı gibi durumlarda isteği tekrar gönderirseniz ikinci bir fatura açılabilir. Bunu önlemek için her yeni fatura için bir UUID üretip external_reference_key ilişkisiyle gönderin ve yeniden denerken aynı anahtarı kullanın. Anahtar daha önce kullanıldıysa ikinci fatura açılmaz; 422 Bu key ile daha önce bir fatura oluşturulmuş. döner ve hatanın meta.sales_invoice_id alanı mevcut faturayı verir. Geçersiz bir UUID 422 Gönderilen key geçerli bir UUID formatında değil. döner.

curl — GET /sales_invoices/find_by_external_reference_key

curl -X GET "https://api.parasut.com/v4/{company_id}/sales_invoices/find_by_external_reference_key?external_reference_key=6f1c2a4e-9b3d-4e8a-a1f0-2c5d7e9b3a14" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Accept: application/json"

Faturayı gönderdiğiniz anahtarla bu uçtan da bulabilirsiniz; anahtar bulunamazsa gövdesiz 404 döner.

Faturayı iptal etmek için DELETE /sales_invoices/{id}/cancel, iptali geri almak için PATCH /sales_invoices/{id}/recover kullanın; fatura iptalden önceki item_type değerine döner, iptal edilmemiş bir fatura için 422 döner. item_type: estimate olan bir kaydı PATCH /sales_invoices/{id}/convert_to_invoice ile faturaya çevirebilirsiniz; stok hareketleri varsayılan deponuzdan oluşur. Arşivlemek ve geri almak için PATCH /sales_invoices/{id}/archive ve PATCH /sales_invoices/{id}/unarchive kullanılır.

Tahsilat EkleOpsiyonel

Faturanın kapanması için müşteriden alınan ödemeyi /payments ucuyla işleyin. Aynı faturaya birden fazla kısmi tahsilat eklenebilir.

curl — POST /sales_invoices/{id}/payments

curl -X POST https://api.parasut.com/v4/{company_id}/sales_invoices/{invoice_id}/payments \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "data": {
      "type": "payments",
      "attributes": {
        "account_id": ACCOUNT_ID,
        "date": "2026-05-18",
        "amount": "1500.00",
        "description": "Havale"
      }
    }
  }'

Alan	Tip / Örnek	Açıklama
account_id	integer (zorunlu)	Kasa veya banka hesabı `id`. Para birimini de bu hesap belirler.
date	date (zorunlu)	Tahsilat tarihi `YYYY-MM-DD`
amount	number (zorunlu)	Tahsilat tutarı
description	string	Tahsilat açıklaması
exchange_rate	number	Fatura ile farklı kur kullanılacaksa TL karşılığı; aynı kur için boş bırakın.

Tahsilatı Geri AlDüzeltme

Tahsilat aslında bir para hareketidir. İptal etmek için önce o hareketin (transaction) id'sini bulup /transactions/{id} ucunu silersiniz.

1) curl — faturanın tahsilatlarını ve transaction id'lerini al

curl -X GET "https://api.parasut.com/v4/{company_id}/sales_invoices/{invoice_id}/payments?include=transaction&page[size]=100" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Accept: application/json"

Yanıttaki included dizisinde type: "transactions" elemanlarının id'si silinecek hareketin id'sidir. Liste sayfalıdır; page[size] en fazla 10000 olabilir. Aynı bilgiyi GET /sales_invoices/{id}?include=payments.transaction ile de alabilirsiniz.

2) curl — transaction'ı sil

curl -X DELETE https://api.parasut.com/v4/{company_id}/transactions/{transaction_id} \
  -H "Authorization: Bearer ACCESS_TOKEN"

DELETE /payments/{id} fatura tahsilatını geri almak için kullanılmaz: yalnızca contact_debit, employee_debit ve check_out işlemlerine bağlı ödemeleri siler, diğer ödemeler için 401 döner. Fatura tahsilatını geri almak için yukarıdaki gibi işlemi DELETE /transactions/{id} ile silin.

Faturayı Resmileştir (e-Arşiv / e-Fatura / e-SMM)Opsiyonel

Resmileştirme akışı beş alt adımdan oluşur: müşterinin e-Fatura mükellefi olup olmadığını sorgulayın, doğru e-belgeyi oluşturun, oluşturma işini takip edin, resmileşen belgenin id'sini alın ve e-Faturanın gönderim sonucunu kontrol edin. PDF'i 7. adımda alırsınız.

6.1 · Müşteri e-Fatura mükellefi mi?

curl — GET /e_invoice_inboxes

curl -X GET "https://api.parasut.com/v4/{company_id}/e_invoice_inboxes?filter[vkn]=12345678901" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Accept: application/json"

Boş bir liste dönerse müşteri e-Arşiv kullanıcısıdır; data dolu dönerse e-Fatura kullanıcısıdır. İhracat faturaları her zaman e-Fatura olarak kesilir.

6.2 · Doğru e-belgeyi oluştur

curl — POST /e_invoices (mükellef için)

curl -X POST https://api.parasut.com/v4/{company_id}/e_invoices \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "data": {
      "type": "e_invoices",
      "attributes": {
        "scenario": "commercial",
        "to": "urn:mail:[email protected]"
      },
      "relationships": {
        "invoice": { "data": { "type": "sales_invoices", "id": "INVOICE_ID" } }
      }
    }
  }'

curl — POST /e_archives (mükellef değilse)

curl -X POST https://api.parasut.com/v4/{company_id}/e_archives \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "data": {
      "type": "e_archives",
      "relationships": {
        "sales_invoice": { "data": { "type": "sales_invoices", "id": "INVOICE_ID" } }
      }
    }
  }'

202 başarı değildir. POST /e_archives ve POST /e_invoices belgeyi hemen oluşturmaz; 202 Accepted ile bir trackable job (data.type: trackable_jobs) döner ve işin id'si data.id alanındadır. İş done olana kadar e-belge yoktur; iş error ile biterse belge oluşmamıştır ve errors dizisindeki metinler nedeni açıklar. 202 yanıtını başarılı resmileştirme olarak kaydetmeyin, işi 6.3'teki gibi takip edin.

curl — POST /e_smms (serbest meslek makbuzu)

curl -X POST https://api.parasut.com/v4/{company_id}/e_smms \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "data": {
      "type": "e_smms",
      "relationships": {
        "sales_invoice": { "data": { "type": "sales_invoices", "id": "INVOICE_ID" } }
      }
    }
  }'

Makbuz kullanıcısıysanız POST /e_smms kullanın. e-SMM eşzamanlı oluşur: istek 201 ile doğrudan e-SMM kaydını döner, takip edilecek bir iş yoktur. 6.3–6.5'i atlayın; yanıttaki data.id ile 7. adımdaki GET /e_smms/{id}/pdf ucunu çağırın; kayıttaki pdf_url bir web uygulaması yoludur, API ile kullanılamaz.

Düzenleme tarihi, e-Fatura/e-SMM aktivasyon tarihinizden önce olamaz; ayrıca alıcının e-Fatura etiketini kullanmaya başladığı tarihten de önce olamaz. Etiket başlangıç tarihi e-Fatura gelen kutusu yanıtında görülür.

Staging ortamı: Staging hesaplarında e-belge entegrasyonu varsayılan olarak "Dummy Integration" olarak ayarlıdır. Faturalarınızı resmileştirebilirsiniz; ancak belgeler GİB'e gönderilmez, sonuçlar test amaçlı taklit edilir. Belge doğrulaması gerçek ortamdaki gibi yapılır.

Hata senaryolarını nasıl test ederim?

Staging'de GİB ve alıcı yanıtlarını taklit etmek için satış faturasının invoice_note (Fatura notu) alanına, resmileştirmeden önce, anahtar= değer; biçiminde direktif yazabilirsiniz. Değerlerde yalnızca İngilizce harf, rakam, boşluk, nokta ve virgül kullanın; Türkçe karakter içeren direktifler dikkate alınmaz. Direktif yazılmazsa belge başarıyla resmileşir. Aynı direktifler e-İrsaliye için de geçerlidir; e-SMM'de POST /e_smms isteğinin note alanına yazın.

Alan	Tip / Örnek	Açıklama
gib_status_code	1195	e-Fatura, e-İrsaliye: GİB durum kodu. `1300` (varsayılan) başarılı; `1000`, `1100`, `1200`, `1210`, `1220` bekliyor durumunda kalır; diğerleri hata (ör. `1150` Schematron hatası, `1163` mükerrer fatura, `1195` sistem hatası).
gib_status_description	Gonderilemedi	e-Fatura, e-İrsaliye: durum açıklaması.
response_type	RED	Ticari e-Fatura: alıcıdan red yanıtı. Yazılmazsa kabul yanıtı gelir.
response_description	Urunler eksik	Ticari e-Fatura: red gerekçesi; yazılmazsa varsayılan metin.
report_id	R123	e-Arşiv: GİB rapor kimliği; `report_gib_status_code` ile birlikte verilmelidir.
report_gib_status_code	1300	e-Arşiv: GİB rapor durum kodu; açıklama için `report_gib_status_description`.
e_archive_sms	WRONG	e-Arşiv (SMS onaylı): SMS onayı başarısız olur.
e_archive_confirm	FALSE	e-Arşiv (SMS onaylı): içe aktarma onayı başarısız olur.

invoice_note — örnek direktifler

gib_status_code= 1195; gib_status_description= Beklenmedik bir hata olustu;
response_type= RED; response_description= Urunler eksik oldugu icin reddedildi;

İpucu: alıcı olarak kendi VKN'inizi yazarsanız gönderdiğiniz e-Fatura ve e-İrsaliye gelen kutunuza da düşer.

6.3 · İşi takip et

6.2'deki 202 yanıtının data.id değerini (trackable job id) polling ile sorgulayın. İşin durumu, son güncellenmesinden sonra 15 dakika boyunca sorgulanabilir.

curl — GET /trackable_jobs/{id}

curl -X GET https://api.parasut.com/v4/{company_id}/trackable_jobs/{trackable_job_id} \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Accept: application/json"

Alan	Tip / Örnek	Açıklama
status: "running"	Sürüyor	İşlem yapılıyor; bir süre sonra tekrar sorgulayın.
status: "error"	Hata	Belge oluşmadı; yanıttaki `errors` dizisi (metin listesi) hatayı açıklar.
status: "done"	Başarılı	e-belge oluşturuldu; 6.4'e geçin.

Polling'e ek olarak webhook kullanabilirsiniz: sales_invoice update event'i yalnızca e-Arşiv ya da e-Fatura'sı olan faturalar için gönderilir (e-SMM'si olanlar için gönderilmez) ve PDF oluştuğunda verisine 2 saat geçerli bir pdf_url eklenir. İrsaliyeler için shipment_document event'leri vardır. Ayrıntılar için Webhook rehberine bakın.

6.4 · Resmileşen belgenin id'sini al

curl — GET /sales_invoices/{id}?include=active_e_document

curl -X GET "https://api.parasut.com/v4/{company_id}/sales_invoices/{invoice_id}?include=active_e_document" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Accept: application/json"

active_e_document ilişkisinde oluşturulan e-belgenin id'si döner; type alanı e_archives, e_invoices ya da e-SMM için e_smms olur.

6.5 · e-Fatura sonucunu kontrol et ve yeniden gönder

e-Fatura oluştuktan sonra GİB/entegratör sonucu e-Fatura kaydına yazılır. 6.4'te aldığınız e-Fatura id'si ile kaydı okuyun.

curl — GET /e_invoices/{id}

curl -X GET https://api.parasut.com/v4/{company_id}/e_invoices/{e_invoice_id} \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Accept: application/json"

Alan	Tip / Örnek	Açıklama
attributes.status	enum	`waiting` (bekliyor) \| `failed` (başarısız) \| `successful` (başarılı)
attributes.status_code	string	GİB/entegratör durum kodu (ör. `1300` başarılı). `status` bu koddan türetilir; durum henüz belli değilse boş olabilir.
attributes.status_message	string	`status_code` açıklaması; gönderim hata aldığında nedenini içerir, boş olabilir.

Durum failed ise e-Faturayı yeniden gönderebilirsiniz. Yanıt yine 202 ve bir trackable job döner; işi 6.3'teki gibi takip edin.

curl — PATCH /e_invoices/{id}/resend

curl -X PATCH https://api.parasut.com/v4/{company_id}/e_invoices/{e_invoice_id}/resend \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Accept: application/json"

Yeniden gönderim yalnızca status: failed olan e-Faturalar içindir. Durumu failed olmayan e-Faturalar için, firmanın aktif bir e-Fatura entegrasyonu yoksa ya da aynı satış faturası için gönderim zaten sürüyorsa 422 döner. Entegrasyona bağlı olarak status_code da kontrol edilir: kod yeniden gönderime uygun değilse istek yine 202 ile kabul edilir, ancak iş error ve E-faturanız yeniden gönderime uygun değil hatasıyla biter. Uygun kodlar API dokümantasyonunda resendEInvoice ucunun açıklamasında listelenir.

PDF'i Müşteriye İletOpsiyonel

Resmileşen belgenin PDF'i hazır olunca üretilir. Endpoint hazır değilse 204 No Content döner; 200 alana kadar belirli aralıklarla tekrar isteyin.

curl — GET /e_archives/{id}/pdf

curl -X GET https://api.parasut.com/v4/{company_id}/e_archives/{id}/pdf \
  -H "Authorization: Bearer ACCESS_TOKEN"

Alan	Tip / Örnek	Açıklama
e-Arşiv	GET /e_archives/{id}/pdf	showEArchivePdf
e-Fatura	GET /e_invoices/{id}/pdf	showEInvoicePdf
e-SMM	GET /e_smms/{id}/pdf	showESmmPdf
e-Arşiv imzalı UBL	GET /e_archives/{id}/signed_ubl	showEArchiveSignedUbl
e-Fatura imzalı UBL	GET /e_invoices/{id}/signed_ubl	showEInvoiceSignedUbl

PDF yanıtındaki url yalnızca expires_at alanındaki zamana kadar geçerlidir; süresi dolunca uca yeniden istek atın. Bu linki doğrudan müşteriyle paylaşmayın; PDF'i indirip kendi sisteminizden iletmeniz beklenir.

İmzalı UBL (XML) uçları dosyayı 200 ile döner ya da sağlayıcıdaki dosyaya 302 ile yönlendirir. Dosya henüz hazır değilse düz metin signed ubl is not ready ile 404 döner ve dosya arka planda hazırlanır; bir süre sonra tekrar deneyin.

Tekliften Satış Faturası Oluşturma

Daha önce verilen bir teklifi (sales_offer) faturaya çevirmek için akış kısalır: teklifi okuyun, alanlarını fatura gövdesine taşıyın ve relationships.sales_offer ile ilişkilendirin.

1. Faturalanacak teklife GET /sales_offers/{id}?include=details.product,contact isteğiyle erişin.

2. Yanıttaki included dizisinde gelen müşteri (contacts), teklif kalemleri ve kalemlerin ürünleri, POST /sales_invoices gövdesindeki relationships alanlarına haritalanır. Kalemleri ürünleriyle birlikte GET /sales_offers/{id}/details?include=product ile ayrıca da okuyabilirsiniz.

3. Yeni faturanın relationships.sales_offer.data alanına teklifin id'sini ve type: "sales_offers" değerini ekleyin.

curl — POST /sales_invoices (tekliften)

curl -X POST https://api.parasut.com/v4/{company_id}/sales_invoices \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "type": "sales_invoices",
      "attributes": { "item_type": "invoice", "issue_date": "2026-05-18" },
      "relationships": {
        "contact": { "data": { "type": "contacts", "id": "CONTACT_ID" } },
        "sales_offer": { "data": { "type": "sales_offers", "id": "OFFER_ID" } },
        "details": {
          "data": [ /* sales_offer detaylarından üretin */ ]
        }
      }
    }
  }'

Özel Gereksinim Duyan Firmalar

Bazı alıcılar standart e-Fatura alanlarının dışında ek bilgi bekler. Bu alanlar satış faturası gövdesine değil, e-Fatura oluştururken (6.2, POST /e_invoices) data.attributes.custom_requirement_params içine yerleştirilir.

SGK

JSON parçası — POST /e_invoices data.attributes

{
  "custom_requirement_params": {
    "integration": {
      "data": {
        "additional_invoice_type": "SAGLIK_ECZ",
        "tax_payer_code": "xx",
        "tax_payer_name": "xx",
        "file_number": "xx",
        "term_start_date": "2026-01-02",
        "term_end_date": "2026-01-04"
      }
    }
  }
}

Alan	Tip / Örnek	Açıklama
additional_invoice_type	enum	İlave fatura tipi (aşağıdaki listeden biri)
tax_payer_code	string	Mükellef kodu
tax_payer_name	string	Mükellef adı
file_number	string	Dosya numarası
term_start_date	date	Dönem başlangıcı
term_end_date	date	Dönem bitişi

additional_invoice_type değerleri: SAGLIK_ECZ, SAGLIK_HAS, SAGLIK_OPT, SAGLIK_MED, ABONELIK, MAL_HIZMET, DIGER

Amazon

Amazon'a kesilen faturalarda adres bilgileri standart, sipariş no/tarihi ise zorunludur. Bu alanlar satış faturasının attributes alanlarıdır. Tedarikçi kodu ve EAN/ASIN kodları e-Fatura isteğinin custom_requirement_params alanı üzerinden geçirilir.

Alan	Tip / Örnek	Açıklama
billing_address	string	Esentepe Mah. Bahar Sk. No: 13/52
billing_postal_code	34394	Posta kodu
tax_office	Zincirlikuyu	Vergi dairesi
district	Şişli	İlçe
city	İstanbul	İl
order_no	string (zorunlu)	Amazon sipariş no
order_date	date (zorunlu)	Sipariş tarihi

JSON parçası — POST /e_invoices data.attributes (supplier_code + ürün buyer_code)

{
  "custom_requirement_params": {
    "integration": {
      "data": { "supplier_code": "210" }
    },
    "products": [
      { "product_id": 1, "data": { "buyer_code": "B01M7UN8RS" } },
      { "product_id": 2, "data": { "buyer_code": "B0186FESVC" } }
    ]
  }
}

İrsaliye Oluşturma

İrsaliye akışı, satış faturasıyla yapısal olarak çok benzer: bir müşteri/tedarikçi ve bir veya daha fazla ürün id'si gerekir. Müşteri ve ürün hazırlığı için yukarıdaki 1. ve 2. adımları kullanın; aynı createContact ve createProduct uç noktaları burada da geçerlidir.

Aradaki temel fark, fatura kalemleri yerine relationships.stock_movements dizisi kullanılması ve inflow alanı ile irsaliye yönünün belirlenmesidir (false = sevk irsaliyesi /true = giriş irsaliyesi).

curl — POST /shipment_documents

curl -X POST https://api.parasut.com/v4/{company_id}/shipment_documents \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "data": {
      "type": "shipment_documents",
      "attributes": {
        "issue_date": "2026-05-18",
        "shipment_date": "2026-05-18T10:00:00Z",
        "inflow": false,
        "description": "Mayıs ayı sevkiyatı",
        "address": "Esentepe Mh. Bahar Sk. No: 13/52",
        "district": "Şişli",
        "city": "İstanbul"
      },
      "relationships": {
        "contact": {
          "data": { "type": "contacts", "id": "CONTACT_ID" }
        },
        "stock_movements": {
          "data": [
            {
              "type": "stock_movements",
              "attributes": { "quantity": 5 },
              "relationships": {
                "product": { "data": { "type": "products", "id": "PRODUCT_ID" } }
              }
            }
          ]
        }
      }
    }
  }'

Alan	Tip / Örnek	Açıklama
attributes.issue_date	date (zorunlu)	Düzenleme tarihi `YYYY-MM-DD`
attributes.shipment_date	date-time	Fiili sevk tarihi
attributes.inflow	boolean	İrsaliye yönü: `false` (sevk) / `true` (giriş)
attributes.description	string	İrsaliye açıklaması
attributes.address	string	Sevkiyat adresi
attributes.district	string	İlçe
attributes.city	string	İl
attributes.procurement_number	string	İrsaliye numarası (boş bırakılırsa sistem üretir)
relationships.contact.data.id	string (zorunlu)	Müşteri/tedarikçinin `id` değeri
relationships.stock_movements.data[]	array (zorunlu)	İrsaliye kalemleri; aşağıya bakın

İrsaliye kalemi (`stock_movements` elemanı)

Alan	Tip / Örnek	Açıklama
attributes.quantity	number (zorunlu)	Sevk edilen miktar
relationships.product.data.id	string	Ürünün `id` değeri
relationships.warehouse.data.id	string	Depo `id`'si (depo takibi varsa)

Dikkat: stock_movements dizisindeki her eleman bir ürün kalemine karşılık gelir; relationships.product.data.id alanı 2. adımda elde ettiğiniz ürün id'sidir.

İrsaliyeyi PATCH /shipment_documents/{id}/archive ile arşivleyip PATCH /shipment_documents/{id}/unarchive ile geri alabilirsiniz. Arşivlemede zaten arşivlenmiş, arşivden çıkarmada arşivde olmayan irsaliyeler ve her iki durumda e-İrsaliye gönderimi süren giden irsaliyeler için 422 döner.

Giden İrsaliyeyi e-İrsaliye Olarak GönderOpsiyonel

Sevk irsaliyesini (inflow: false) e-İrsaliye olarak resmileştirme akışı dört alt adımdan oluşur: alıcının posta kutusunu bulun, irsaliyeyi resmileştirin, sonucu kontrol edin ve PDF/UBL dosyasını alın.

1 · Alıcının e-İrsaliye posta kutusunu bul

curl — GET /e_despatch_inboxes

curl -X GET "https://api.parasut.com/v4/{company_id}/e_despatch_inboxes?tax_number=12345678901" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Accept: application/json"

tax_number (VKN veya TCKN) zorunlu bir sorgu parametresidir; filter[...] biçiminde gönderilmez. Yanıt alıcının aktif e-İrsaliye posta kutularını listeler; her kaydın alias alanı posta kutusu etiketidir.

2 · İrsaliyeyi resmileştir

curl — POST /shipment_documents/{id}/legalize

curl -X POST https://api.parasut.com/v4/{company_id}/shipment_documents/{shipment_document_id}/legalize \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "data": {
      "attributes": { "to": "urn:mail:[email protected]" }
    }
  }'

Gövde opsiyoneldir; data.attributes.to alanına 1. adımdaki alias değerini yazın. Yanıt 202 ve bir trackable job döner: işin id'si data.id alanındadır, işi 6.3'teki gibi GET /trackable_jobs/{id} ile takip edin. Gönderim tamamlandığında irsaliyenin status alanı güncellenir.

Firmanın aktif bir e-İrsaliye entegrasyonu yoksa ya da aynı irsaliye için gönderim zaten sürüyorsa 422 döner. İrsaliye arşivlenmişse, daha önce resmileştirilmişse (status dolu) ya da firmanın e-belge kontörü bitmişse istek yine 202 ile kabul edilir, ancak iş error ile biter.

3 · Sonucu kontrol et ve gerekirse yeniden gönder

curl — GET /shipment_documents/{id}

curl -X GET https://api.parasut.com/v4/{company_id}/shipment_documents/{shipment_document_id} \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Accept: application/json"

Alan	Tip / Örnek	Açıklama
attributes.status	enum	`waiting` (bekliyor) \| `failed` (başarısız) \| `legalized` (resmileşti); irsaliye resmileştirilmemişse boştur.
attributes.status_message	string	Durum açıklaması; gönderim hata aldığında nedenini içerir, boş olabilir.
attributes.despatch_no	string	e-İrsaliye numarası
attributes.uuid	string	e-İrsaliye UUID'si
attributes.legalized_at	date-time	Resmileştirme tarihi

Zarf bilgileri (env_uuid, gib_status_code, despatch_no) için GET /shipment_documents/{id}/e_despatch ucunu kullanın. Durum failed ise irsaliyeyi yeniden gönderebilirsiniz; yanıt yine 202 ve bir trackable job döner.

curl — PATCH /shipment_documents/{id}/resend

curl -X PATCH https://api.parasut.com/v4/{company_id}/shipment_documents/{shipment_document_id}/resend \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Accept: application/json"

Firmanın aktif bir e-İrsaliye entegrasyonu yoksa ya da aynı irsaliye için gönderim zaten sürüyorsa 422 döner. İrsaliyenin durumu failed değilse (Sadece gönderimi başarısız olan irsaliyeler tekrar gönderilebilir), irsaliye arşivlenmişse ya da e-belge kontörü bitmişse istek yine 202 ile kabul edilir, ancak iş error ile biter.

4 · PDF ve UBL dosyasını al

Alan	Tip / Örnek	Açıklama
e-İrsaliye PDF	GET /shipment_documents/{id}/pdf	showEDespatchPdf
e-İrsaliye UBL	GET /shipment_documents/{id}/ubl	showEDespatchUbl

İki uç da dosya henüz hazır değilse 204 döner; bir süre sonra tekrar isteyin. PDF ucu bir bağlantı (url, expires_at) ya da PDF dosyasının kendisini dönebilir. UBL ucu zip dosyası indirir ve yalnızca giden irsaliyelerde çalışır: gelen irsaliyede 404, aktif e-İrsaliye entegrasyonu yoksa 422 Bu firmaya ait aktif bir e-irsaliye entegrasyonu bulunmamaktadır. döner.

Fatura ile İrsaliyeyi Eşleştirme

Aynı satışa ait satış faturası ile giden irsaliyeyi birbirine bağlayabilirsiniz. Bağlantı faturadan ya da irsaliyeden kurulabilir; irsaliyeye bağlı faturaları GET /shipment_documents/{id}?include=invoices ile görürsünüz.

curl — POST /sales_invoices/{id}/link_shipment_documents

curl -X POST https://api.parasut.com/v4/{company_id}/sales_invoices/{invoice_id}/link_shipment_documents \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "data": { "shipment_document_ids": [SHIPMENT_DOCUMENT_ID] }
  }'

201 ile satış faturası ve bağlı irsaliyeler döner. Aynı bağlantıyı irsaliye tarafından kurmak için:

curl — POST /shipment_documents/{id}/link_invoices

curl -X POST https://api.parasut.com/v4/{company_id}/shipment_documents/{shipment_document_id}/link_invoices \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "data": { "invoice_type": "sales_invoices", "invoice_ids": [INVOICE_ID] }
  }'

Alan	Tip / Örnek	Açıklama
data.invoice_type	enum (zorunlu)	Giden irsaliye için `sales_invoices`, gelen irsaliye için `purchase_bills`; yanlış yön 400 döner.
data.invoice_ids	integer[] (zorunlu)	Fatura id'leri

Bağlantıyı kaldırmak için aynı gövdeyle DELETE isteği gönderin. Yanıt 200 ile irsaliyeyi ve kalan bağlı faturaları döner; bağlı olmayan faturalar sessizce atlanır, istek güvenle tekrarlanabilir.

curl — DELETE /shipment_documents/{id}/unlink_invoices

curl -X DELETE https://api.parasut.com/v4/{company_id}/shipment_documents/{shipment_document_id}/unlink_invoices \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "data": { "invoice_type": "sales_invoices", "invoice_ids": [INVOICE_ID] }
  }'

Gövde JSON:API kaynak nesnesi değil, düz bir data nesnesidir (type ya da attributes yok). İşlem bütünseldir: biri bağlanamazsa hiçbiri bağlanmaz. Stok entegrasyonunun açık olması gerekir. İrsaliyeli faturalar (shipment_included), iptal edilmiş, arşivlenmiş ve proforma faturalar, tekrarlama şablonları ve zaten eşleştirilmiş çiftler 422 döner (ör. İrsaliyeli faturalar ile başka irsaliyeler eşleştirilemez, İrsaliye ile Fatura hali hazırda eşleştirilmiş.).

Hızlı Referans

Bu Rehberde Geçen Tüm Uç Noktalar

MEGEThttps://api.parasut.com/v4/me

CONTACTSGET / POSThttps://api.parasut.com/v4/{company_id}/contacts

PRODUCTSGET / POSThttps://api.parasut.com/v4/{company_id}/products

SALES INVOICEPOSThttps://api.parasut.com/v4/{company_id}/sales_invoices

SALES INVOICEGEThttps://api.parasut.com/v4/{company_id}/sales_invoices/{id}

SALES INVOICEGEThttps://api.parasut.com/v4/{company_id}/sales_invoices/find_by_external_reference_key

SALES INVOICEDELETEhttps://api.parasut.com/v4/{company_id}/sales_invoices/{id}/cancel

SALES INVOICEPATCHhttps://api.parasut.com/v4/{company_id}/sales_invoices/{id}/recover

SALES INVOICEPATCHhttps://api.parasut.com/v4/{company_id}/sales_invoices/{id}/convert_to_invoice

SALES INVOICEPATCHhttps://api.parasut.com/v4/{company_id}/sales_invoices/{id}/archive

SALES INVOICEPATCHhttps://api.parasut.com/v4/{company_id}/sales_invoices/{id}/unarchive

PAYMENTGET / POSThttps://api.parasut.com/v4/{company_id}/sales_invoices/{id}/payments

TRANSACTIONDELETEhttps://api.parasut.com/v4/{company_id}/transactions/{id}

E-INVOICE INBOXESGEThttps://api.parasut.com/v4/{company_id}/e_invoice_inboxes

E-ARCHIVEPOSThttps://api.parasut.com/v4/{company_id}/e_archives

E-INVOICEPOSThttps://api.parasut.com/v4/{company_id}/e_invoices

E-INVOICEGEThttps://api.parasut.com/v4/{company_id}/e_invoices/{id}

E-INVOICEPATCHhttps://api.parasut.com/v4/{company_id}/e_invoices/{id}/resend

E-SMMPOSThttps://api.parasut.com/v4/{company_id}/e_smms

TRACKABLE JOBGEThttps://api.parasut.com/v4/{company_id}/trackable_jobs/{id}

E-ARCHIVE PDFGEThttps://api.parasut.com/v4/{company_id}/e_archives/{id}/pdf

E-INVOICE PDFGEThttps://api.parasut.com/v4/{company_id}/e_invoices/{id}/pdf

E-SMM PDFGEThttps://api.parasut.com/v4/{company_id}/e_smms/{id}/pdf

E-ARCHIVE UBLGEThttps://api.parasut.com/v4/{company_id}/e_archives/{id}/signed_ubl

E-INVOICE UBLGEThttps://api.parasut.com/v4/{company_id}/e_invoices/{id}/signed_ubl

SALES OFFERGEThttps://api.parasut.com/v4/{company_id}/sales_offers/{id}

SALES OFFERGEThttps://api.parasut.com/v4/{company_id}/sales_offers/{id}/details

SHIPMENT DOCPOSThttps://api.parasut.com/v4/{company_id}/shipment_documents

SHIPMENT DOCGEThttps://api.parasut.com/v4/{company_id}/shipment_documents/{id}

SHIPMENT DOCPATCHhttps://api.parasut.com/v4/{company_id}/shipment_documents/{id}/archive

SHIPMENT DOCPATCHhttps://api.parasut.com/v4/{company_id}/shipment_documents/{id}/unarchive

E-DESPATCH INBOXESGEThttps://api.parasut.com/v4/{company_id}/e_despatch_inboxes

E-DESPATCHPOSThttps://api.parasut.com/v4/{company_id}/shipment_documents/{id}/legalize

E-DESPATCHPATCHhttps://api.parasut.com/v4/{company_id}/shipment_documents/{id}/resend

E-DESPATCHGEThttps://api.parasut.com/v4/{company_id}/shipment_documents/{id}/e_despatch

E-DESPATCH PDFGEThttps://api.parasut.com/v4/{company_id}/shipment_documents/{id}/pdf

E-DESPATCH UBLGEThttps://api.parasut.com/v4/{company_id}/shipment_documents/{id}/ubl

LINKPOSThttps://api.parasut.com/v4/{company_id}/sales_invoices/{id}/link_shipment_documents

LINKPOSThttps://api.parasut.com/v4/{company_id}/shipment_documents/{id}/link_invoices

LINKDELETEhttps://api.parasut.com/v4/{company_id}/shipment_documents/{id}/unlink_invoices

Her uç noktanın tam parametre şeması için API dokümantasyonuna bakın.

OAuth Rehberi API Dokümantasyonu Webhook Rehberi Kaynaklar