e-Arşiv Fatura

Örnekler

Request Örnekleri

Normal satış, internet satışı, ÖKC, tevkifat ve iptal/itiraz senaryoları için JSON ve ByXml endpointlerine ayrılmış kopyalanabilir request örnekleri.

Senaryo Kapsamı

Aşağıdaki fatura örnekleri AddOutgoingInvoice endpoint sözleşmesine göre hazırlanmıştır. Her örnek eksiksiz bir gövdedir; alan adları ve iç içe yapı API sözleşmesiyle aynıdır.

Alan tipi uyarısı: InvoicedQuantity alanı ham sayı değil { "UnitCode": "...", "Value": ... } biçiminde bir nesnedir. Aşağıdaki örneklerde birim ve miktar birlikte gösterilir.
Özel fatura tipleri: SARJ, SARJANLIK, YTBTEVKIFAT, YTBTEVKIFATIADE ve TEKNOLOJIDESTEK için zorunlu alanları Kullanım Senaryoları, alan karşılıklarını Request → UBL XML Mapping sayfasından uygulayın; bu tipler yalnız temel örnek değiştirilerek gönderilmemelidir.

Örnek 1 — Normal Satış

Ek alan gerektirmeyen temel e-Arşiv Fatura akışı; alıcı GİB e-Fatura mükellefi değildir.

Tek kalemli, KDV'li standart bir satış.

Endpoint: POST /api/VbtApi/AddOutgoingInvoice
Body: OutgoingInvoiceRequestModel (JSON)

{
  "ProfileId": "EARSIVFATURA",
  "InvoiceExternalId": "ERP-2026-000145",
  "IssueDate": "2026-03-15T14:30:00",
  "DocumentCurrencyCode": "TRY",
  "AccountingSupplierParty": {
    "Party": {
      "PartyIdentifications": [
        {
          "SchemeId": "VKN",
          "Value": "1234567890"
        }
      ],
      "PartyName": "Satıcı Ticaret A.Ş."
    }
  },
  "AccountingCustomerParty": {
    "Party": {
      "PartyIdentifications": [
        {
          "SchemeId": "TCKN",
          "Value": "12345678901"
        }
      ],
      "Person": { "FirstName": "Alıcı", "FamilyName": "Adı Soyadı" }
    }
  },
  "InvoiceLine": [
    {
      "Id": "1",
      "InvoicedQuantity": {
        "UnitCode": "C62",
        "Value": 2
      },
      "Price": 50,
      "LineExtensionAmount": 100,
      "Item": {
        "Name": "Kırtasiye Malzemesi"
      }
    }
  ],
  "TaxTotal": [
    {
      "TaxAmount": 18,
      "TaxSubtotal": [
        {
          "TaxableAmount": 100,
          "TaxAmount": 18,
          "Percent": 18,
          "TaxCategory": {
            "TaxScheme": {
              "Name": "KDV",
              "TaxTypeCode": "0015"
            }
          }
        }
      ]
    }
  ],
  "LegalMonetaryTotal": {
    "LineExtensionAmount": 100,
    "TaxExclusiveAmount": 100,
    "TaxInclusiveAmount": 118,
    "PayableAmount": 118
  }
}

Örnek 2 — İnternet Satışı

