E-gider pusulası

E-gider, firmanız için yönetim ekranından açılır. Yalnız aktivasyondan sonra oluşturulan pusulalar elektronik olur. Mevcut kağıt belgeler ve eski taslaklar türünü korur. Yeni elektronik kaydı POST /v1/expenses ile isDraft: true göndererek oluşturun. Kayıt oluşturmadan hesaplama için Gider pusulası işlemleri sayfasına bakın. Kimlik doğrulama ve cevap zarfı Genel Bakış sayfasındadır. Gönderim sırası prepare → PDF önizlemesi → sms → confirm şeklindedir. Taslak hazırlandığında içerik ve telefon kilitlenir. İlk aşama yalnız vergisiz alım pusulasını, TRY ve döviz kuru 1 ile destekler. Has kuru kalem hesabında kullanılır; belgenin döviz kuru değildir.

Gönderimin sonucu belirsizse yeni belge oluşturmayın ve onayı tekrar göndermeyin. Aynı yerel kayıt için status çağırın. review_required durumu sonuç netleşene kadar korunur. Gönderilen e-gider silinemez; iptal ve GİB rapor gönderimi sağlayıcı portalından yürütülür.

`POST /v1/expenses/{id}/e-document/prepare` — taslağı hazırlayın

Yerel elektronik taslağı hazırlayın. Gerçek satıcı TCKN/VKN’si, adı, adresi, cep telefonu ve kalemleri doğrulanır. Genel müşteri veya rastgele kimlik bilgisiyle elektronik gönderim yapılmaz.

curl -X POST 'https://api.sarraf.pro/v1/expenses/6ab2f0c21ae2463211cf4321/e-document/prepare' \
  -u 'apiUserId:secretKey' -H 'Content-Type: application/json' \
  -d '{"data":{}}'

Alan	Tür	Kural
`id`	string, path	Yerel pusula kimliği. Kayıt `electronic` olmalıdır
`data`	object	Boş nesne. İçerik kayıtlı pusuladan alınır

Cevap — `200`

{
  "success": true,
  "data": {
    "id": "6ab2f0c21ae2463211cf4321",
    "documentMode": "electronic",
    "isFinalized": false,
    "eDocument": {
      "environment": "test",
      "uuid": "93f65d9f-b32a-434b-b8c7-16ba9151f307",
      "number": null,
      "state": "prepared",
      "phone": "905321234567",
      "frozenAt": "2026-10-09T10:00:00.000Z",
      "preparedAt": "2026-10-09T10:00:01.000Z",
      "smsSentAt": null,
      "smsRetryAt": null,
      "acceptedAt": null,
      "finalizedAt": null,
      "lastCheckedAt": null,
      "providerStatus": null,
      "statusDetail": null,
      "reportStatus": null,
      "cancelled": null,
      "errorCode": null,
      "errorMessage": null
    }
  },
  "meta": {"requestId":"c6c85e42-dd06-4cb3-885b-c0ca551ee866","timestamp":"2026-10-09T10:00:01.000Z"}
}

HTTP	`error.code`	Açıklama
409	`E_DOCUMENT_PAPER`	Kağıt belge bu akışla gönderilemez
409	`E_DOCUMENT_BUSY` / `E_DOCUMENT_REVIEW_REQUIRED`	İşlem sürüyor veya önce durum kontrolü gerekiyor
422	`E_DOCUMENT_DATA_INCOMPLETE`	Satıcı veya kalem bilgilerini tamamlayın
422	`E_DOCUMENT_CONFIG_MISSING` / `E_DOCUMENT_COMPANY_MISMATCH`	Firma bağlantısı doğrulanmalıdır
502	`E_DOCUMENT_RESULT_UNKNOWN` / `E_DOCUMENT_RESPONSE_INVALID`	Sonuç belirsiz; aynı kaydı sorgulayın

Yerel serial ve number, resmi e-gider numarası değildir. Resmi numara gönderim kabul edildikten sonra eDocument.number alanına yazılır.

`POST /v1/expenses/{id}/e-document/sms` — SMS gönderin

Hazırlanan belgenin sabit telefonuna doğrulama SMS’i gönderin. UUID kayıtlı pusuladan alınır; SMS cevabı yeni UUID oluşturmaz.

curl -X POST 'https://api.sarraf.pro/v1/expenses/6ab2f0c21ae2463211cf4321/e-document/sms' \
  -u 'apiUserId:secretKey' -H 'Content-Type: application/json' \
  -d '{"data":{}}'

Alan	Tür	Kural
`id`	string, path	Hazırlanmış elektronik pusula
`data`	object	Boş nesne. Telefon değişikliği kabul edilmez

Cevap — `200`

prepare ile aynı zarf döner. eDocument.state değeri verification_pending olur. smsSentAt gönderim zamanını, smsRetryAt yeniden SMS gönderebileceğiniz zamanı gösterir.

