# GİB e-Arşiv API

REST API for issuing Turkish e-Arşiv documents (e-Arşiv fatura, serbest meslek makbuzu, müstahsil makbuzu) through the GİB e-Arşiv portal (earsivportal.efatura.gov.tr). It wraps the [mlevent/fatura](https://github.com/mlevent/fatura) library.

This document is the full contract. It is written so an AI agent or a developer can use the API without reading the source code.

- Raw Markdown of this document: `GET /docs.md` (also `GET /llms.txt`, or `GET /docs` without `Accept: text/html`). Browsers get an HTML version at `/docs`.
- Base URL: `https://invoice.poditeknoloji.com/api/v1` (all paths below are relative to the host, e.g. `POST https://invoice.poditeknoloji.com/api/v1/invoices`)
- Docs: `https://invoice.poditeknoloji.com/docs.md`
- All requests and responses are JSON (`Content-Type: application/json`) unless stated otherwise.

---

## 1. Concepts you must know

1. **Draft first, then sign.** `POST /invoices` (and the receipt endpoints) creates a **draft** ("Onaylanmadı") on the GİB portal. A draft has no legal effect until it is **signed** ("Onaylandı") with an SMS code sent to the phone number registered on the GİB portal. Signing needs a human to read the SMS: see [Signing](#7-signing-sms-approval).
2. **ETTN = `uuid`.** Each document is identified by a UUID called ETTN. Every document endpoint takes this UUID.
3. **Document number** (`document_number`, e.g. `GIB2026000004550`) is assigned by GİB when the draft is created.
4. **Field names are Turkish** and match the GİB portal and the mlevent/fatura library exactly (`vknTckn`, `aliciUnvan`, `malHizmetListe`, `kdvOrani`...). The [field reference](#9-field-reference) lists them all.
5. **Dates** are accepted as `YYYY-MM-DD` or `DD/MM/YYYY`. Responses that come from GİB use GİB formats (`DD/MM/YYYY` or `DD-MM-YYYY`).
6. **Idempotency.** Send a unique `reference` (for example your order ID) when you create a document. If a document with the same `reference` already exists for the account, the API does not call GİB again. It returns the existing record with HTTP 200 and `"idempotent_replay": true`. You can also send the reference in the `Idempotency-Key` header. **Always send a reference when you retry after a timeout**, or you may issue the same invoice twice.
7. **Totals are calculated for you.** Send quantities, unit prices, VAT rates, discounts and extra taxes. The API calculates matrah, KDV, discounts, withholding and the payable amount. Use the `/preview` endpoints to check the totals without sending anything to GİB.
8. **GİB is the source of truth.** The API also keeps local records (`/records`) of documents it created. Their `status` changes only when the action goes through this API (create, delete, sign, cancel). To get the real status, query `/documents`.
9. **One API key = one GİB account.** The key decides which GİB taxpayer issues the documents. Each project gets its own key.

---

## 2. Authentication

Send the API key in one of these headers:

```
Authorization: Bearer gib_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
X-Api-Key: gib_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

A missing, wrong or revoked key returns `401` with error code `unauthenticated`.

**Call the API from your server, not from browser JavaScript.** A key used in the browser is visible to anyone who opens the page. Browser requests are also accepted only from allowed sites; others get `403 origin_not_allowed`. Only `GET /api/v1/meta` and `GET /docs` work without a key.

The service logs in to the GİB portal for you. It keeps one portal session per account and logs in again automatically when GİB ends it. GİB allows only one session per account at a time, so a person logging in to the portal in a browser can block the API until they log out (see `gib_session_conflict` below).

---

## 3. Response and error format

Success:

```json
{ "data": { ... } }
```

List endpoints also return a `meta` object. Error responses always look like this:

```json
{
  "error": {
    "code": "validation_failed",
    "message": "Human readable message",
    "details": { "...": "optional extra info" }
  }
}
```

| HTTP | `error.code` | Meaning / what to do |
|---|---|---|
| 401 | `unauthenticated` | API key missing, wrong or revoked. |
| 403 | `ip_not_allowed` | Your server's IP address is not on the allowed list. `details.ip` shows the address the API saw. Ask the API owner to add it. |
| 403 | `origin_not_allowed` | The request came from a browser on a site that is not on the allowed list. Call the API from your backend instead. |
| 404 | `not_found`, `download_failed` | Unknown endpoint or record. For `download_failed`, check the `uuid`, `type` and `signed` values. |
| 409 | `busy` | Another document is being created on this account. Retry after a few seconds with the same `reference`. |
| 409 | `gib_session_conflict` | GİB allows only one session per account, and another session is open (for example, someone is logged in to the portal in a browser). Ask the user to log out of the portal ("Güvenli Çıkış"), or wait for that session to time out, then retry. |
| 422 | `validation_failed` | The request is invalid. `details` maps each field to its errors, e.g. `{"malHizmetListe.0.kdvOrani": ["..."]}`. Fix the request and do not retry it unchanged. |
| 422 | `invalid_document` | The library rejected the document: invalid withholding code, special base reason or GTIP, for example. |
| 422 | `gib_rejected` | The GİB portal rejected the request. `details.gib_response` has the raw GİB answer. |
| 422 | `no_phone`, `signing_failed` | Signing problems, see [Signing](#7-signing-sms-approval). |
| 502 | `gib_login_failed` | The service could not log in to GİB. The credentials may be wrong, or the portal may be down. |
| 502 | `gib_unreachable` | GİB timed out or could not be reached. Safe to retry; send the same `reference` when retrying a create call. |

---

## 4. Endpoint summary

| Method | Path | Purpose |
|---|---|---|
| GET | `/api/v1/meta` | Allowed values: units, taxes, currencies, invoice types, withholding codes... (no auth) |
| GET | `/api/v1/me` | Which account and key you are using (does not call GİB) |
| GET | `/api/v1/profile` | Issuer (seller) information stored on the GİB portal |
| PATCH | `/api/v1/profile` | Partly update the issuer information |
| GET | `/api/v1/recipients/{vknOrTckn}` | Look up a recipient's name/title and tax office by VKN or TCKN |
| POST | `/api/v1/invoices/preview` | Calculate the invoice totals without sending to GİB |
| POST | `/api/v1/invoices` | Create a draft e-Arşiv invoice |
| POST | `/api/v1/self-employed-receipts/preview` | Calculate a serbest meslek makbuzu |
| POST | `/api/v1/self-employed-receipts` | Create a draft serbest meslek makbuzu |
| POST | `/api/v1/producer-receipts/preview` | Calculate a müstahsil makbuzu |
| POST | `/api/v1/producer-receipts` | Create a draft müstahsil makbuzu |
| GET | `/api/v1/documents` | List documents issued by you on GİB (date range required) |
| GET | `/api/v1/documents/issued-to-me` | List documents issued to you |
| GET | `/api/v1/documents/{uuid}` | Full document detail from GİB |
| GET | `/api/v1/documents/{uuid}/html` | Document as HTML (`text/html`), for display or PDF conversion |
| GET | `/api/v1/documents/{uuid}/download` | Official ZIP (HTML + UBL XML) |
| POST | `/api/v1/documents/delete` | Delete drafts. Signed documents cannot be deleted. |
| POST | `/api/v1/documents/{uuid}/cancel` | Send a cancellation request for a signed document |
| POST | `/api/v1/documents/{uuid}/objection` | Object to a document issued to you |
| GET | `/api/v1/requests` | Incoming cancellation and objection requests |
| POST | `/api/v1/signing/start` | Send an SMS code to the registered phone |
| POST | `/api/v1/signing/complete` | Sign drafts with the SMS code |
| GET | `/api/v1/records` | Local records of documents created through this API |
| GET | `/api/v1/records/{id}` | One local record, including the original request payload |
| DELETE | `/api/v1/session` | Close the cached GİB session (the next request logs in again) |

`{uuid}` must be a valid UUID. Document endpoints take an optional `type`: `invoice` (default), `self_employed_receipt` or `producer_receipt`. If you leave it out and this API created the document, the type is taken from the local record. Otherwise `invoice` is assumed. **Always send `type` for receipts.**

---

## 5. Creating documents

### 5.1 `POST /api/v1/invoices`: e-Arşiv invoice

Minimal request:

```json
{
  "reference": "order-1001",
  "vknTckn": "11111111111",
  "aliciAdi": "Mert",
  "aliciSoyadi": "Levent",
  "malHizmetListe": [
    { "malHizmet": "Web tasarım hizmeti", "miktar": 1, "birimFiyat": 1000, "kdvOrani": 20 }
  ]
}
```

Full example: company recipient, a discount, an extra tax and a note.

```json
{
  "reference": "order-1002",
  "vknTckn": "1234567890",
  "aliciUnvan": "Levent İnşaat Ltd. Şti.",
  "vergiDairesi": "Çekirge",
  "adres": "İzmir Yolu Cd. No:212/B",
  "mahalleSemtIlce": "Nilüfer",
  "sehir": "Bursa",
  "ulke": "Türkiye",
  "eposta": "muhasebe@example.com",
  "tarih": "2026-11-19",
  "saat": "14:30:00",
  "faturaTipi": "SATIS",
  "paraBirimi": "TRY",
  "siparisNumarasi": "SP-1002",
  "not": "Sipariş #1002",
  "malHizmetListe": [
    {
      "malHizmet": "Hosting",
      "miktar": 12,
      "birim": "Ay",
      "birimFiyat": 50,
      "kdvOrani": 20,
      "iskontoOrani": 10,
      "iskontoNedeni": "Yıllık ödeme"
    },
    {
      "malHizmet": "Muhtelif Oyuncak",
      "miktar": 2,
      "birim": "Adet",
      "birimFiyat": 309.87,
      "kdvOrani": 20,
      "vergiler": [ { "vergi": "Damga", "oran": 20 } ]
    }
  ]
}
```

Response `201 Created`:

```json
{
  "data": {
    "id": 1,
    "type": "invoice",
    "uuid": "27f0f81e-fe86-4042-b947-cd51d2f17e52",
    "document_number": "GIB2026000004550",
    "reference": "order-1001",
    "status": "draft",
    "recipient_id": "11111111111",
    "recipient_name": "Mert Levent",
    "currency": "TRY",
    "payable_amount": "1848.00",
    "document_date": "20/11/2026",
    "totals": {
      "matrah": 1540,
      "malHizmetToplamTutari": 1600,
      "toplamIskonto": 60,
      "hesaplananKdv": 308,
      "vergilerToplami": 308,
      "vergilerDahilToplamTutar": 1848,
      "toplamMasraflar": 0,
      "odenecekTutar": 1848
    },
    "created_at": "2026-11-20T01:08:46+03:00",
    "updated_at": "2026-11-20T01:08:46+03:00"
  },
  "idempotent_replay": false
}
```

If the same `reference` already exists, the response is `200` with `"idempotent_replay": true` and the original record.

**Recipient rules (GİB):**
- `vknTckn` must be 10 digits (VKN, company) or 11 digits (TCKN, individual).
- For an individual, send `aliciAdi` and `aliciSoyadi`. For a company, send `aliciUnvan` and `vergiDairesi`.
- If you don't know the recipient's TCKN (an end consumer), GİB accepts `11111111111`.
- To fill in the name and tax office from a VKN, call `GET /recipients/{vkn}` first.

#### Invoice types (`faturaTipi`)

| Value | Use | Extra fields |
|---|---|---|
| `SATIS` (default) | Normal sale | – |
| `IADE` | Return | `iadeListe` is required: `[{"faturaNo": "GIB2026000000001", "duzenlenmeTarihi": "2026-11-01"}]` |
| `TEVKIFAT` | VAT withholding | Set `tevkifatKodu` on each item (e.g. `604`). The rate is applied automatically. Codes: `GET /meta` → `withholding_codes`. |
| `ISTISNA` | Exemption | Optional `gtip` (12 digits) on each item |
| `OZELMATRAH` | Special base | `ozelMatrahNedeni` (801–812) and `ozelMatrahTutari` on each item |
| `IHRACKAYITLI` | Export-registered | – |
| `KONAKLAMAVERGISI` | Accommodation tax | Add `{"vergi": "Konaklama", "oran": 2}` to the items |

#### Foreign currency

```json
{ "paraBirimi": "USD", "dovizKuru": 34.52, ... }
```

`dovizKuru` is required when `paraBirimi` is not `TRY`.

#### Withholding (tevkifat) example

```json
{
  "vknTckn": "1234567890", "aliciUnvan": "ABC A.Ş.", "vergiDairesi": "Kadıköy",
  "faturaTipi": "TEVKIFAT",
  "malHizmetListe": [
    { "malHizmet": "Yemek servisi", "miktar": 1, "birimFiyat": 1000, "kdvOrani": 20, "tevkifatKodu": 604 }
  ]
}
```

The totals are KDV 200, withholding 5/10 = 100, payable 1100.

### 5.2 `POST /api/v1/self-employed-receipts`: serbest meslek makbuzu

```json
{
  "reference": "smm-55",
  "vknTckn": "11111111111",
  "aliciAdi": "Ayşe",
  "aliciSoyadi": "Yılmaz",
  "sehir": "İstanbul",
  "aciklama": "Kasım ayı danışmanlık",
  "malHizmetListe": [
    { "neIcinAlindigi": "Danışmanlık", "brutUcret": 5000, "kdvOrani": 20, "gvStopajOrani": 20 }
  ]
}
```

Totals: `brutUcret` 5000, `gvStopajTutari` 1000, `netUcretTutari` 4000, `kdvTutari` 1000, `netAlinanToplam` 5000.

### 5.3 `POST /api/v1/producer-receipts`: müstahsil makbuzu

```json
{
  "reference": "mm-7",
  "vknTckn": "11111111111",
  "aliciAdi": "Ali",
  "aliciSoyadi": "Çiftçi",
  "teslimTarihi": "2026-11-18",
  "malHizmetListe": [
    {
      "malHizmet": "Fındık",
      "miktar": 100,
      "birim": "Kgm",
      "birimFiyat": 120,
      "gvStopajOrani": 2,
      "vergiler": [ { "vergi": "BorsaTescil", "oran": 2 } ]
    }
  ]
}
```

Here `aliciAdi` and `aliciSoyadi` are the producer (the seller). Totals: 12000 − 240 stopaj − 235.20 borsa tescil = 11524.80 payable.

### 5.4 Preview (`.../preview`)

Each create endpoint has a `/preview` version. It takes the same body, sends nothing to GİB and saves nothing. It returns:

```json
{
  "data": {
    "type": "invoice",
    "totals": { "matrah": 1540, "hesaplananKdv": 308, "odenecekTutar": 1848, "...": 0 },
    "payable_amount": 1848,
    "gib_payload": { "...": "exact payload that would be sent to the GİB portal" }
  }
}
```

Use it to check that the payable amount matches your order total before you create the document.

---

## 6. Querying documents

### 6.1 `GET /api/v1/documents`

Lists the documents **you issued** on GİB.

| Query param | Required | Description |
|---|---|---|
| `start`, `end` | yes | Date range, `YYYY-MM-DD` or `DD/MM/YYYY`. At most 93 days. GİB allows 7 days per query, so the service splits longer ranges into 7-day queries. Longer ranges are slower, since each week is a separate GİB request. |
| `status` | no | `signed`, `unsigned` (drafts) or `deleted` |
| `type` | no | `invoice`, `self_employed_receipt` or `producer_receipt` |
| `recipient_id` | no | Recipient VKN/TCKN (substring match) |
| `recipient_name` | no | Recipient name or title (case-insensitive substring match) |
| `document_number` | no | e.g. `GIB2026000004550` |
| `uuid` | no | ETTN |
| `sort` | no | `asc` (default, oldest first) or `desc` |
| `limit`, `offset` | no | Pagination applied after filtering (`limit` 1–1000) |

Response:

```json
{
  "data": [
    {
      "belgeNumarasi": "GIB2026000004550",
      "aliciVknTckn": "11111111111",
      "aliciUnvanAdSoyad": "Mert Levent",
      "belgeTarihi": "20-11-2026",
      "belgeTuru": "FATURA",
      "onayDurumu": "Onaylanmadı",
      "ettn": "27f0f81e-fe86-4042-b947-cd51d2f17e52"
    }
  ],
  "meta": { "total": 1, "count": 1, "limit": null, "offset": 0 }
}
```

`onayDurumu` is one of `Onaylandı` (signed), `Onaylanmadı` (draft) or `Silinmiş` (deleted). `belgeTuru` is one of `FATURA`, `SERBEST MESLEK MAKBUZU` or `MÜSTAHSİL MAKBUZU`.

### 6.2 `GET /api/v1/documents/issued-to-me`

Lists documents **issued to you** by others. It takes the same parameters as above except `status` and `type`.

### 6.3 `GET /api/v1/documents/{uuid}?type=invoice`

Returns the full document from GİB: all header fields, the item table and the totals. The `local` field contains the local record if this API created the document, otherwise `null`.

### 6.4 `GET /api/v1/documents/{uuid}/html?type=invoice&signed=`

Returns the document as an HTML page (`Content-Type: text/html`). If you leave out `signed`, the service picks the right state: it uses the local record if there is one, otherwise it tries draft first and then signed.

### 6.5 `GET /api/v1/documents/{uuid}/download?type=invoice&signed=`

Returns `application/zip` with `<uuid>_f.html` and `<uuid>_f.xml` (UBL-TR). The `signed` parameter works the same as for HTML.

---

## 7. Signing (SMS approval)

A draft becomes a legal document only after it is signed. The flow needs a human who can read the SMS:

1. `POST /api/v1/signing/start` (no body). GİB sends an SMS code to the phone number registered on the portal.
   ```json
   { "data": { "oid": "1m2n3o4p5q", "phone": "*******4567", "next": "..." } }
   ```
2. Ask the user for the code in the SMS.
3. `POST /api/v1/signing/complete`:
   ```json
   {
     "type": "invoice",
     "oid": "1m2n3o4p5q",
     "code": "123456",
     "uuids": ["27f0f81e-fe86-4042-b947-cd51d2f17e52"]
   }
   ```
   Response: `{ "data": { "signed": 1, "uuids": ["..."] } }`

- `uuids` may contain several drafts. They must all be of the same `type`.
- If the code is wrong or expired, the response is `422 signing_failed`. Start again from step 1.
- If no phone number is registered on the portal, the response is `422 no_phone`.
- **The GİB test portal does not support SMS signing.** It returns `gib_rejected` with "Bu işlem için yetkiniz yok". Signing works only on production accounts.

---

## 8. Deleting, cancelling, objecting

### `POST /api/v1/documents/delete`

Deletes **drafts only**. A signed document must be cancelled instead.

```json
{ "type": "invoice", "uuids": ["27f0f81e-..."], "reason": "Hatalı tutar" }
```

Response: `{ "data": { "deleted": 1 } }`. If you leave out `reason`, it is "Hatalı İşlem".

### `POST /api/v1/documents/{uuid}/cancel`

Sends a cancellation request for a **signed** document. The recipient must accept it on the portal.

```json
{ "type": "invoice", "explanation": "Sipariş iptal edildi" }
```

### `POST /api/v1/documents/{uuid}/objection`

Objects to a document issued **to you**.

```json
{
  "type": "invoice",
  "method": "KEP",
  "document_id": "KEP-2026-0001",
  "document_date": "2026-11-19",
  "explanation": "Hizmet alınmadı"
}
```

`method` is one of `NOTER`, `TAAHHUTLU_MEKTUP`, `TELGRAF` or `KEP`.

### `GET /api/v1/requests?start=&end=`

Lists incoming cancellation and objection requests. The same date rules as `/documents` apply.

---

## 9. Field reference

Enum fields accept either the **value** or the **name**, case-insensitively. For example, `birim` accepts `"C62"`, `"Adet"` or `"adet"`, and `vergi` accepts `"1047"` or `"Damga"`. `GET /api/v1/meta` returns every allowed value with its label.

### 9.1 Invoice header (`POST /invoices`)

| Field | Type | Required | Notes |
|---|---|---|---|
| `reference` | string | recommended | Your idempotency key (≤191 characters), unique per account |
| `vknTckn` | string | **yes** | 10-digit VKN or 11-digit TCKN |
| `aliciUnvan` | string | company | Company title |
| `aliciAdi`, `aliciSoyadi` | string | individual | First name and last name |
| `vergiDairesi` | string | company | Tax office |
| `adres` | string | | Street address |
| `binaAdi`, `binaNo`, `kapiNo`, `kasabaKoy`, `mahalleSemtIlce`, `sehir`, `ulke`, `postaKodu` | string | | Address parts |
| `tel`, `fax`, `eposta`, `websitesi` | string | | Contact details |
| `tarih` | date | | Invoice date. Defaults to today (Europe/Istanbul). |
| `saat` | `HH:MM:SS` | | Defaults to now |
| `faturaTipi` | enum | | `SATIS` (default), `IADE`, `TEVKIFAT`, `ISTISNA`, `OZELMATRAH`, `IHRACKAYITLI`, `KONAKLAMAVERGISI` |
| `paraBirimi` | enum | | ISO currency, default `TRY` |
| `dovizKuru` | number | if not TRY | Exchange rate to TRY |
| `siparisNumarasi`, `siparisTarihi` | string, date | | Order number and date |
| `irsaliyeNumarasi`, `irsaliyeTarihi` | string, date | | Delivery note number and date |
| `fisNo`, `fisTarihi`, `fisSaati`, `fisTipi`, `zRaporNo`, `okcSeriNo` | string | | Receipt (ÖKC) details |
| `not` | string | | Note printed on the invoice |
| `iadeListe` | array | if `IADE` | `[{ "faturaNo": "GIB...", "duzenlenmeTarihi": date }]` |
| `malHizmetListe` | array | **yes** | At least one item (see 9.2) |

### 9.2 Invoice item (`malHizmetListe[]`)

| Field | Type | Required | Notes |
|---|---|---|---|
| `malHizmet` | string | **yes** | Product or service name |
| `miktar` | number | **yes** | Quantity (> 0) |
| `birimFiyat` | number | **yes** | Unit price, excluding VAT |
| `kdvOrani` | number | **yes** | One of `0, 1, 8, 10, 18, 20` |
| `birim` | enum | | Default `Adet` (C62). Common values: `Adet`, `Saat`, `Gun`, `Ay`, `Yil`, `Kgm`, `Grm`, `Ltr`, `Mtr`, `M2`, `M3`, `Kwh`, `Pk`, `Kutu`, `Set`. |
| `iskontoTipi` | string | | `İskonto` (discount, default) or `Arttırım` (surcharge) |
| `iskontoOrani` | number | | Discount percent (0–100) |
| `iskontoTutari` | number | | Fixed discount amount. Use it instead of `iskontoOrani`. |
| `iskontoNedeni` | string | | Reason for the discount |
| `tevkifatKodu` | int | `TEVKIFAT` | Withholding code (601–627, 801–825...), see `/meta` |
| `ozelMatrahNedeni` | int | `OZELMATRAH` | 801–812 |
| `ozelMatrahTutari` | number | `OZELMATRAH` | Special base amount |
| `gtip` | string | | 12-digit GTIP code (`ISTISNA`) |
| `vergiler` | array | | Extra taxes (see 9.3) |

Calculation per item: `fiyat = miktar × birimFiyat`, then discount, then `malHizmetTutari`, then `kdvTutari = malHizmetTutari × kdvOrani%`. Extra taxes are added after that.

### 9.3 Extra taxes (`vergiler[]`)

| Field | Type | Notes |
|---|---|---|
| `vergi` | enum | Tax name or code: `Damga` / `1047`, `OTV1Liste` / `0071`, `Konaklama` / `0059`, `BorsaTescil` / `8001`, `MeraFonu` / `9040`, `GVStopaj` / `0003`... Full list: `/meta` → `taxes` |
| `oran` | int | Rate in percent |
| `tutar` | number | Fixed amount. Leave it out to calculate it from `oran`. Required for taxes with a default rate (e.g. `OTV1Liste`). |
| `kdv` | number | VAT on this tax. Calculated automatically when the tax is subject to VAT. |

### 9.4 Self-employed receipt (`POST /self-employed-receipts`)

Header: `reference`, `vknTckn`*, `aliciUnvan`, `aliciAdi`, `aliciSoyadi`, `adres`, `binaAdi`, `binaNo`, `kapiNo`, `kasabaKoy`, `mahalleSemtIlce`, `sehir`, `ulke`, `postaKodu`, `vergiDairesi`, `tarih`, `saat`, `paraBirimi`, `dovizKuru`, `aciklama` (note), `kdvTahakkukIcin` (bool), `malHizmetListe`*.

Item: `neIcinAlindigi`* (description), `brutUcret`* (gross fee), `kdvOrani`* (0/1/8/10/18/20), `gvStopajOrani` (income tax withholding %, e.g. 20), `kdvTevkifatOrani` (VAT withholding %).

### 9.5 Producer receipt (`POST /producer-receipts`)

Header: `reference`, `vknTckn`*, `aliciAdi`*, `aliciSoyadi`*, `tarih`, `saat`, `teslimTarihi` (delivery date), `sehir`, `websitesi`, `not`, `malHizmetListe`*.

Item: `malHizmet`*, `miktar`*, `birimFiyat`*, `birim`, `gvStopajOrani` (e.g. 2 or 4), `vergiler` (e.g. `BorsaTescil`, `MeraFonu`, `SGKPrim`).

\* required

### 9.6 Profile (`PATCH /profile`)

Send only the fields you want to change. Other fields keep their current values. Fields: `vknTckn`, `unvan`, `ad`, `soyad`, `cadde`, `apartmanAdi`, `apartmanNo`, `kapiNo`, `kasaba`, `ilce`, `il`, `postaKodu`, `ulke`, `telNo`, `faksNo`, `ePostaAdresi`, `webSitesiAdresi`, `vergiDairesi`, `sicilNo`, `isMerkezi`, `mersisNo`.

---

## 10. Local records

### `GET /api/v1/records`

Lists documents created through this API with this account, newest first. Query: `reference`, `uuid`, `status` (`draft`, `signed`, `deleted`, `cancel_requested`), `type`, `recipient_id`, `per_page` (1–200), `page`.

Use `GET /records?reference=order-1001` to check whether an order already has an invoice.

### `GET /api/v1/records/{id}`

Returns one record, including the original request `payload`.

---

## 11. Typical agent workflows

**Issue an invoice for an order**
1. Optional: `GET /recipients/{vkn}` to fill in the recipient's name and tax office.
2. `POST /invoices/preview` and compare `payable_amount` with the order total.
3. `POST /invoices` with `reference` set to the order ID. Save `uuid` and `document_number`.
4. If the invoice must be legally final, ask the user to sign: `POST /signing/start`, get the SMS code from the user, then `POST /signing/complete`.
5. Share the document: `GET /documents/{uuid}/html` or `/download`.

**A request timed out or failed with 5xx.** Retry the same request with the same `reference`. If the first attempt reached GİB, you get the existing record back (`idempotent_replay: true`).

**Fix a wrong draft.** Delete it with `POST /documents/delete`, then create a new one with a **new** `reference`. Signed documents cannot be deleted; use `/cancel` and issue a new document.

**Find unsigned drafts from the last week.** `GET /documents?start=<today-6d>&end=<today>&status=unsigned&type=invoice`

---

## 12. Limits and notes

- e-Arşiv portal invoices are generally limited to buyers who are **not** e-Fatura users, and GİB applies daily and annual amount limits. GİB enforces these rules and rejects invalid requests with `gib_rejected`.
- Document creation is serialized per account: the library finds the new ETTN by looking up the latest document. Parallel create requests on the same account wait in line. If one waits longer than 60 seconds, it gets `409 busy`.
- If GİB creates the document but the service cannot read back its ETTN, the call returns an error and no local record is saved. In that case, check `/documents` before you retry without a `reference`.
- `test_mode` accounts use `earsivportaltest.efatura.gov.tr`. Test users are shared, so you may see documents created by other people.
