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

الإشعارات الدائنة

إشعارات دائنة على فاتورة مخلّصة، تُعتمد وتُخلَّص بالطريقة نفسها.

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

تعديل مسودة

PUT/credit-notes/{id}

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

Replaces the header and the lines of a draft. Anything past a draft is refused with the app's own sentence (RULE_REFUSED).

المعاملات

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

جسم الطلب

29 حقلًا

الحقل	النوع	الوصف
`lines`	`object[]`
`lines[].unitPrice`	`number`	What it costs; a product needs no product. VAT-exclusive, as stored.
`lines[].quantity`	`number`
`lines[].taxRate`	`number`	VAT percent: 5 (standard) or 0 (zero-rated).
`lines[].description`	`string`
`lines[].productId`	`string`	A product of this company by id …
`lines[].productCode`	`string`	… or by its internal reference (SKU), then its barcode.
`lines[].uom`	`string`
`lines[].discount`	`number`	Discount percent, 0 to 100.
`lines[].kind`	`PRODUCT \| SECTION \| NOTE`
`customerId`	`string`	Required on an invoice.
`issueDate`	`date`	The document's day, YYYY-MM-DD. Defaults to today.
`dueDate`	`date`
`expiryDate`	`date`	A quotation's expiry day.
`customerRef`	`string`
`notes`	`string`
`paymentTermId`	`string`
`fiscalPositionId`	`string`
`salespersonId`	`string`
`salesTeamId`	`string`
`emirate`	`ABU_DHABI \| DUBAI \| SHARJAH \| AJMAN \| UMM_AL_QUWAIN \| RAS_AL_KHAIMAH \| FUJAIRAH`
`taxMode`	`TAX_EXCLUDED \| TAX_INCLUDED`
`invoiceAddressId`	`string`
`deliveryAddressId`	`string`
`externalId`	`string`	Your system's id for it, kept for good; unique per company. Create only.
`paymentMeansCode`	`string`	UNCL 4461 payment means, such as 30 (credit transfer).
`transactionFlags`	`FREE_TRADE_ZONE \| DEEMED_SUPPLY \| MARGIN_SCHEME \| SUMMARY_INVOICE \| CONTINUOUS_SUPPLY \| DISCLOSED_AGENT_BILLING \| ECOMMERCE \| EXPORTS[]`
`invoicePeriodStart`	`string`
`invoicePeriodEnd`	`string`

أمثلة برمجية

curl -sS -X PUT "https://app.kwn.tax/api/v1/credit-notes/<id>" \
  -H "X-Api-Key: $KWN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "customerId": "cus_4kq9w2m1",
  "issueDate": "2026-10-15",
  "dueDate": "2026-11-14",
  "customerRef": "PO-7781",
  "externalId": "SO-10045",
  "lines": [
    {
      "description": "Office chair, mesh back",
      "quantity": 4,
      "unitPrice": 450,
      "taxRate": 5,
      "productCode": "CHR-MESH-01"
    },
    {
      "description": "Delivery within Dubai",
      "quantity": 1,
      "unitPrice": 100,
      "taxRate": 5
    }
  ]
}'

الاستجابات

200OK

الحقل	النوع	الوصف
`id`	`string`
`type`	`QUOTATION \| ORDER \| INVOICE \| CREDIT_NOTE \| DEBIT_NOTE`
`number`	`string`
`status`	`DRAFT \| SENT \| CONFIRMED \| ISSUED \| SUBMITTED \| PROCESSING \| APPROVED \| REJECTED \| FAILED \| PAID \| CANCELLED \| EXPIRED`
`issueDate`	`date`
`dueDate`	`date`
`expiryDate`	`date`
`customer`	`object`
`emirate`	`ABU_DHABI \| DUBAI \| SHARJAH \| AJMAN \| UMM_AL_QUWAIN \| RAS_AL_KHAIMAH \| FUJAIRAH`
`currency`	`string`
`taxMode`	`TAX_EXCLUDED \| TAX_INCLUDED`
`customerRef`	`string`
`notes`	`string`
`paymentTermId`	`string`
`fiscalPositionId`	`string`
`salespersonId`	`string`
`salesTeamId`	`string`
`invoiceAddressId`	`string`
`deliveryAddressId`	`string`
`lines`	`object[]`
`subtotal`	`number`
`discountTotal`	`number`
`taxTotal`	`number`
`total`	`number`
`invoicedTotal`	`number`
`paidTotal`	`number`
`creditedTotal`	`number`
`source`	`object`
`derived`	`object[]`
`origin`	`string`	API, MANUAL, ODOO or POS.
`externalId`	`string`
`clearance`	`object`
`eInvoice`	`object`
`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"
}

قراءة مستند

GET/credit-notes/{id}

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

The document with its lines, where it came from and what came of it, its e-invoice readiness and, for an invoice or credit note, its clearance. A document of another type under this route is NOT_FOUND.

المعاملات

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

أمثلة برمجية

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

الاستجابات

200OK

الحقل	النوع	الوصف
`id`	`string`
`type`	`QUOTATION \| ORDER \| INVOICE \| CREDIT_NOTE \| DEBIT_NOTE`
`number`	`string`
`status`	`DRAFT \| SENT \| CONFIRMED \| ISSUED \| SUBMITTED \| PROCESSING \| APPROVED \| REJECTED \| FAILED \| PAID \| CANCELLED \| EXPIRED`
`issueDate`	`date`
`dueDate`	`date`
`expiryDate`	`date`
`customer`	`object`
`emirate`	`ABU_DHABI \| DUBAI \| SHARJAH \| AJMAN \| UMM_AL_QUWAIN \| RAS_AL_KHAIMAH \| FUJAIRAH`
`currency`	`string`
`taxMode`	`TAX_EXCLUDED \| TAX_INCLUDED`
`customerRef`	`string`
`notes`	`string`
`paymentTermId`	`string`
`fiscalPositionId`	`string`
`salespersonId`	`string`
`salesTeamId`	`string`
`invoiceAddressId`	`string`
`deliveryAddressId`	`string`
`lines`	`object[]`
`subtotal`	`number`
`discountTotal`	`number`
`taxTotal`	`number`
`total`	`number`
`invoicedTotal`	`number`
`paidTotal`	`number`
`creditedTotal`	`number`
`source`	`object`
`derived`	`object[]`
`origin`	`string`	API, MANUAL, ODOO or POS.
`externalId`	`string`
`clearance`	`object`
`eInvoice`	`object`
`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/credit-notes/{id}/request-approval

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