{
  "success": true,
  "data": {
    "id": "6ab2f0c21ae2463211cf4321",
    "documentMode": "electronic",
    "isFinalized": false,
    "eDocument": {
      "environment": "test",
      "uuid": "93f65d9f-b32a-434b-b8c7-16ba9151f307",
      "state": "verification_pending",
      "phone": "905321234567",
      "smsSentAt": "2026-10-09T10:01:00.000Z",
      "smsRetryAt": "2026-10-09T10:04:00.000Z"
    }
  },
  "meta": {"requestId":"c6c85e42-dd06-4cb3-885b-c0ca551ee866","timestamp":"2026-10-09T10:01:00.000Z"}
}

HTTP	`error.code`	Açıklama
409	`E_DOCUMENT_NOT_PREPARED`	Önce taslağı hazırlayın
409	`E_DOCUMENT_BUSY` / `E_DOCUMENT_REVIEW_REQUIRED`	İşlem sürüyor veya kontrol gerekiyor
429	`E_DOCUMENT_SMS_COOLDOWN`	`smsRetryAt` sonrasını bekleyin
422	`E_DOCUMENT_REJECTED`	SMS bekleme süresi veya firma SMS kotasını kontrol edin
502	`E_DOCUMENT_RESULT_UNKNOWN`	Sonuç belirsiz; aynı kaydı sorgulayın

`POST /v1/expenses/{id}/e-document/confirm` — kodla onaylayın

Satıcının telefonuna gelen kodla belgeyi gönderin. Gönderim kabulü resmi UUID ve numara ile kaydedildikten sonra yerel kesinleştirme, stok ve banka bağlantıları tamamlanır.

curl -X POST 'https://api.sarraf.pro/v1/expenses/6ab2f0c21ae2463211cf4321/e-document/confirm' \
  -u 'apiUserId:secretKey' -H 'Content-Type: application/json' \
  -d '{"data":{"code":"123456"}}'

Alan	Tür	Kural
`id`	string, path	SMS gönderilmiş elektronik pusula
`data.code`	string	4–8 rakam. Kod saklanmaz ve API loguna yazılmaz

Cevap — `200`

{
  "success": true,
  "data": {
    "id": "6ab2f0c21ae2463211cf4321",
    "documentMode": "electronic",
    "isFinalized": true,
    "eDocument": {
      "environment": "test",
      "uuid": "93f65d9f-b32a-434b-b8c7-16ba9151f307",
      "number": "EGP2026000000001",
      "state": "sent",
      "acceptedAt": "2026-10-09T10:02:00.000Z",
      "finalizedAt": "2026-10-09T10:02:01.000Z",
      "providerStatus": "unknown"
    }
  },
  "meta": {"requestId":"c6c85e42-dd06-4cb3-885b-c0ca551ee866","timestamp":"2026-10-09T10:02:01.000Z"}
}

HTTP	`error.code`	Açıklama
400	`VALIDATION_FAILED`	Kod biçimi geçersiz
409	`VERIFICATION_REQUIRED`	Önce SMS gönderin
409	`E_DOCUMENT_BUSY` / `E_DOCUMENT_REVIEW_REQUIRED`	İşlem sürüyor veya sonuç belirsiz
409	`BANK_ACCOUNT_INACTIVE`	Kaynak banka hesabı pasif
422	`E_DOCUMENT_REJECTED`	Kod yanlış, süresi dolmuş veya iş kuralı reddedildi
502	`E_DOCUMENT_RESULT_UNKNOWN` / `E_DOCUMENT_RESPONSE_INVALID`	Onayı tekrar göndermeden durum sorgulayın

Kabul sonrası yerel kayıt hatasında belge review_required olabilir. status, yeni gönderim yapmadan kesinleştirmeyi tamamlar. Aynı banka hareketi için allowDuplicate: true ile ikinci elektronik taslak açılamaz.

`GET /v1/expenses/{id}/e-document/status` — durumu yenileyin

Aynı UUID için gönderim kabulünü ve sağlayıcı durumunu sorgulayın. Kabul edilmiş kaydın yarım kalan yerel işlemleri mükerrer stok oluşmadan tamamlanır.

curl 'https://api.sarraf.pro/v1/expenses/6ab2f0c21ae2463211cf4321/e-document/status' \
  -u 'apiUserId:secretKey'

Alan	Tür	Kural
`id`	string, path	Elektronik pusula kimliği

Cevap — `200`

