مرجع الواجهة البرمجية

جهات الاتصال

دفتر واحد للعملاء والمورّدين. لا تغادر البيانات المصرفية والملاحظات الداخلية KWN أبدًا.

الأوصاف التقنية أدناه بالإنجليزية كما يولّدها خادم الواجهة، وهي اللغة التي تُكتب بها رسائل الأخطاء أيضًا. العناوين والجداول بالعربية.

عرض جهات الاتصال

GET/contacts

يتطلب: contacts.read
النطاقات: sales:readpurchase:readcontacts:read

Customers and vendors, newest first: type=customer or vendor, search by name, TRN or email, active=false for the archived. Bank accounts and internal notes are never returned.

المعاملات

الحقل	النوع	الوصف
`type`الاستعلام	`string`	customer or vendor.
`search`الاستعلام	`string`
`active`الاستعلام	`boolean`	true (default) for active contacts, false for archived.
`limit`الاستعلام	`integer`	1 to 200; 50 by default.
`cursor`الاستعلام	`string`	The previous page's next.
`updatedSince`الاستعلام	`date`	Only rows changed at or after this instant.
`createdFrom`الاستعلام	`date`
`createdTo`الاستعلام	`date`
`externalId`الاستعلام	`string`	Only the row your system gave this id.

أمثلة برمجية

curl -sS -X GET "https://app.kwn.tax/api/v1/contacts" \
  -H "X-Api-Key: $KWN_API_KEY"

الاستجابات

200OK
الحقل النوع الوصف
data object[] The rows of this page.
next string The cursor of the next page, to send as ?cursor=; null on the last page.
400Refused: the request or a business rule. The code says which (REQUEST_INVALID, RULE_REFUSED, …).
مثال
```
{
  "error": "Lines: at least one line is required.",
  "code": "REQUEST_INVALID"
}
```
401No key, a key that is not ours, or one revoked (API_KEY_INVALID); a merchant not active (MERCHANT_INACTIVE).
مثال
```
{
  "error": "That API key is not valid, or it was revoked.",
  "code": "API_KEY_INVALID"
}
```
403The key's scopes do not carry the capability (APP_NOT_GRANTED, ROLE_TOO_LOW), or the plan lacks the app (APP_LOCKED).
مثال
```
{
  "error": "This key's scopes do not include sales.approve.",
  "code": "ROLE_TOO_LOW"
}
```
404Not found: another type under this route, or another company's (NOT_FOUND).
مثال
```
{
  "error": "Not found.",
  "code": "NOT_FOUND"
}
```
409A conflict: an externalId taken, or a change that could not be saved (EXTERNAL_ID_TAKEN, CONFLICT).
مثال
```
{
  "error": "That externalId is already used by another record of this company.",
  "code": "EXTERNAL_ID_TAKEN"
}
```

الحقل	النوع	الوصف
`data`	`object[]`	The rows of this page.
`next`	`string`	The cursor of the next page, to send as ?cursor=; null on the last page.

429Too many requests: wait retryAfter seconds (RATE_LIMITED).

مثال

{
  "error": "Too many requests. Wait a little and try again.",
  "code": "RATE_LIMITED"
}

إنشاء جهة اتصال

POST/contacts

يتطلب: contacts.write
النطاقات: sales:writepurchase:writecontacts:write

أرسل ترويسة Idempotency-Key.

A customer by default (isCustomer), a vendor with isVendor. A UAE company's TRN is 15 digits. Requires Idempotency-Key.

المعاملات

الحقل	النوع	الوصف
`Idempotency-Key`الترويسةإلزامي	`string`	1 to 100 visible ASCII characters, such as a UUID, unique to this request. Sent again with the same request, the first answer is replayed (Idempotent-Replayed: true); with another request, 422 IDEMPOTENCY_KEY_REUSED.

جسم الطلب

25 حقلًا