Puts a draft in front of a person who may approve it. Not available yet: RULE_REFUSED.

المعاملات

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

أمثلة برمجية

curl -sS -X POST "https://app.kwn.tax/api/v1/credit-notes/<id>/request-approval" \
  -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/credit-notes/{id}/approve

يتطلب: sales.approve
النطاقات: sales:approve

Checks the lock dates, the UAE mandatory fields, the clearance rules and the provider's dry run, and moves the draft to ISSUED. Costs nothing. Approved already: alreadyDone.

المعاملات

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

أمثلة برمجية

curl -sS -X POST "https://app.kwn.tax/api/v1/credit-notes/<id>/approve" \
  -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/credit-notes/{id}/issue

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

Takes the document's one credit and queues it for clearance. A draft is approved first when the key holds sales:approve, else APPROVAL_REQUIRED. Sent already: alreadyDone. The answer may say SUBMITTED; poll the document or its clearance for the outcome.

المعاملات

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

أمثلة برمجية

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

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

A draft, an approved document not yet sent, or a rejected one (its credit is released). A cleared document is credited, never cancelled. Cancelled already: alreadyDone.

المعاملات

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

أمثلة برمجية

curl -sS -X POST "https://app.kwn.tax/api/v1/credit-notes/<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/credit-notes/{id}/reset-to-draft

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

A rejected or failed document opens again for correction. A draft already: alreadyDone.

المعاملات

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

أمثلة برمجية

curl -sS -X POST "https://app.kwn.tax/api/v1/credit-notes/<id>/reset-to-draft" \
  -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"
}

حالة التخليص

GET/credit-notes/{id}/clearance

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

Where the document stands with e-invoicing clearance: status, provider reference, attempts and the provider's errors.

المعاملات

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

أمثلة برمجية

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

الاستجابات

200OK

الحقل	النوع	الوصف
`status`	`string`	The document's status: SUBMITTED, PROCESSING, APPROVED (cleared), REJECTED, FAILED, …
`route`	`string`	TAXSTAR, LOCAL_B2C or LOCAL_CREDIT_NOTE; null before it is issued.
`provider`	`object`
`providerCode`	`string`
`reference`	`string`	The provider's or the FTA's reference once cleared.
`submittedAt`	`date`
`lastCheckedAt`	`date`
`clearedAt`	`date`
`attempts`	`integer`
`errorCode`	`string`
`error`	`string`
`errors`	`object[]`
`delivery`	`string`
`canRetry`	`boolean`
`canRefresh`	`boolean`

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/credit-notes/{id}/clearance/retry

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

A FAILED document is sent to the provider again, with no second credit.

المعاملات

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

أمثلة برمجية

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

الاستجابات

200OK

الحقل	النوع	الوصف
`status`	`string`	The document's status: SUBMITTED, PROCESSING, APPROVED (cleared), REJECTED, FAILED, …
`route`	`string`	TAXSTAR, LOCAL_B2C or LOCAL_CREDIT_NOTE; null before it is issued.
`provider`	`object`
`providerCode`	`string`
`reference`	`string`	The provider's or the FTA's reference once cleared.
`submittedAt`	`date`
`lastCheckedAt`	`date`
`clearedAt`	`date`
`attempts`	`integer`
`errorCode`	`string`
`error`	`string`
`errors`	`object[]`
`delivery`	`string`
`canRetry`	`boolean`
`canRefresh`	`boolean`

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/credit-notes/{id}/clearance/refresh

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

Asks the provider for the outcome of a PROCESSING document now. At most every 30 seconds: REFRESH_TOO_SOON with retryAfter.

المعاملات

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

أمثلة برمجية

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

الاستجابات

200OK

الحقل	النوع	الوصف
`status`	`string`	The document's status: SUBMITTED, PROCESSING, APPROVED (cleared), REJECTED, FAILED, …
`route`	`string`	TAXSTAR, LOCAL_B2C or LOCAL_CREDIT_NOTE; null before it is issued.
`provider`	`object`
`providerCode`	`string`
`reference`	`string`	The provider's or the FTA's reference once cleared.
`submittedAt`	`date`
`lastCheckedAt`	`date`
`clearedAt`	`date`
`attempts`	`integer`
`errorCode`	`string`
`error`	`string`
`errors`	`object[]`
`delivery`	`string`
`canRetry`	`boolean`
`canRefresh`	`boolean`

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

عرض القائمة

GET/credit-notes

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

Newest first, a page at a time: send the previous page's next as cursor. Filter by status, partnerId (the customer), issueFrom/issueTo, number, externalId, createdFrom/createdTo, or updatedSince to poll for changes.

المعاملات

الحقل	النوع	الوصف
`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/credit-notes" \
  -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/credit-notes/{id}/pdf

يتطلب: sales.read
النطاقات: sales: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/credit-notes/<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"
}