Paraşüt API ile e-SMM: Satış Faturasından Serbest Meslek Makbuzu Oluşturma

e-SMM akışına genel bakış

• 1. Cari: makbuzun kesileceği müşteri Paraşüt'te kayıtlı olmalı (cari oluşturma).
• 2. Hizmet: kalemlerde kullanılacak hizmet ürün olarak tanımlı olabilir (ürün yönetimi).
• 3. Satış faturası: POST /{company_id}/sales_invoices ile kalemleri olan fatura açılır.
• 4. e-SMM: POST /{company_id}/e_smms ile fatura resmileştirilir; yanıt 201 ile doğrudan e-SMM kaydıdır.
• 5. PDF: GET /{company_id}/e_smms/{id}/pdf ile süreli bir indirme bağlantısı alınır.

e-SMM'yi diğer e-belgelerden ayıran noktaları bir tabloda toplayalım:

e-Fatura ve e-Arşiv akışı e-Fatura ve e-Arşiv gönderme yazısında ayrıntılı anlatılıyor.

Ön koşullar

• Paraşüt rehberinin ifadesiyle makbuz kullanıcısıysanız POST /e_smms kullanırsınız; yani firmanızın Paraşüt'te e-SMM için etkinleştirilmiş olması gerekir.
• Satış faturasının düzenleme tarihi (issue_date), e-Fatura/e-SMM aktivasyon tarihinizden önce olamaz.
• Geçerli bir access token ve company_id. Token almayı OAuth2 token alma yazısında anlattık.
• Tüm istekler https://api.parasut.com/v4/{company_id}/... yoluna, Authorization: Bearer header'ı ile gider; gövdeler application/vnd.api+json biçimindedir.

Adım 1: Satış faturasını oluşturun

e-SMM'nin kaynağı sıradan bir satış faturasıdır. Faturada zorunlu alanlar item_type ve issue_date; kalemlerde ise quantity, unit_price ve vat_rate. Para birimi TRL olarak yazılır (TRY değil). Tekrar denemelerde mükerrer fatura açılmaması için external_reference_key ilişkisini kullanın:

curl -X POST "https://api.parasut.com/v4/{company_id}/sales_invoices" \
  -H "Authorization: Bearer $PARASUT_ACCESS_TOKEN" \
  -H "Content-Type: application/vnd.api+json" \
  -d '{
    "data": {
      "type": "sales_invoices",
      "attributes": {
        "item_type": "invoice",
        "issue_date": "2026-11-03",
        "due_date": "2026-11-03",
        "currency": "TRL",
        "description": "Kasım danışmanlık hizmeti"
      },
      "relationships": {
        "contact": { "data": { "type": "contacts", "id": "{contact_id}" } },
        "external_reference_key": {
          "data": { "type": "external_reference_keys", "attributes": { "key": "{UUID}" } }
        },
        "details": {
          "data": [
            {
              "type": "sales_invoice_details",
              "attributes": { "quantity": 1, "unit_price": 10000, "vat_rate": 20 },
              "relationships": {
                "product": { "data": { "type": "products", "id": "{product_id}" } }
              }
            }
          ]
        }
      }
    }
  }'

Yanıttaki data.id faturanın kimliğidir; bir sonraki adımda kullanılır. Örnekteki KDV oranı yalnızca biçimi gösterir; hangi oranları uygulayacağınız sizin vergisel durumunuza bağlıdır.

Stopaj ve tevkifat alanları

API şemasında serbest meslek makbuzu senaryosunda karşınıza çıkabilecek alanlar şunlardır. Hangi oranın uygulanacağı vergi mevzuatına ve sizin durumunuza bağlıdır; burada yalnızca alanların API'deki yerini gösteriyoruz:

Salt okunur alanları (withholding, total_vat_withholding, net_total gibi) istek gövdesine koymayın; Paraşüt bunları hesaplar. Fatura oluşturmanın tüm ayrıntıları Paraşüt API ile fatura kesme yazısında.

Adım 2: Faturayı e-SMM olarak resmileştirin (POST /e_smms)