الحقل	النوع	الوصف
`name`	`string`
`isCompany`	`boolean`
`isCustomer`	`boolean`
`isVendor`	`boolean`
`trn`	`string`	15 digits for a contact in the UAE.
`email`	`string`
`phone`	`string`
`mobile`	`string`
`website`	`string`
`address`	`string`
`street2`	`string`
`city`	`string`
`zip`	`string`
`state`	`string`
`emirate`	`ABU_DHABI \| DUBAI \| SHARJAH \| AJMAN \| UMM_AL_QUWAIN \| RAS_AL_KHAIMAH \| FUJAIRAH`
`country`	`string`
`parentId`	`string`
`companyName`	`string`
`paymentTermId`	`string`
`vendorPaymentTermId`	`string`
`fiscalPositionId`	`string`
`salespersonId`	`string`
`creditLimit`	`number`
`tags`	`string[]`
`externalId`	`string`	Your system's id for it, kept for good. Create only.

أمثلة برمجية

curl -sS -X POST "https://app.kwn.tax/api/v1/contacts" \
  -H "X-Api-Key: $KWN_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Al Noor Trading L.L.C.",
  "isCompany": true,
  "isCustomer": true,
  "trn": "100398765400003",
  "email": "accounts@alnoor.example",
  "phone": "+971 4 555 0142",
  "address": "Office 1204, Bay Square, Business Bay",
  "city": "Dubai",
  "emirate": "DUBAI",
  "country": "AE",
  "externalId": "CUST-0091"
}'

الاستجابات

201Created

الحقل	النوع	الوصف
`id`	`string`
`customerNo`	`string`
`name`	`string`
`isCompany`	`boolean`
`isCustomer`	`boolean`
`isVendor`	`boolean`
`active`	`boolean`
`trn`	`string`
`email`	`string`
`phone`	`string`
`mobile`	`string`
`website`	`string`
`address`	`string`
`street2`	`string`
`city`	`string`
`zip`	`string`
`state`	`string`
`emirate`	`ABU_DHABI \| DUBAI \| SHARJAH \| AJMAN \| UMM_AL_QUWAIN \| RAS_AL_KHAIMAH \| FUJAIRAH`
`country`	`string`
`parentId`	`string`
`companyName`	`string`
`paymentTermId`	`string`
`vendorPaymentTermId`	`string`
`fiscalPositionId`	`string`
`salespersonId`	`string`
`creditLimit`	`number`
`tags`	`string[]`
`externalId`	`string`
`createdAt`	`date`
`updatedAt`	`date`

400Refused: the request or a business rule. The code says which (REQUEST_INVALID, RULE_REFUSED, …).
مثال
```
{
  "error": "Lines: at least one line is required.",
  "code": "REQUEST_INVALID"
}
```
401No key, a key that is not ours, or one revoked (API_KEY_INVALID); a merchant not active (MERCHANT_INACTIVE).
مثال
```
{
  "error": "That API key is not valid, or it was revoked.",
  "code": "API_KEY_INVALID"
}
```
403The key's scopes do not carry the capability (APP_NOT_GRANTED, ROLE_TOO_LOW), or the plan lacks the app (APP_LOCKED).
مثال
```
{
  "error": "This key's scopes do not include sales.approve.",
  "code": "ROLE_TOO_LOW"
}
```
404Not found: another type under this route, or another company's (NOT_FOUND).
مثال
```
{
  "error": "Not found.",
  "code": "NOT_FOUND"
}
```
409A conflict: an externalId taken, or a change that could not be saved (EXTERNAL_ID_TAKEN, CONFLICT).
مثال
```
{
  "error": "That externalId is already used by another record of this company.",
  "code": "EXTERNAL_ID_TAKEN"
}
```

422That Idempotency-Key was used for a different request (IDEMPOTENCY_KEY_REUSED).

مثال

{
  "error": "That Idempotency-Key was used for a different request.",
  "code": "IDEMPOTENCY_KEY_REUSED"
}

