Required fields
Customer code, unique within the company. Send
"Next" on create to generate it.Digits only: a 10-digit tax number (VKN) or an 11-digit Turkish national ID number (TCKN).
General fields
Risk
Only
RiskAction 2 is enforced by the API; 0 and 1 never block a request. When it is 2, a sales order with a customer movement, a sales invoice and a purchase-return invoice for this customer are rejected if they break the limit (error 6020 for orders, 3028 for invoices). The limit is in the company’s default currency; amounts in other currencies are converted with the document’s exchange rate.
RiskControl1(current balance): rejected when the customer’s balance (debit minus credit of all customer movements) plus the document’s amount would exceed the limit.RiskControl2(sales amount): rejected when the document’s amount alone exceeds the limit; the balance is not considered.
E-invoice
E-invoice labels (mailbox aliases) cannot be sent through the API. Send
QueryEInvoiceLabels: true on create to query them from the e-invoice integrator. Details are in the E-invoice labels section below.
Note
The text inNote can be shown on documents with the flags below. If any flag is true, Note is required. Flags that are not sent are treated as false.
ShowNoteOnQuote, ShowNoteOnOrder, ShowNoteOnDespatch, ShowNoteOnInvoice
Identity schemes
IdentitySchemes holds additional identifiers based on UBL identity schemes (used in e-documents).
SchemeID can be sent at most once and Value cannot be empty. Valid SchemeID values:
VKN, TCKN, HIZMETNO, MUSTERINO, TESISATNO, TELEFONNO, DISTRIBUTORNO, TICARETSICILNO, TAPDKNO, BAYINO, ABONENO, SAYACNO, EPDKNO, SUBENO, PASAPORTNO, URETICINO, CIFTCINO, IMALATCINO, DOSYANO, HASTANO, MERSISNO, ARACIKURUMVKN, ARACIKURUMETIKET, GTB_REFNO, GCB_TESCILNO, GTB_FIILI_IHRACAT_TARIHI, ARACKIMLIKNO, PLAKA, SEVKIYATNO
Sub-records
Customer sub-records can be managed in two ways:- When creating a customer: with the lists in the
POST /customersbody, in the same operation as the customer. If any record is invalid, the customer is not created either. - Afterwards: with each sub-record’s own endpoints (
/customers/{customerId}/addressesand so on). They support list, get, create, update and delete.
Update customer does not change sub-records; use their own endpoints. If the customer is not visible to the user, all sub-record endpoints return 404.
PUT or partially updated with PATCH. See Partial update.
Addresses
/customers/{customerId}/addresses
FullAddress in responses is the address combined with district, city and country, and is read-only.
Invoice address rules
A customer always has exactly one invoice address.- When creating a customer with a single address, that address becomes the invoice address. With several addresses, exactly one must have
IsInvoiceAddress: true. - When adding an address, the customer’s first address always becomes the invoice address. A new address added with
IsInvoiceAddress: truebecomes the invoice address and the previous one loses the flag. - The flag of the invoice address cannot be removed by an update, and the invoice address cannot be deleted. Mark another address as the invoice address first.
Telephones
/customers/{customerId}/telephones
Links
/customers/{customerId}/links
Representatives
/customers/{customerId}/representatives
Bank accounts
/customers/{customerId}/bank-accounts
Send either
Iban, or Branch together with AccountNumber.
Group memberships
/customers/{customerId}/group-members
- A customer can be a member of the same group detail only once.
- Some groups may be defined as mandatory. When creating a customer, at least one detail from every mandatory group must be sent. This is checked only on create, not when a membership is deleted.
Parameters
/customers/{customerId}/parameters
In responses,
ParameterType is the definition type and Value is the value in that type’s format.
E-invoice labels
E-invoice labels (GİB mailbox aliases) cannot be sent through the API; they are read-only. SendQueryEInvoiceLabels: true when creating a customer to query the labels from the e-invoice integrator by TaxNumber after the customer is saved:
- Labels found are saved, and the first one is marked as default.
- If the query fails, the customer is still created; labels stay empty and the response
Messagesays the labels could not be queried.Messagealso says so when no label is found for the tax number.
EInvoiceLabels of Get customer.
Example
POST /api/v1/customers