> ## Documentation Index > Fetch the complete documentation index at: https://docs.sarraf.pro/llms.txt > Use this file to discover all available pages before exploring further. # Fatura oluşturma ve gönderimi > Fatura oluşturur ve e-belge entegratörüne gönderir. İki kaynak desteklenir: - `source: "bankTransaction"` — faturalandırılmamış bir gelen banka hareketinden. Hareket faturalandırılmış olarak işaretlenir ve panel yayın akışıyla aynı sonucu üretir. - `source: "manual"` — banka hareketine bağlı olmayan serbest fatura. Tutar, şablon ve ödeme bilgisi istekte verilir. Başarılı gönderimde **201** döner ve `invoiceId` ile fatura `GET /v1/invoices/{id}` üzerinden okunabilir. `isDraft: true` gönderildiğinde entegratörde yalnız taslak oluşturulur; resmî fatura kesilmez, `invoiceId` ve `totals` boş döner ve yanıt **200**'dür. Mükerrer gönderim koruması kaynak bazlıdır: banka hareketi zaten faturalandırılmışsa 409 döner; serbest faturada aynı gün + aynı kimlik + aynı tutar için kesilmiş fatura varsa 409 döner ve `allowDuplicate: true` ile bilinçli olarak aşılabilir. ## OpenAPI ````yaml /api-reference/openapi.json post /v1/invoices openapi: 3.0.3 info: title: Sarraf API v1 version: 1.0.0 description: >- Sarraf sürümlü dış API yüzeyi. Bu sürüm salt okunurdur; e-ticaret siteleri ve muhasebe programları için mevcut kayıtların okunmasını sağlar. Kimlik doğrulama mevcut dış API ile aynıdır: HTTP Basic, base64(apiUserId:secretKey). Tüm yanıtlar sabit zarf formatındadır: başarılı yanıtta success/data/meta, hatalı yanıtta success/error{code,message,details}/traceId. Her yanıtta x-request-id başlığı döner ve traceId ile aynıdır. servers: - url: https://api.sarraf.pro description: Canlı ortam security: - BasicAuth: [] tags: - name: Customers description: >- Cari hesaplar ve uyum — listeleme, detay, müşteri tanı oluşturma, kayıt/sicil sorgusu, tanı formları, kimlik belgeleri, yaptırım sorguları ve sicil geçmişi x-group: Müşteriler - name: Bank accounts description: Banka hesapları, bakiyeler ve sorgu tetikleme x-group: Banka - name: Bank transactions description: Gelen/giden banka hareketleri — detayda gömülü MASAK özeti x-group: Banka - name: Invoices description: Fatura oluşturma ve gönderimi, kesilen faturalar ve kalem şablonları x-group: Faturalar - name: Expenses description: Gider pusulası kayıtları x-group: Giderler paths: /v1/invoices: post: tags: - Invoices summary: Fatura oluşturma ve gönderimi description: >- Fatura oluşturur ve e-belge entegratörüne gönderir. İki kaynak desteklenir: - `source: "bankTransaction"` — faturalandırılmamış bir gelen banka hareketinden. Hareket faturalandırılmış olarak işaretlenir ve panel yayın akışıyla aynı sonucu üretir. - `source: "manual"` — banka hareketine bağlı olmayan serbest fatura. Tutar, şablon ve ödeme bilgisi istekte verilir. Başarılı gönderimde **201** döner ve `invoiceId` ile fatura `GET /v1/invoices/{id}` üzerinden okunabilir. `isDraft: true` gönderildiğinde entegratörde yalnız taslak oluşturulur; resmî fatura kesilmez, `invoiceId` ve `totals` boş döner ve yanıt **200**'dür. Mükerrer gönderim koruması kaynak bazlıdır: banka hareketi zaten faturalandırılmışsa 409 döner; serbest faturada aynı gün + aynı kimlik + aynı tutar için kesilmiş fatura varsa 409 döner ve `allowDuplicate: true` ile bilinçli olarak aşılabilir. operationId: createInvoice requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/InvoiceCreateRequest' responses: '200': description: 'Taslak oluşturuldu (isDraft: true). Resmî fatura kesilmedi.' headers: x-request-id: description: İstek kimliği; yanıt gövdesindeki meta.requestId ile aynıdır. schema: type: string format: uuid content: application/json: schema: $ref: '#/components/schemas/InvoiceCreateResponse' '201': description: Fatura oluşturuldu ve gönderildi. headers: x-request-id: description: İstek kimliği; yanıt gövdesindeki meta.requestId ile aynıdır. schema: type: string format: uuid content: application/json: schema: $ref: '#/components/schemas/InvoiceCreateResponse' '400': $ref: '#/components/responses/ValidationFailed' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' '409': description: >- Mükerrer fatura. Banka hareketi faturalandırılmış veya aynı gün/kimlik/tutar ile fatura kesilmiş (details[0] mevcut kaydı gösterir). content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '422': description: >- İş kuralı hatası (TCKN/VKN doğrulanamadı, kalemler hatalı, tutar çok düşük, hızlı fatura tanımları eksik vb.). content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': $ref: '#/components/responses/InternalError' '502': description: >- E-belge entegratörü hatası. `error.details` entegratörün döndürdüğü hata listesini taşır. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' components: schemas: InvoiceCreateRequest: type: object description: 'Yazma uçlarında gövde zarfı: data zorunludur.' properties: data: type: object properties: source: type: string enum: - bankTransaction - manual description: Fatura kaynağı. bankTransactionId: type: string description: >- Faturalandırılacak gelen banka hareketi (yalnız `source: bankTransaction`). amount: type: number description: >- Fatura tutarı (yalnız `source: manual`; banka kaynağında hareketin tutarı kullanılır). templateKey: type: string description: >- Kalem şablonu anahtarı. Verilmezse firmanın varsayılan şablonu kullanılır. exchanges: type: number description: Has/kur değeri. Verilmezse güncel fiyat listesinden alınır. idNo: type: string description: >- Müşteri TCKN/VKN. `source: manual` için zorunludur; banka kaynağında boş bırakılırsa hareketin kimlik bilgisi kullanılır. nameSurname: type: string description: Müşteri ad soyad / ünvan. transactionDate: type: string format: date-time description: 'Fatura tarihi (yalnız `source: manual`; varsayılan: şimdi).' paymentDate: type: string format: date-time description: >- Ödeme tarihi (yalnız `source: manual`; varsayılan: fatura tarihi). paymentType: type: string enum: - bank - pos - expense - other description: 'Ödeme şekli (`source: manual` için zorunlu).' bankName: type: string description: 'Ödemenin geçtiği banka (yalnız `source: manual`).' approvalCode: type: string description: 'POS onay kodu (yalnız `source: manual`, `paymentType: pos`).' iban: type: string description: 'Karşı IBAN (yalnız `source: manual`, `paymentType: bank`).' expenseNumber: type: string description: >- Mahsuplaşılan gider pusulası numarası (yalnız `source: manual`, `paymentType: expense`). paymentNote: type: string description: 'Ödeme notu (yalnız `source: manual`, `paymentType: other`).' description: type: string description: >- Fatura notu; satır satır fatura açıklamasına eklenir (yalnız `source: manual`). currentCode: type: string description: 'Muhasebe cari kodu (yalnız `source: manual`).' invoiceType: type: string enum: - OTOMATIK - ISTISNA - OZELMATRAH - SATIS description: >- Fatura türü (yalnız `source: manual`). Verilmezse veya `OTOMATIK` gönderilirse tür kalem şablonundan türetilir. customerInfo: $ref: '#/components/schemas/InvoiceCustomerInfoInput' isDraft: type: boolean default: false description: >- true ise entegratörde yalnız taslak oluşturulur; resmî fatura kesilmez. allowDuplicate: type: boolean default: false description: >- true ise serbest faturadaki mükerrer kaydı kontrolü atlanır (yalnız `source: manual`). required: - source required: - data InvoiceCreateResponse: type: object properties: success: type: boolean enum: - true data: $ref: '#/components/schemas/InvoiceCreateResult' meta: $ref: '#/components/schemas/MetaBase' required: - success - data - meta ErrorResponse: type: object properties: success: type: boolean enum: - false error: $ref: '#/components/schemas/ErrorBody' traceId: type: string format: uuid description: x-request-id başlığı ile aynı değer. required: - success - error - traceId InvoiceCustomerInfoInput: type: object description: >- Faturada kullanılacak müşteri bilgisi (yalnız `source: manual`). Verilen alanlar cari kaydından gelen bilgiyi geçersiz kılar. properties: nameSurname: type: string taxOffice: type: string address: type: string cities: type: string description: İlçe. states: type: string description: İl. phone: type: string email: type: string InvoiceCreateResult: type: object properties: source: type: string enum: - bankTransaction - manual sourceId: type: string nullable: true description: >- Banka kaynağında hareket kimliği; serbest faturada oluşan fatura kaydının kimliği. isDraft: type: boolean invoiceId: type: string nullable: true description: >- Resmî fatura kaydı; `GET /v1/invoices/{id}` ile okunur. Taslakta null döner. uuid: type: string nullable: true description: Entegratör belge kimliği. invoiceNumber: type: string nullable: true channel: type: string nullable: true enum: - earchive - einvoice - null description: Faturanın kesildiği kanal. integrator: type: string nullable: true template: $ref: '#/components/schemas/InvoiceTemplateSummary' totals: allOf: - $ref: '#/components/schemas/InvoiceTotals' nullable: true description: Oluşan fatura kaydının toplamları; taslakta null döner. MetaBase: type: object properties: requestId: type: string format: uuid timestamp: type: string format: date-time required: - requestId - timestamp ErrorBody: type: object properties: code: type: string enum: - VALIDATION_FAILED - AUTH_INVALID_CREDENTIALS - AUTH_FORBIDDEN - RESOURCE_NOT_FOUND - CONFLICT - UPSTREAM_ERROR - INTERNAL_ERROR message: type: string details: type: array items: $ref: '#/components/schemas/ErrorDetail' required: - code - message - details InvoiceTemplateSummary: type: object properties: key: type: string nullable: true title: type: string nullable: true lineName: type: string nullable: true material: type: string nullable: true InvoiceTotals: type: object properties: linesTotal: type: number description: Kalem net toplamı (KDV hariç). kdvTotal: type: number allowanceTotal: type: number description: İskonto toplamı. payableTotal: type: number description: Ödenecek toplam. ErrorDetail: type: object properties: field: type: string rule: type: string responses: ValidationFailed: description: Doğrulama hatası (geçersiz parametre). content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' Unauthorized: description: Kimlik doğrulama başarısız. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' NotFound: description: Kayıt bulunamadı. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' InternalError: description: Beklenmeyen sunucu hatası. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' securitySchemes: BasicAuth: type: http scheme: basic description: >- Kullanıcı adı apiUserId, parola secretKey. Authorization: Basic base64(apiUserId:secretKey) ````