429Too many requests: wait retryAfter seconds (RATE_LIMITED).

مثال

{
  "error": "Too many requests. Wait a little and try again.",
  "code": "RATE_LIMITED"
}

قراءة جهة اتصال

GET/contacts/{id}

يتطلب: contacts.read
النطاقات: sales:readpurchase:readcontacts:read

One contact of this company.

المعاملات

الحقل	النوع	الوصف
`id`المسارإلزامي	`string`

أمثلة برمجية

curl -sS -X GET "https://app.kwn.tax/api/v1/contacts/<id>" \
  -H "X-Api-Key: $KWN_API_KEY"

الاستجابات

200OK

الحقل	النوع	الوصف
`id`	`string`
`customerNo`	`string`
`name`	`string`
`isCompany`	`boolean`
`isCustomer`	`boolean`
`isVendor`	`boolean`
`active`	`boolean`
`trn`	`string`
`email`	`string`
`phone`	`string`
`mobile`	`string`
`website`	`string`
`address`	`string`
`street2`	`string`
`city`	`string`
`zip`	`string`
`state`	`string`
`emirate`	`ABU_DHABI \| DUBAI \| SHARJAH \| AJMAN \| UMM_AL_QUWAIN \| RAS_AL_KHAIMAH \| FUJAIRAH`
`country`	`string`
`parentId`	`string`
`companyName`	`string`
`paymentTermId`	`string`
`vendorPaymentTermId`	`string`
`fiscalPositionId`	`string`
`salespersonId`	`string`
`creditLimit`	`number`
`tags`	`string[]`
`externalId`	`string`
`createdAt`	`date`
`updatedAt`	`date`

400Refused: the request or a business rule. The code says which (REQUEST_INVALID, RULE_REFUSED, …).
مثال
```
{
  "error": "Lines: at least one line is required.",
  "code": "REQUEST_INVALID"
}
```
401No key, a key that is not ours, or one revoked (API_KEY_INVALID); a merchant not active (MERCHANT_INACTIVE).
مثال
```
{
  "error": "That API key is not valid, or it was revoked.",
  "code": "API_KEY_INVALID"
}
```
403The key's scopes do not carry the capability (APP_NOT_GRANTED, ROLE_TOO_LOW), or the plan lacks the app (APP_LOCKED).
مثال
```
{
  "error": "This key's scopes do not include sales.approve.",
  "code": "ROLE_TOO_LOW"
}
```
404Not found: another type under this route, or another company's (NOT_FOUND).
مثال
```
{
  "error": "Not found.",
  "code": "NOT_FOUND"
}
```
409A conflict: an externalId taken, or a change that could not be saved (EXTERNAL_ID_TAKEN, CONFLICT).
مثال
```
{
  "error": "That externalId is already used by another record of this company.",
  "code": "EXTERNAL_ID_TAKEN"
}
```

429Too many requests: wait retryAfter seconds (RATE_LIMITED).

مثال

{
  "error": "Too many requests. Wait a little and try again.",
  "code": "RATE_LIMITED"
}

تعديل جهة اتصال

PUT/contacts/{id}

يتطلب: contacts.write
النطاقات: sales:writepurchase:writecontacts:write

An optional field left out keeps what is on file.

المعاملات

الحقل	النوع	الوصف
`id`المسارإلزامي	`string`

جسم الطلب

25 حقلًا

