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

المنتجات

قائمة المنتجات بقواعد التطبيق نفسها: ضريبة 5 أو 0، والرمز الشريطي لا يتكرر.

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

عرض المنتجات

GET/products

يتطلب: products.read
النطاقات: sales:readpurchase:readaccounting:read

Newest first: search by name or internal reference, sku, barcode, active=false for the archived.

المعاملات

الحقل	النوع	الوصف
`search`الاستعلام	`string`
`sku`الاستعلام	`string`
`barcode`الاستعلام	`string`
`active`الاستعلام	`boolean`
`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/products" \
  -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/products

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

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

VAT is 5 (standard) or 0 (zero-rated). A barcode is unique in the company. 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.

جسم الطلب

15 حقلًا

الحقل	النوع	الوصف
`name`	`string`
`unitPrice`	`number`	VAT-exclusive sales price.
`taxRate`	`number`	Sales VAT percent: 5 or 0; 5 on a new product, what is on file on an update.
`sku`	`string`	Internal reference.
`barcode`	`string`
`description`	`string`
`purchaseDescription`	`string`
`type`	`GOODS \| SERVICE`
`uom`	`string`
`costPrice`	`number`
`purchaseTaxRate`	`number`
`categoryId`	`string`
`saleOk`	`boolean`
`purchaseOk`	`boolean`
`externalId`	`string`	Your system's id for it, kept for good. Create only.

أمثلة برمجية

curl -sS -X POST "https://app.kwn.tax/api/v1/products" \
  -H "X-Api-Key: $KWN_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Office chair, mesh back",
  "unitPrice": 450,
  "taxRate": 5,
  "sku": "CHR-MESH-01",
  "barcode": "6291041500213",
  "costPrice": 280,
  "externalId": "ITEM-3310"
}'

الاستجابات

201Created

الحقل	النوع	الوصف
`id`	`string`
`name`	`string`
`sku`	`string`
`barcode`	`string`
`description`	`string`
`purchaseDescription`	`string`
`type`	`GOODS \| SERVICE`
`uom`	`string`
`unitPrice`	`number`
`costPrice`	`number`
`taxRate`	`number`
`purchaseTaxRate`	`number`
`categoryId`	`string`
`saleOk`	`boolean`
`purchaseOk`	`boolean`
`active`	`boolean`
`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/products/{id}

يتطلب: products.read
النطاقات: sales:readpurchase:readaccounting:read

One product of this company.

المعاملات

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

أمثلة برمجية

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

الاستجابات

200OK

الحقل	النوع	الوصف
`id`	`string`
`name`	`string`
`sku`	`string`
`barcode`	`string`
`description`	`string`
`purchaseDescription`	`string`
`type`	`GOODS \| SERVICE`
`uom`	`string`
`unitPrice`	`number`
`costPrice`	`number`
`taxRate`	`number`
`purchaseTaxRate`	`number`
`categoryId`	`string`
`saleOk`	`boolean`
`purchaseOk`	`boolean`
`active`	`boolean`
`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/products/{id}

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

An optional field left out keeps what is on file.

المعاملات

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

جسم الطلب

15 حقلًا

الحقل	النوع	الوصف
`name`	`string`
`unitPrice`	`number`	VAT-exclusive sales price.
`taxRate`	`number`	Sales VAT percent: 5 or 0; 5 on a new product, what is on file on an update.
`sku`	`string`	Internal reference.
`barcode`	`string`
`description`	`string`
`purchaseDescription`	`string`
`type`	`GOODS \| SERVICE`
`uom`	`string`
`costPrice`	`number`
`purchaseTaxRate`	`number`
`categoryId`	`string`
`saleOk`	`boolean`
`purchaseOk`	`boolean`
`externalId`	`string`	Your system's id for it, kept for good. Create only.

أمثلة برمجية

curl -sS -X PUT "https://app.kwn.tax/api/v1/products/<id>" \
  -H "X-Api-Key: $KWN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Office chair, mesh back",
  "unitPrice": 450,
  "taxRate": 5,
  "sku": "CHR-MESH-01",
  "barcode": "6291041500213",
  "costPrice": 280,
  "externalId": "ITEM-3310"
}'

الاستجابات

200OK

الحقل	النوع	الوصف
`id`	`string`
`name`	`string`
`sku`	`string`
`barcode`	`string`
`description`	`string`
`purchaseDescription`	`string`
`type`	`GOODS \| SERVICE`
`uom`	`string`
`unitPrice`	`number`
`costPrice`	`number`
`taxRate`	`number`
`purchaseTaxRate`	`number`
`categoryId`	`string`
`saleOk`	`boolean`
`purchaseOk`	`boolean`
`active`	`boolean`
`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"
}