{
  "success": true,
  "data": {
    "id": "6ab2f0c21ae2463211cf4321",
    "documentMode": "electronic",
    "isFinalized": true,
    "eDocument": {
      "environment": "test",
      "uuid": "93f65d9f-b32a-434b-b8c7-16ba9151f307",
      "number": "EGP2026000000001",
      "state": "sent",
      "acceptedAt": "2026-10-09T10:02:00.000Z",
      "finalizedAt": "2026-10-09T10:02:01.000Z",
      "providerStatus": "succeed",
      "reportStatus": "Reported",
      "cancelled": false,
      "lastCheckedAt": "2026-10-09T10:10:00.000Z"
    }
  },
  "meta": {"requestId":"c6c85e42-dd06-4cb3-885b-c0ca551ee866","timestamp":"2026-10-09T10:10:00.000Z"}
}

HTTP	`error.code`	Açıklama
404	`RESOURCE_NOT_FOUND`	Firma kapsamındaki yerel pusula bulunamadı
409	`E_DOCUMENT_BUSY`	Başka işlem sürüyor; daha sonra sorgulayın
409	`E_DOCUMENT_FINALIZATION_REQUIRED`	Kabul edildi; yerel kesinleştirme tekrar kontrol edilmelidir
502	`E_DOCUMENT_RESULT_UNKNOWN`	Sağlayıcıya erişilemedi; sonuç bilinmiyor

Alan	Anlam
`state`	Yerel işlem: `draft`, `preparing`, `prepared`, `sms_sending`, `verification_pending`, `dispatching`, `provider_accepted`, `sent`, `failed`, `review_required`, `deleting`
`acceptedAt`	Gönderimin kabul edildiği zaman
`finalizedAt`	Stok ve banka bağlantılarının yerelde tamamlandığı zaman
`providerStatus`	`unknown`, `waiting`, `succeed`, `error`. Yerel kesinleştirmeden bağımsızdır
`reportStatus`	`NotReported` veya `Reported`; GİB raporu
`cancelled`	Sağlayıcı portalındaki iptal bilgisi

Gönderim timeout’u sonrası belgenin sağlayıcıda henüz bulunmaması, reddedildiğini kanıtlamaz. Böyle bir kayıt review_required kalır; otomatik yeniden gönderim yapılmaz.

`GET /v1/expenses/{id}/e-document/file` — PDF veya XML alın

Hazırlanan taslağın veya gönderilen belgenin dosyasını firma yetkisiyle alın. Test/canlı ortamı kayıt üzerinde sabittir; firma ayarını kapatmak eski elektronik belgenin dosya erişimini değiştirmez. İlgili ortamın bağlantısı korunmalıdır.

curl 'https://api.sarraf.pro/v1/expenses/6ab2f0c21ae2463211cf4321/e-document/file?format=pdf' \
  -u 'apiUserId:secretKey' -o gider-pusulasi.pdf

Alan	Tür	Kural
`id`	string, path	Elektronik pusula kimliği
`format`	string, query	Zorunlu: `pdf` veya `xml`

Cevap — `200`

JSON zarfı kullanılmaz. PDF için application/pdf, XML için application/xml içerik döner. Cevap Cache-Control: private, no-store taşır.

HTTP	`error.code`	Açıklama
400	`VALIDATION_FAILED`	Dosya biçimi geçersiz
404	`RESOURCE_NOT_FOUND`	Firma kapsamındaki kayıt bulunamadı
409	`E_DOCUMENT_NOT_PREPARED`	Önce taslağı hazırlayın
502	`E_DOCUMENT_FILE_INVALID`	Geçerli dosya alınamadı

Başlangıç

API'ye Giriş

Müşteriler

Banka

Faturalar

Giderler

KMTS

`POST /v1/expenses/{id}/e-document/prepare` — taslağı hazırlayın

Cevap — `200`

`POST /v1/expenses/{id}/e-document/sms` — SMS gönderin

Cevap — `200`

`POST /v1/expenses/{id}/e-document/confirm` — kodla onaylayın

Cevap — `200`

`GET /v1/expenses/{id}/e-document/status` — durumu yenileyin

Cevap — `200`

`GET /v1/expenses/{id}/e-document/file` — PDF veya XML alın

Cevap — `200`

​POST /v1/expenses/{id}/e-document/prepare — taslağı hazırlayın

​Cevap — 200

​POST /v1/expenses/{id}/e-document/sms — SMS gönderin

​Cevap — 200

​POST /v1/expenses/{id}/e-document/confirm — kodla onaylayın

​Cevap — 200

​GET /v1/expenses/{id}/e-document/status — durumu yenileyin

​Cevap — 200

​GET /v1/expenses/{id}/e-document/file — PDF veya XML alın

​Cevap — 200

`POST /v1/expenses/{id}/e-document/prepare` — taslağı hazırlayın

Cevap — `200`

`POST /v1/expenses/{id}/e-document/sms` — SMS gönderin

Cevap — `200`

`POST /v1/expenses/{id}/e-document/confirm` — kodla onaylayın

Cevap — `200`

`GET /v1/expenses/{id}/e-document/status` — durumu yenileyin

Cevap — `200`

`GET /v1/expenses/{id}/e-document/file` — PDF veya XML alın

Cevap — `200`