curl -X POST "https://api.parasut.com/v4/{company_id}/e_smms" \
  -H "Authorization: Bearer $PARASUT_ACCESS_TOKEN" \
  -H "Content-Type: application/vnd.api+json" \
  -d '{
    "data": {
      "type": "e_smms",
      "attributes": {
        "note": "Kasım 2026 danışmanlık hizmeti"
      },
      "relationships": {
        "sales_invoice": { "data": { "type": "sales_invoices", "id": "{invoice_id}" } }
      }
    }
  }'

Şemada data dışında zorunlu işaretlenmiş alan yoktur, ancak makbuzun hangi faturadan üretileceğini sales_invoice ilişkisi belirler; pratikte her istekte gönderilmelidir. Dikkat: e-Fatura'da bu ilişkinin adı invoice, e-Arşiv ve e-SMM'de sales_invoice'dır.

Yanıt: 201 ve doğrudan e-SMM kaydı

e-SMM eşzamanlı oluşur. e-Fatura ve e-Arşiv'deki gibi 202 ile bir trackable job dönmez, takip edilecek bir iş yoktur; istek 201 ile e-SMM kaydını döner. Kaydın özellikleri salt okunurdur:

Diğer belgelenmiş yanıt kodları 400, 401, 403, 404 ve 422'dir. Hata gövdesindeki errors dizisini kullanıcıya gösterin; hata metinleri değişebileceği için programatik ayrımı durum koduyla yapın. Ayrıntılar hata kodları ve rate limit yazısında.

Adım 3: Oluşan belgeyi doğrulayın

Faturaya bağlı e-belgeyi active_e_document ilişkisiyle okursunuz. e-SMM için ilişkinin tipi e_smms olur:

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

• e-SMM kaydını doğrudan okumak için GET /{company_id}/e_smms/{id}; faturayla birlikte almak için ?include=sales_invoice.
• e-SMM'si gönderilmiş faturaları listelemek için satış faturası liste ucunda filter[print_status]=e_smm_sent kullanılabilir.
• e-SMM'si olan faturalar için sales_invoice update webhook olayı gönderilmez; faturanın oluşturulmasına ait create olayı ise gelir. Webhook kurulumu için Paraşüt webhook kurulumu yazısına bakın.

Adım 4: e-SMM PDF'ini alın

PDF için kayıttaki pdf_url alanını değil, API ucunu kullanın:

curl -X GET "https://api.parasut.com/v4/{company_id}/e_smms/{e_smm_id}/pdf" \
  -H "Authorization: Bearer $PARASUT_ACCESS_TOKEN"

# Yanıt PDF baytı değil, JSON'dur:
# {"data": {"id": "...", "type": "e_document_pdfs",
#   "attributes": {"url": "https://...", "expires_at": "2026-11-03T12:00:00Z"}}}

url yalnızca expires_at zamanına kadar geçerlidir; kalıcı olarak saklamayın, süresi dolunca uca yeniden istek atın. Rehber, PDF hazır değilken bu tür uçların 204 No Content döndüğünü ve 200 alana kadar aralıklarla tekrar istenmesi gerektiğini söyler. Bağlantıyı doğrudan müşteriyle paylaşmak yerine PDF'i indirip kendi sisteminizden (e-posta, müşteri paneli) iletmeniz beklenir.

Node.js ile uçtan uca örnek

Aşağıdaki fonksiyon, oluşturulmuş bir satış faturasını e-SMM'ye çevirir ve PDF bağlantısını alır. Paraşüt'ün resmî TypeScript örnek uygulamasındaki desene (204 gelirse bekle ve tekrar sor) uygun yazıldı; token yenileme ve 429 yönetimini kendi HTTP katmanınıza bırakın.

const BASE = 'https://api.parasut.com/v4';
const sleep = (ms) => new Promise((r) => setTimeout(r, ms));

async function parasut(path, token, init = {}) {
  const res = await fetch(`${BASE}${path}`, {
    ...init,
    headers: {
      Authorization: `Bearer ${token}`,
      'Content-Type': 'application/vnd.api+json',
      ...(init.headers || {}),
    },
  });
  return res;
}