الحقل	النوع	الوصف
`name`	`string`
`isCompany`	`boolean`
`isCustomer`	`boolean`
`isVendor`	`boolean`
`trn`	`string`	15 digits for a contact in the UAE.
`email`	`string`
`phone`	`string`
`mobile`	`string`
`website`	`string`
`address`	`string`
`street2`	`string`
`city`	`string`
`zip`	`string`
`state`	`string`
`emirate`	`ABU_DHABI \| DUBAI \| SHARJAH \| AJMAN \| UMM_AL_QUWAIN \| RAS_AL_KHAIMAH \| FUJAIRAH`
`country`	`string`
`parentId`	`string`
`companyName`	`string`
`paymentTermId`	`string`
`vendorPaymentTermId`	`string`
`fiscalPositionId`	`string`
`salespersonId`	`string`
`creditLimit`	`number`
`tags`	`string[]`
`externalId`	`string`	Your system's id for it, kept for good. Create only.

أمثلة برمجية

curl -sS -X PUT "https://app.kwn.tax/api/v1/contacts/<id>" \
  -H "X-Api-Key: $KWN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Al Noor Trading L.L.C.",
  "isCompany": true,
  "isCustomer": true,
  "trn": "100398765400003",
  "email": "accounts@alnoor.example",
  "phone": "+971 4 555 0142",
  "address": "Office 1204, Bay Square, Business Bay",
  "city": "Dubai",
  "emirate": "DUBAI",
  "country": "AE",
  "externalId": "CUST-0091"
}'

الاستجابات

200OK

الحقل	النوع	الوصف
`id`	`string`
`customerNo`	`string`
`name`	`string`
`isCompany`	`boolean`
`isCustomer`	`boolean`
`isVendor`	`boolean`
`active`	`boolean`
`trn`	`string`
`email`	`string`
`phone`	`string`
`mobile`	`string`
`website`	`string`
`address`	`string`
`street2`	`string`
`city`	`string`
`zip`	`string`
`state`	`string`
`emirate`	`ABU_DHABI \| DUBAI \| SHARJAH \| AJMAN \| UMM_AL_QUWAIN \| RAS_AL_KHAIMAH \| FUJAIRAH`
`country`	`string`
`parentId`	`string`
`companyName`	`string`
`paymentTermId`	`string`
`vendorPaymentTermId`	`string`
`fiscalPositionId`	`string`
`salespersonId`	`string`
`creditLimit`	`number`
`tags`	`string[]`
`externalId`	`string`
`createdAt`	`date`
`updatedAt`	`date`

400Refused: the request or a business rule. The code says which (REQUEST_INVALID, RULE_REFUSED, …).
مثال
```
{
  "error": "Lines: at least one line is required.",
  "code": "REQUEST_INVALID"
}
```
401No key, a key that is not ours, or one revoked (API_KEY_INVALID); a merchant not active (MERCHANT_INACTIVE).
مثال
```
{
  "error": "That API key is not valid, or it was revoked.",
  "code": "API_KEY_INVALID"
}
```
403The key's scopes do not carry the capability (APP_NOT_GRANTED, ROLE_TOO_LOW), or the plan lacks the app (APP_LOCKED).
مثال
```
{
  "error": "This key's scopes do not include sales.approve.",
  "code": "ROLE_TOO_LOW"
}
```
404Not found: another type under this route, or another company's (NOT_FOUND).
مثال
```
{
  "error": "Not found.",
  "code": "NOT_FOUND"
}
```
409A conflict: an externalId taken, or a change that could not be saved (EXTERNAL_ID_TAKEN, CONFLICT).
مثال
```
{
  "error": "That externalId is already used by another record of this company.",
  "code": "EXTERNAL_ID_TAKEN"
}
```

429Too many requests: wait retryAfter seconds (RATE_LIMITED).

مثال

{
  "error": "Too many requests. Wait a little and try again.",
  "code": "RATE_LIMITED"
}

أرشفة جهة اتصال

POST/contacts/{id}/archive

يتطلب: contacts.write
النطاقات: sales:writepurchase:writecontacts:write

The contact leaves the lists; its documents keep it. Archived already: alreadyDone.

المعاملات

الحقل	النوع	الوصف
`id`المسارإلزامي	`string`

أمثلة برمجية

