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

فواتير المورّدين

فواتير المورّدين: تُنشأ من أمر شراء ثم تُرحَّل. الترحيل هو الاعتماد ويتطلب purchase:approve.

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

عرض فواتير المورّدين

GET/bills

يتطلب: purchases.read
النطاقات: purchase:read

Every vendor bill, newest first, whether pushed, billed from an order or typed in.

المعاملات

الحقل	النوع	الوصف
`status`الاستعلام	`string`	A status, by name.
`partnerId`الاستعلام	`string`	The customer (sales) or the vendor (purchases).
`issueFrom`الاستعلام	`date`	Issued on or after this day.
`issueTo`الاستعلام	`date`	Issued on or before this day.
`number`الاستعلام	`string`
`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/bills" \
  -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"
}

قراءة فاتورة مورّد

GET/bills/{id}

يتطلب: purchases.read
النطاقات: purchase:read

Any bill of the company, with its lines. A superset of what the legacy push answers.

المعاملات

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

أمثلة برمجية

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

الاستجابات

200OK

الحقل	النوع	الوصف
`id`	`string`
`type`	`RFQ \| ORDER \| BILL \| REFUND \| DEBIT_NOTE`
`number`	`string`
`status`	`DRAFT \| SENT \| CONFIRMED \| RECEIVED \| POSTED \| PAID \| CANCELLED`
`issueDate`	`date`
`dueDate`	`date`
`vendor`	`object`
`vendorRef`	`string`
`buyerId`	`string`
`paymentTermId`	`string`
`notes`	`string`
`lines`	`object[]`
`subtotal`	`number`
`discountTotal`	`number`
`taxTotal`	`number`
`total`	`number`
`paidTotal`	`number`
`creditedTotal`	`number`
`origin`	`MANUAL \| API \| EINVOICE`
`source`	`object`
`derived`	`object[]`
`externalId`	`string`
`duplicate`	`boolean`	Always false here; true only on the legacy push when it answered a bill it already had.
`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/bills/{id}

يتطلب: purchases.write
النطاقات: purchase:write

Replaces the header and lines of a draft bill. A bill pushed through the legacy endpoint stays without VAT.

المعاملات

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

جسم الطلب

20 حقلًا

الحقل	النوع	الوصف
`lines`	`object[]`
`lines[].unitPrice`	`number`
`lines[].quantity`	`number`
`lines[].taxRate`	`number`	VAT percent: 5 or 0.
`lines[].description`	`string`
`lines[].productId`	`string`
`lines[].productCode`	`string`	A product's SKU, then its barcode.
`lines[].uom`	`string`
`lines[].discount`	`number`
`lines[].kind`	`PRODUCT \| SECTION \| NOTE`
`vendorId`	`string`	The vendor contact; needed to confirm.
`issueDate`	`date`
`dueDate`	`date`
`vendorRef`	`string`	The vendor's own reference.
`notes`	`string`
`orderDeadline`	`date`
`expectedArrival`	`date`
`buyerId`	`string`
`paymentTermId`	`string`
`externalId`	`string`	Your system's id for it, kept for good. Create only.

أمثلة برمجية

curl -sS -X PUT "https://app.kwn.tax/api/v1/bills/<id>" \
  -H "X-Api-Key: $KWN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "vendorId": "ven_7xp3k8d2",
  "issueDate": "2026-10-15",
  "vendorRef": "Q-2026-118",
  "externalId": "PO-5521",
  "lines": [
    {
      "description": "A4 copier paper, box of 5 reams",
      "quantity": 20,
      "unitPrice": 95,
      "taxRate": 5,
      "productCode": "PAP-A4-5"
    }
  ]
}'

الاستجابات

200OK

الحقل	النوع	الوصف
`id`	`string`
`type`	`RFQ \| ORDER \| BILL \| REFUND \| DEBIT_NOTE`
`number`	`string`
`status`	`DRAFT \| SENT \| CONFIRMED \| RECEIVED \| POSTED \| PAID \| CANCELLED`
`issueDate`	`date`
`dueDate`	`date`
`vendor`	`object`
`vendorRef`	`string`
`buyerId`	`string`
`paymentTermId`	`string`
`notes`	`string`
`lines`	`object[]`
`subtotal`	`number`
`discountTotal`	`number`
`taxTotal`	`number`
`total`	`number`
`paidTotal`	`number`
`creditedTotal`	`number`
`origin`	`MANUAL \| API \| EINVOICE`
`source`	`object`
`derived`	`object[]`
`externalId`	`string`
`duplicate`	`boolean`	Always false here; true only on the legacy push when it answered a bill it already had.
`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/bills/{id}/post

يتطلب: purchases.approve
النطاقات: purchase:approve

Validates the draft bill into the books: Dr expenses and input VAT, Cr the vendor's payable. Posted already: alreadyDone.

المعاملات

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

أمثلة برمجية

curl -sS -X POST "https://app.kwn.tax/api/v1/bills/<id>/post" \
  -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/bills/{id}/cancel

يتطلب: purchases.write
النطاقات: purchase:write

A posted bill is refunded, never cancelled. Cancelled already: alreadyDone.

المعاملات

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

أمثلة برمجية

curl -sS -X POST "https://app.kwn.tax/api/v1/bills/<id>/cancel" \
  -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/bills/{id}/refunds

يتطلب: purchases.write
النطاقات: purchase:write

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

A draft refund against a posted bill. Requires Idempotency-Key.

المعاملات

الحقل	النوع	الوصف
`id`المسارإلزامي	`string`
`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.

أمثلة برمجية

curl -sS -X POST "https://app.kwn.tax/api/v1/bills/<id>/refunds" \
  -H "X-Api-Key: $KWN_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

الاستجابات

201Created

الحقل	النوع	الوصف
`id`	`string`
`type`	`RFQ \| ORDER \| BILL \| REFUND \| DEBIT_NOTE`
`number`	`string`
`status`	`DRAFT \| SENT \| CONFIRMED \| RECEIVED \| POSTED \| PAID \| CANCELLED`
`issueDate`	`date`
`dueDate`	`date`
`vendor`	`object`
`vendorRef`	`string`
`buyerId`	`string`
`paymentTermId`	`string`
`notes`	`string`
`orderDeadline`	`date`
`expectedArrival`	`date`
`lines`	`object[]`
`subtotal`	`number`
`discountTotal`	`number`
`taxTotal`	`number`
`total`	`number`
`paidTotal`	`number`
`creditedTotal`	`number`
`origin`	`MANUAL \| API \| EINVOICE`
`source`	`object`
`derived`	`object[]`
`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/bills/{id}/pdf

يتطلب: purchases.read
النطاقات: purchase:read

The printed document as the app prints it, in English or Arabic (?lang=ar). Counted against the apikey-heavy budget.

المعاملات

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

أمثلة برمجية

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

الاستجابات

200OK
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"
}