async function createESmmWithPdf(companyId, invoiceId, token, note) {
  // 1) e-SMM oluştur (eşzamanlı, 201 beklenir)
  const res = await parasut(`/${companyId}/e_smms`, token, {
    method: 'POST',
    body: JSON.stringify({
      data: {
        type: 'e_smms',
        attributes: { note },
        relationships: {
          sales_invoice: { data: { type: 'sales_invoices', id: String(invoiceId) } },
        },
      },
    }),
  });
  const body = await res.json().catch(() => ({}));
  if (res.status !== 201) {
    throw new Error(`e-SMM oluşturulamadı (HTTP ${res.status}): ${JSON.stringify(body.errors || body)}`);
  }
  const eSmmId = body.data.id;

  // 2) PDF bağlantısını al; hazır değilse 204 döner
  for (let i = 0; i < 10; i++) {
    const pdf = await parasut(`/${companyId}/e_smms/${eSmmId}/pdf`, token);
    if (pdf.status === 200) {
      const { data } = await pdf.json();
      return { eSmmId, url: data.attributes.url, expiresAt: data.attributes.expires_at };
    }
    if (pdf.status !== 204) throw new Error(`PDF alınamadı (HTTP ${pdf.status})`);
    await sleep(3000);
  }
  return { eSmmId, url: null }; // PDF daha sonra tekrar istenebilir
}

Staging ortamında test

Rehbere göre staging hesaplarında e-belge entegrasyonu varsayılan olarak "Dummy Integration" olarak ayarlıdır: belgeleri resmileştirebilirsiniz ama GİB'e gönderilmez, sonuçlar test amacıyla taklit edilir; belge doğrulaması ise gerçek ortamdaki gibi yapılır. Hata senaryolarını denemek için rehberdeki anahtar= değer; biçimindeki test direktifleri e-Fatura ve e-Arşiv'de fatura notuna yazılırken, e-SMM'de POST /e_smms isteğinin note alanına yazılır. 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.

Sık yapılan hatalar

• e-SMM'yi trackable job ile takip etmeye çalışmak: e-SMM 201 ile kaydı döner, iş kimliği yoktur.
• relationships.invoice yazmak: e-SMM'de ilişkinin adı sales_invoice'dır.
• Kayıttaki pdf_url alanını müşteriye göndermek: bu web uygulaması yoludur ve oturum ister; GET /e_smms/{id}/pdf kullanın.
• issue_date'i aktivasyon tarihinden önceye atmak.
• currency için TRY yazmak; API TRL bekler.
• e-SMM'li faturaların durumunu sales_invoice update webhook'u ile beklemek; bu olay e-SMM'li faturalar için gelmez.

Sık Sorulan Sorular

Paraşüt API ile e-SMM kesmek için ayrı bir uç var mı?

Evet: POST /{company_id}/e_smms. Ancak bu uç bağımsız bir belge yazmaz; var olan bir satış faturasını sales_invoice ilişkisiyle e-SMM olarak resmileştirir. Yanında GET /e_smms/{id} ve GET /e_smms/{id}/pdf uçları vardır.

e-SMM oluşturduktan sonra beklemem gerekiyor mu?

Belge açısından hayır; e-SMM eşzamanlı oluşur ve 201 ile döner. Yalnızca PDF hazır olmayabilir; PDF ucu 204 dönerse kısa aralıklarla tekrar isteyin.

Kimler e-SMM kullanmak zorunda?

Bu bir mevzuat sorusudur ve Paraşüt API belgesinde yer almaz. Yükümlülüğünüzü mali müşavirinizle ve GİB'in güncel düzenlemeleriyle netleştirin; API tarafında yalnızca firmanızın Paraşüt'te makbuz kullanıcısı olarak etkin olması gerekir.

Aynı faturadan hem e-Arşiv hem e-SMM oluşturabilir miyim?

Belge bu konuda açık bir kural vermez. Faturanın tek bir active_e_document ilişkisi vardır ve tipi e_archives, e_invoices ya da e_smms olur; bu nedenle her fatura için hangi e-belgeyi oluşturacağınıza önceden karar verin ve göndermeden önce bu ilişkiyi kontrol edin.

Marka adları sahiplerine aittir. Bu yazı bağımsız bir teknik rehberdir; adı geçen kuruluşlarla bayilik veya ortaklık ilişkisi bulunduğu anlamına gelmez.

İlgili içerikler: Paraşüt entegrasyonu genel rehberi · Paraşüt API ile fatura kesme · Paraşüt e-Fatura ve e-Arşiv gönderme · Paraşüt cari hesap oluşturma · Paraşüt webhook kurulumu · Paraşüt API hata kodları · e-Arşiv ve e-Fatura zorunluluğu