curl -sS -X POST "https://app.kwn.tax/api/v1/contacts/<id>/archive" \
  -H "X-Api-Key: $KWN_API_KEY"

الاستجابات

200OK
الحقل النوع الوصف
alreadyDone boolean True when the document was already where the action takes it; nothing changed.
document object
400Refused: the request or a business rule. The code says which (REQUEST_INVALID, RULE_REFUSED, …).
مثال
```
{
  "error": "Lines: at least one line is required.",
  "code": "REQUEST_INVALID"
}
```
401No key, a key that is not ours, or one revoked (API_KEY_INVALID); a merchant not active (MERCHANT_INACTIVE).
مثال
```
{
  "error": "That API key is not valid, or it was revoked.",
  "code": "API_KEY_INVALID"
}
```
403The key's scopes do not carry the capability (APP_NOT_GRANTED, ROLE_TOO_LOW), or the plan lacks the app (APP_LOCKED).
مثال
```
{
  "error": "This key's scopes do not include sales.approve.",
  "code": "ROLE_TOO_LOW"
}
```
404Not found: another type under this route, or another company's (NOT_FOUND).
مثال
```
{
  "error": "Not found.",
  "code": "NOT_FOUND"
}
```
409A conflict: an externalId taken, or a change that could not be saved (EXTERNAL_ID_TAKEN, CONFLICT).
مثال
```
{
  "error": "That externalId is already used by another record of this company.",
  "code": "EXTERNAL_ID_TAKEN"
}
```

الحقل	النوع	الوصف
`alreadyDone`	`boolean`	True when the document was already where the action takes it; nothing changed.
`document`	`object`

429Too many requests: wait retryAfter seconds (RATE_LIMITED).

مثال

{
  "error": "Too many requests. Wait a little and try again.",
  "code": "RATE_LIMITED"
}

استعادة جهة اتصال

POST/contacts/{id}/restore

يتطلب: contacts.write
النطاقات: sales:writepurchase:writecontacts:write

Active already: alreadyDone.

المعاملات

الحقل	النوع	الوصف
`id`المسارإلزامي	`string`

أمثلة برمجية

curl -sS -X POST "https://app.kwn.tax/api/v1/contacts/<id>/restore" \
  -H "X-Api-Key: $KWN_API_KEY"

الاستجابات

200OK
الحقل النوع الوصف
alreadyDone boolean True when the document was already where the action takes it; nothing changed.
document object
400Refused: the request or a business rule. The code says which (REQUEST_INVALID, RULE_REFUSED, …).
مثال
```
{
  "error": "Lines: at least one line is required.",
  "code": "REQUEST_INVALID"
}
```
401No key, a key that is not ours, or one revoked (API_KEY_INVALID); a merchant not active (MERCHANT_INACTIVE).
مثال
```
{
  "error": "That API key is not valid, or it was revoked.",
  "code": "API_KEY_INVALID"
}
```
403The key's scopes do not carry the capability (APP_NOT_GRANTED, ROLE_TOO_LOW), or the plan lacks the app (APP_LOCKED).
مثال
```
{
  "error": "This key's scopes do not include sales.approve.",
  "code": "ROLE_TOO_LOW"
}
```
404Not found: another type under this route, or another company's (NOT_FOUND).
مثال
```
{
  "error": "Not found.",
  "code": "NOT_FOUND"
}
```
409A conflict: an externalId taken, or a change that could not be saved (EXTERNAL_ID_TAKEN, CONFLICT).
مثال
```
{
  "error": "That externalId is already used by another record of this company.",
  "code": "EXTERNAL_ID_TAKEN"
}
```

الحقل	النوع	الوصف
`alreadyDone`	`boolean`	True when the document was already where the action takes it; nothing changed.
`document`	`object`

429Too many requests: wait retryAfter seconds (RATE_LIMITED).

مثال

{
  "error": "Too many requests. Wait a little and try again.",
  "code": "RATE_LIMITED"
}