---
title: "Builds a UBL-TR e-Invoice or e-Archive XML document from plain JSON, computing every total and validating the parties."
method: POST
path: "/v1/tr/invoice/build"
tags: ["Finance"]
---

# Builds a UBL-TR e-Invoice or e-Archive XML document from plain JSON, computing every total and validating the parties.

`POST /v1/tr/invoice/build`

## Request

- Base URL: `https://api.temsor.com`
- URL: `https://api.temsor.com/v1/tr/invoice/build`
- Auth: one of:
  - HTTP bearer
  - API key in header `x-api-key`

Selling into Türkiye means issuing a UBL-TR document whose element order is fixed by schema and whose totals must agree to the kuruş, or the integrator rejects it. This endpoint takes the invoice as ordinary JSON and returns the XML. Totals you send are ignored on purpose — line amounts, per-rate VAT subtotals and the payable amount are all recomputed here, because a rounding difference of one kuruş is the most common rejection. VKN and TCKN checksums are verified, and the amount is written out in Turkish words as invoices require. It does not sign the document and does not transmit it: the financial seal and the submission to the tax authority belong to your certificate and your integrator. What comes back is a document ready to enter that step.

**Credits per call:** 3 · **Operation id:** `tr_invoice_build`

## Request body

- object
  - `profile` 'TEMELFATURA' | 'TICARIFATURA' | 'EARSIVFATURA': TEMELFATURA: no formal objection flow. TICARIFATURA: buyer may accept/reject. EARSIVFATURA: buyer is not an e-Invoice user.
  - `invoiceTypeCode` 'SATIS' | 'IADE'
  - `id` string: Invoice number. Omit and supply `series` to have it built from the series and sequence.
  - `series` string: Three-letter series code, used with `sequence`.
  - `sequence` integer: Sequence number within the series and year.
  - `uuid` string, uuid: Document UUID (ETTN). Generated when omitted.
  - `issueDate` string, required
  - `issueTime` string
  - `currency` string: ISO 4217. Anything other than TRY requires `exchangeRate`.
  - `exchangeRate` number: Units of TRY per one unit of `currency`.
  - `supplier` object, required
    - `name` string, required: Registered trade name, or the person’s full name.
    - `taxNumber` string, required: VKN (10 digits) or, for an individual, TCKN (11 digits).
    - `taxOffice` string: Tax office ("vergi dairesi"). Required for VKN holders.
    - `street` string
    - `buildingNumber` string
    - `district` string: District.
    - `city` string: City.
    - `postalCode` string
    - `country` string
    - `email` string
    - `phone` string
  - `customer` object, required
    - `name` string, required: Registered trade name, or the person’s full name.
    - `taxNumber` string, required: VKN (10 digits) or, for an individual, TCKN (11 digits).
    - `taxOffice` string: Tax office ("vergi dairesi"). Required for VKN holders.
    - `street` string
    - `buildingNumber` string
    - `district` string: District.
    - `city` string: City.
    - `postalCode` string
    - `country` string
    - `email` string
    - `phone` string
  - `lines` object[], required
    - `name` string, required: Item or service description as it must appear on the invoice.
    - `quantity` number
    - `unitCode` string: UN/ECE unit code. C62 = piece, KGM = kg, MTR = metre, HUR = hour.
    - `unitPrice` number, required: Net unit price, before VAT and before the discount.
    - `vatRate` number: VAT percentage, e.g. 20, 10, 1 or 0.
    - `discountRate` number: Line discount percentage applied to the net amount.
    - `note` string
    - `sellerItemCode` string
    - `vatExemptionReasonCode` string: Required by the tax authority when vatRate is 0.
  - `notes` string[]
  - `amountInWords` boolean: Adds the payable amount written out in Turkish words as a note, the way invoices require.
  - `despatchDocumentId` string: Delivery note number, if the goods shipped separately.
  - `orderReferenceId` string

## Response `200`

Success

- object
  - `ok` unknown, required
  - `data` object, required
    - `xml` string, required
    - `id` string, required
    - `uuid` string, required
    - `profile` string, required
    - `currency` string, required
    - `totals` object, required
      - `lineExtensionAmount` number, required
      - `allowanceTotalAmount` number, required
      - `taxExclusiveAmount` number, required
      - `taxTotalAmount` number, required
      - `taxInclusiveAmount` number, required
      - `payableAmount` number, required
    - `taxSubtotals` object[], required
      - `rate` number, required
      - `taxableAmount` number, required
      - `taxAmount` number, required
    - `lines` object[], required
      - `no` number, required
      - `name` string, required
      - `quantity` number, required
      - `unitPrice` number, required
      - `allowance` number, required
      - `lineExtensionAmount` number, required
      - `vatRate` number, required
      - `vatAmount` number, required
    - `checks` object[], required
      - `check` string, required
      - `passed` boolean, required
      - `detail` string, nullable, required
    - `nextSteps` string[], required
    - `warnings` string[], required
  - `meta` object
    - `credits` integer
    - `cached` boolean
    - `requestId` string
    - `durationMs` integer

## Other responses

- `400`: Error
- `401`: Error
- `402`: Error
- `429`: Rate limit exceeded — wait `Retry-After` seconds. The RateLimit headers are sent here too.

---

[API](https://skmtc.dev/temsor/apis/temsor-api.md) · [All operations](https://skmtc.dev/temsor/apis/temsor-api/llms.txt) · [OpenAPI document](https://skmtc.dev/temsor/apis/temsor-api/revisions/19702107e15a?raw)