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

التقارير

إقرار ضريبة القيمة المضافة 201 وتقارير الأعمار، بالأرقام نفسها التي يعرضها التطبيق.

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

إقرار ضريبة القيمة المضافة 201

GET/reports/vat-201

يتطلب: reports.read + (sales.read | purchases.read)
النطاقات: reports:readsales:readpurchase:read

The VAT 201 return for from–to (YYYY-MM-DD, both days included), as the app builds it: output boxes 1a–8, input 9–11, net 12–14. Without a period, the quarter that has just ended. A period over 366 days, or from after to, is REPORT_PERIOD_INVALID.

المعاملات

الحقل	النوع	الوصف
`from`الاستعلام	`date`
`to`الاستعلام	`date`

أمثلة برمجية

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

الاستجابات

200OK
الحقل النوع الوصف
from date
to date
output object[]
input object[]
net object[]
excludedDocuments integer
unassignedDocuments integer
source string LIVE (computed now) or FILED (as filed).
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"
}
```

الحقل	النوع	الوصف
`from`	`date`
`to`	`date`
`output`	`object[]`
`input`	`object[]`
`net`	`object[]`
`excludedDocuments`	`integer`
`unassignedDocuments`	`integer`
`source`	`string`	LIVE (computed now) or FILED (as filed).

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

مثال

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

أعمار الذمم المدينة

GET/reports/aged-receivable

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

Open cleared invoices by days past due on asOf (today by default, never in the future): the five buckets and each customer's row.

المعاملات

الحقل	النوع	الوصف
`asOf`الاستعلام	`date`

أمثلة برمجية

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

الاستجابات

200OK
الحقل النوع الوصف
asOf date
buckets object[]
customers 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"
}
```

الحقل	النوع	الوصف
`asOf`	`date`
`buckets`	`object[]`
`customers`	`object[]`

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

مثال

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

أعمار الذمم الدائنة

GET/reports/aged-payable

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

What is owed to each vendor on posted bills by how late it is, and what the books owe beyond them. Needs the Accounting app and accounting:read: until Accounting is in the plan, 403 APP_LOCKED.

المعاملات

الحقل	النوع	الوصف
`asOf`الاستعلام	`date`

أمثلة برمجية

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

الاستجابات

200OK
الحقل النوع الوصف
asOf date
vendors 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"
}
```

الحقل	النوع	الوصف
`asOf`	`date`
`vendors`	`object[]`

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

مثال

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

ميزان المراجعة

GET/reports/trial-balance

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

Every account's opening, movement and closing over from–to from the stored ledger. Needs the Accounting app and accounting:read: until Accounting is in the plan, 403 APP_LOCKED. LEDGER_NOT_READY until the books are stored entries.

المعاملات

الحقل	النوع	الوصف
`from`الاستعلام	`date`
`to`الاستعلام	`date`
`includeClosing`الاستعلام	`boolean`

أمثلة برمجية

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

الاستجابات

200OK
الحقل النوع الوصف
from date
to date
rows object[]
totals 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"
}
```

الحقل	النوع	الوصف
`from`	`date`
`to`	`date`
`rows`	`object[]`
`totals`	`object`

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

مثال

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