Ortak alanlara (taraflar, satırlar, toplamlar — Örnek 1'deki gibi) ek olarak InternetPayment ve zorunlu Note ibaresi eklenir.

Mal ve hizmetlerin sipariş/satın alma sürecinin tamamı internet üzerinden yapıldığı satış.

Endpoint: POST /api/VbtApi/AddOutgoingInvoice
Body: OutgoingInvoiceRequestModel (JSON)

{
  "ProfileId": "EARSIVFATURA",
  "InvoiceExternalId": "ERP-2026-000146",
  "IssueDate": "2026-03-15T10:00:00",
  "DocumentCurrencyCode": "TRY",
  "AccountingSupplierParty": {
    "Party": {
      "PartyIdentifications": [
        {
          "SchemeId": "VKN",
          "Value": "1234567890"
        }
      ],
      "PartyName": "Satıcı Ticaret A.Ş."
    }
  },
  "AccountingCustomerParty": {
    "Party": {
      "PartyIdentifications": [
        {
          "SchemeId": "TCKN",
          "Value": "12345678901"
        }
      ],
      "Person": { "FirstName": "Alıcı", "FamilyName": "Adı Soyadı" }
    }
  },
  "InvoiceLine": [
    {
      "Id": "1",
      "InvoicedQuantity": {
        "UnitCode": "C62",
        "Value": 2
      },
      "Price": 50,
      "LineExtensionAmount": 100,
      "Item": {
        "Name": "Kırtasiye Malzemesi"
      }
    }
  ],
  "TaxTotal": [
    {
      "TaxAmount": 18,
      "TaxSubtotal": [
        {
          "TaxableAmount": 100,
          "TaxAmount": 18,
          "Percent": 18,
          "TaxCategory": {
            "TaxScheme": {
              "Name": "KDV",
              "TaxTypeCode": "0015"
            }
          }
        }
      ]
    }
  ],
  "LegalMonetaryTotal": {
    "LineExtensionAmount": 100,
    "TaxExclusiveAmount": 100,
    "TaxInclusiveAmount": 118,
    "PayableAmount": 118
  },
  "Note": [
    "Bu satış internet üzerinden yapılmıştır."
  ],
  "InternetPayment": {
    "WebAdresi": "https://magaza.example.com",
    "OdemeSekli": "KREDIKARTI",
    "OdemeTarihi": "2026-03-14T00:00:00",
    "GonderiTasiyanVknTckn": "1234567890",
    "GonderiTasiyanUnvan": "Kargo Firması A.Ş.",
    "GonderimTarihi": "2026-03-16T00:00:00",
    "Gonderilen": "Alıcı Adı Soyadı"
  }
}
Koşullu alanlar: OdemeSekli=ODEMEARACISI ise OdemeAracisiAdi, OdemeSekli=DIGER ise OdemeSekliAciklama ayrıca zorunlu hâle gelir (INV0036/INV0037). OdemeSekli değeri GİB kod listesinde tanımlı olmalıdır (INV0168).

Örnek 3 — ÖKC ile Birlikte

ÖKC doğrulaması DocumentTypeCode=OKCBF ile tetiklenir; bu durumda aşağıdaki tüm alt alanlar zorunludur (bkz. Teknik Referans — Validasyon Referansları).

Yeni nesil ÖKC'den düzenlenen fiş bilgisinin fatura ile birlikte gönderilmesi.

Endpoint: POST /api/VbtApi/AddOutgoingInvoice
Body: OutgoingInvoiceRequestModel (JSON)

{
  "ProfileId": "EARSIVFATURA",
  "InvoiceExternalId": "ERP-2026-000147",
  "IssueDate": "2026-03-15T00:00:00",
  "DocumentCurrencyCode": "TRY",
  "AccountingSupplierParty": {
    "Party": {
      "PartyIdentifications": [
        {
          "SchemeId": "VKN",
          "Value": "1234567890"
        }
      ],
      "PartyName": "Satıcı Ticaret A.Ş."
    }
  },
  "AccountingCustomerParty": {
    "Party": {
      "PartyIdentifications": [
        {
          "SchemeId": "TCKN",
          "Value": "12345678901"
        }
      ],
      "Person": { "FirstName": "Alıcı", "FamilyName": "Adı Soyadı" }
    }
  },
  "InvoiceLine": [
    {
      "Id": "1",
      "InvoicedQuantity": {
        "UnitCode": "C62",
        "Value": 2
      },
      "Price": 50,
      "LineExtensionAmount": 100,
      "Item": {
        "Name": "Kırtasiye Malzemesi"
      }
    }
  ],
  "TaxTotal": [
    {
      "TaxAmount": 18,
      "TaxSubtotal": [
        {
          "TaxableAmount": 100,
          "TaxAmount": 18,
          "Percent": 18,
          "TaxCategory": {
            "TaxScheme": {
              "Name": "KDV",
              "TaxTypeCode": "0015"
            }
          }
        }
      ]
    }
  ],
  "LegalMonetaryTotal": {
    "LineExtensionAmount": 100,
    "TaxExclusiveAmount": 100,
    "TaxInclusiveAmount": 118,
    "PayableAmount": 118
  },
  "BillingReference": [
    {
      "AdditionalDocumentReference": {
        "Id": "OKC0000123",
        "DocumentTypeCode": "OKCBF",
        "DocumentType": "OKCBilgiFisi",
        "IssueDate": "2026-03-15T00:00:00",
        "DocumentDescription": [
          "Yeni nesil ÖKC fiş bilgisi"
        ],
        "Attachment": {
          "ExternalReference": "https://okc.example.com/fis/OKC0000123"
        },
        "IssuerParty": {
          "EndpointId": "1234567890"
        },
        "ValidityPeriod": {
          "StartDate": "2026-03-15T00:00:00"
        }
      }
    }
  ]
}
Sık hata: DocumentType alanı literal olarak OKCBilgiFisi olmalıdır; ayrıca ValidityPeriod.StartDate, IssueDate ile aynı takvim gününde olmalıdır — aksi hâlde "SCHEME" koduyla reddedilir (bkz. Teknik Referans — Katman A).

Örnek 4 — Tevkifatlı

WithholdingTaxTotal yalnızca InvoiceTypeCode TEVKIFAT/YTBTEVKIFAT/IADE/YTBIADE/SGK/SARJ/SARJANLIK olduğunda kabul edilir.

GV stopajı tevkifatı içeren bir fatura.

Endpoint: POST /api/VbtApi/AddOutgoingInvoice
Body: OutgoingInvoiceRequestModel (JSON)

{
  "ProfileId": "EARSIVFATURA",
  "InvoiceExternalId": "ERP-2026-000148",
  "IssueDate": "2026-03-15T00:00:00",
  "DocumentCurrencyCode": "TRY",
  "AccountingSupplierParty": {
    "Party": {
      "PartyIdentifications": [
        {
          "SchemeId": "VKN",
          "Value": "1234567890"
        }
      ],
      "PartyName": "Satıcı Ticaret A.Ş."
    }
  },
  "AccountingCustomerParty": {
    "Party": {
      "PartyIdentifications": [
        {
          "SchemeId": "TCKN",
          "Value": "12345678901"
        }
      ],
      "Person": { "FirstName": "Alıcı", "FamilyName": "Adı Soyadı" }
    }
  },
  "InvoiceLine": [
    {
      "Id": "1",
      "InvoicedQuantity": {
        "UnitCode": "C62",
        "Value": 2
      },
      "Price": 50,
      "LineExtensionAmount": 100,
      "Item": {
        "Name": "Kırtasiye Malzemesi"
      }
    }
  ],
  "TaxTotal": [
    {
      "TaxAmount": 18,
      "TaxSubtotal": [
        {
          "TaxableAmount": 100,
          "TaxAmount": 18,
          "Percent": 18,
          "TaxCategory": {
            "TaxScheme": {
              "Name": "KDV",
              "TaxTypeCode": "0015"
            }
          }
        }
      ]
    }
  ],
  "LegalMonetaryTotal": {
    "LineExtensionAmount": 100,
    "TaxExclusiveAmount": 100,
    "TaxInclusiveAmount": 118,
    "PayableAmount": 118
  },
  "InvoiceTypeCode": "TEVKIFAT",
  "WithholdingTaxTotal": [
    {
      "TaxAmount": 20,
      "TaxSubtotal": [
        {
          "TaxableAmount": 200,
          "TaxAmount": 20,
          "Percent": 10,
          "TaxCategory": {
            "TaxScheme": {
              "Name": "GV STOPAJI",
              "TaxTypeCode": "0003"
            }
          }
        }
      ]
    }
  ]
}
Sık hata: TaxSubtotal.TaxCategory.TaxScheme.TaxTypeCode ve Percent ikilisi platformun (parametre tablosundan gelen) tanımlı tevkifat kod/oran eşleşmelerinden biri olmalıdır; eşleşmeyen bir kombinasyon "Uyumsuz vergi tipi yüzdesi" mesajıyla reddedilir.

Örnek 5 — Mükerrer/İade Referanslı

InvoiceTypeCode=IADE olduğunda referans verilen orijinal faturanın numarası tam 16 karakter olmalıdır.

Önceki bir faturaya iade referansı veren belge.

Endpoint: POST /api/VbtApi/AddOutgoingReturnedInvoice
Body: OutgoingInvoiceRequestModel (JSON)

{
  "ProfileId": "EARSIVFATURA",
  "InvoiceExternalId": "ERP-2026-000149",
  "IssueDate": "2026-03-20T00:00:00",
  "DocumentCurrencyCode": "TRY",
  "AccountingSupplierParty": {
    "Party": {
      "PartyIdentifications": [
        {
          "SchemeId": "VKN",
          "Value": "1234567890"
        }
      ],
      "PartyName": "Satıcı Ticaret A.Ş."
    }
  },
  "AccountingCustomerParty": {
    "Party": {
      "PartyIdentifications": [
        {
          "SchemeId": "TCKN",
          "Value": "12345678901"
        }
      ],
      "Person": { "FirstName": "Alıcı", "FamilyName": "Adı Soyadı" }
    }
  },
  "InvoiceLine": [
    {
      "Id": "1",
      "InvoicedQuantity": {
        "UnitCode": "C62",
        "Value": 2
      },
      "Price": 50,
      "LineExtensionAmount": 100,
      "Item": {
        "Name": "Kırtasiye Malzemesi"
      }
    }
  ],
  "TaxTotal": [
    {
      "TaxAmount": 18,
      "TaxSubtotal": [
        {
          "TaxableAmount": 100,
          "TaxAmount": 18,
          "Percent": 18,
          "TaxCategory": {
            "TaxScheme": {
              "Name": "KDV",
              "TaxTypeCode": "0015"
            }
          }
        }
      ]
    }
  ],
  "LegalMonetaryTotal": {
    "LineExtensionAmount": 100,
    "TaxExclusiveAmount": 100,
    "TaxInclusiveAmount": 118,
    "PayableAmount": 118
  },
  "InvoiceTypeCode": "IADE",
  "BillingReference": [
    {
      "InvoiceDocumentReference": {
        "Id": "FGH2026000000001",
        "DocumentTypeCode": "IADE",
        "IssueDate": "2026-03-10T00:00:00"
      }
    }
  ]
}
Sık hata: Id alanı tam olarak 16 karakter olmalıdır (örn. FGH2026000000001); aksi hâlde "16 haneli olmalıdır" mesajıyla reddedilir. Aynı istekte birden fazla satır aynı Id'yi referans veriyorsa "mükerrer" hatası döner.

Özel Örnek — SARJ

Hizmet dönemi, alıcı plakası ve birden fazla ESU rapor kimliği taşıyan tam e-Arşiv Fatura gövdesi.

Endpoint: POST /api/VbtApi/AddOutgoingInvoice
Body: OutgoingInvoiceRequestModel (JSON)

{
  "ProfileId": "EARSIVFATURA",
  "InvoiceTypeCode": "SARJ",
  "InvoiceExternalId": "ERP-EARSIV-SARJ-2026-0001",
  "IssueDate": "2026-09-14T09:00:00+03:00",
  "DocumentCurrencyCode": "TRY",
  "LineCountNumeric": 1,
  "InvoicePeriod": {
    "StartDate": "2026-09-14T10:00:00+03:00",
    "EndDate": "2026-09-14T11:00:00+03:00"
  },
  "AdditionalDocumentReference": [
    {
      "SchemeId": "ESURaporID",
      "Id": "11111111-2222-3333-4444-555555555555",
      "IssueDate": "2026-09-14T00:00:00+03:00"
    },
    {
      "SchemeId": "ESURaporID",
      "Id": "66666666-7777-8888-9999-000000000000",
      "IssueDate": "2026-09-14T00:00:00+03:00"
    }
  ],
  "AccountingSupplierParty": {
    "Party": {
      "PartyIdentifications": [
        { "SchemeId": "VKN", "Value": "1234567890" }
      ],
      "PartyName": "Şarj Hizmetleri A.Ş."
    }
  },
  "AccountingCustomerParty": {
    "Party": {
      "PartyIdentifications": [
        { "SchemeId": "VKN", "Value": "9876543210" },
        { "SchemeId": "PLAKA", "Value": "34ABC123" }
      ],
      "PartyName": "Kurumsal Alıcı A.Ş."
    }
  },
  "InvoiceLine": [
    {
      "Id": "1",
      "InvoicedQuantity": { "UnitCode": "C62", "Value": 10 },
      "Price": 100,
      "LineExtensionAmount": 1000,
      "Item": { "Name": "Elektrikli Araç Şarj Hizmeti" },
      "TaxTotal": {
        "TaxAmount": 200,
        "TaxSubtotal": [
          {
            "TaxableAmount": 1000,
            "TaxAmount": 200,
            "Percent": 20,
            "TaxCategory": {
              "TaxScheme": { "Name": "KDV", "TaxTypeCode": "0015" }
            }
          }
        ]
      }
    }
  ],
  "TaxTotal": [
    {
      "TaxAmount": 200,
      "TaxSubtotal": [
        {
          "TaxableAmount": 1000,
          "TaxAmount": 200,
          "Percent": 20,
          "TaxCategory": {
            "TaxScheme": { "Name": "KDV", "TaxTypeCode": "0015" }
          }
        }
      ]
    }
  ],
  "LegalMonetaryTotal": {
    "LineExtensionAmount": 1000,
    "TaxExclusiveAmount": 1000,
    "TaxInclusiveAmount": 1200,
    "PayableAmount": 1200
  }
}
Çoklu ESU raporu: Faturayla ilişkili her rapor AdditionalDocumentReference[] içinde ayrı bir SchemeId=ESURaporID kaydı olarak gönderilir. Her kayıtta GUID biçiminde Id ve dolu IssueDate bulunur; platform geçerli kayıtların tamamını request sırasıyla e-Arşiv raporuna aktarır.

Örnek 6 — İptal

CancelOutgoingEArchiveInvoice endpoint gövdesi.

Mükerrer belge nedeniyle iptal.

Endpoint: POST /api/VbtApi/CancelOutgoingEArchiveInvoice
Body: EArchiveCancelRequestModel (JSON)

{
  "Ettn": "7DC52246-5750-496E-8BF2-BD27BC0764DC",
  "InvoiceNumber": "FGH2026000000001",
  "EArchiveStatus": 2,
  "EArchiveCancelDescription": "Mükerrer belge"
}

Örnek 7 — İtiraz Bildirimi

ObjectOutgoingEArchiveInvoice endpoint gövdesi — alıcının TTK md. 18/3 kapsamında zaten yaptığı itirazın kayda geçirilmesi.

KEP yoluyla yapılan itirazın bildirimi.

Endpoint: POST /api/VbtApi/ObjectOutgoingEArchiveInvoice
Body: DocumentObjectionRequestModel (JSON)

{
  "UUId": "7DC52246-5750-496E-8BF2-BD27BC0764DC",
  "ObjectingType": "KEP",
  "ObjectingDocumentNumber": "itirazBelgeNo0",
  "ObjectingDocumentDate": "2026-03-22",
  "ObjectingDescription": "Mal iade edildi"
}
Not: Kimlik, numara ve tarih değerleri temsilidir. Alan sözleşmesi için Entegratör API Endpoint Referansı kullanılmalıdır.