API reference

Sales orders

Confirmed orders, invoiced whole, by a percentage or by an amount.

Invoice an order

POST/sales-orders/{id}/invoices

Needs: sales.write
Scopes: sales:write

Send an Idempotency-Key header.

A draft invoice for what is left on the order (mode whole), a share of it (percent) or an amount. Each invoice raised from an order uses one credit when it is issued. Requires Idempotency-Key.

Parameters

Field	Type	Description
`id`PathRequired	`string`
`Idempotency-Key`HeaderRequired	`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.

Request body

3 fields

Field	Type	Description
`mode`	`string`	whole, percent or amount.
`percent`	`number`
`amount`	`number`

Code samples

curl -sS -X POST "https://app.kwn.tax/api/v1/sales-orders/<id>/invoices" \
  -H "X-Api-Key: $KWN_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "mode": "percent",
  "percent": 50
}'

Responses

201Created

Field	Type	Description
`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, …).
Example
```
{
  "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).
Example
```
{
  "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).
Example
```
{
  "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).
Example
```
{
  "error": "Not found.",
  "code": "NOT_FOUND"
}
```

409A conflict: an externalId taken, or a change that could not be saved (EXTERNAL_ID_TAKEN, CONFLICT).

Example

{
  "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).

Example

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

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

Example

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

Cancel an order

POST/sales-orders/{id}/cancel

Needs: sales.write
Scopes: sales:write

An order with live invoices is refused. Cancelled already: alreadyDone.

Parameters

Field	Type	Description
`id`PathRequired	`string`

Code samples

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

Responses

200OK
Field Type Description
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, …).
Example
```
{
  "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).
Example
```
{
  "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).
Example
```
{
  "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).
Example
```
{
  "error": "Not found.",
  "code": "NOT_FOUND"
}
```

Field	Type	Description
`alreadyDone`	`boolean`	True when the document was already where the action takes it; nothing changed.
`document`	`object`

409A conflict: an externalId taken, or a change that could not be saved (EXTERNAL_ID_TAKEN, CONFLICT).

Example

{
  "error": "That externalId is already used by another record of this company.",
  "code": "EXTERNAL_ID_TAKEN"
}

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

Example

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

List

GET/sales-orders

Needs: sales.read
Scopes: 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.

Parameters

Field	Type	Description
`status`Query	`string`	A status, by name.
`partnerId`Query	`string`	The customer (sales) or the vendor (purchases).
`issueFrom`Query	`date`	Issued on or after this day.
`issueTo`Query	`date`	Issued on or before this day.
`number`Query	`string`
`limit`Query	`integer`	1 to 200; 50 by default.
`cursor`Query	`string`	The previous page's next.
`updatedSince`Query	`date`	Only rows changed at or after this instant.
`createdFrom`Query	`date`
`createdTo`Query	`date`
`externalId`Query	`string`	Only the row your system gave this id.

Code samples

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

Responses

200OK
Field Type Description
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, …).
Example
```
{
  "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).
Example
```
{
  "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).
Example
```
{
  "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).
Example
```
{
  "error": "Not found.",
  "code": "NOT_FOUND"
}
```

Field	Type	Description
`data`	`object[]`	The rows of this page.
`next`	`string`	The cursor of the next page, to send as ?cursor=; null on the last page.

409A conflict: an externalId taken, or a change that could not be saved (EXTERNAL_ID_TAKEN, CONFLICT).

Example

{
  "error": "That externalId is already used by another record of this company.",
  "code": "EXTERNAL_ID_TAKEN"
}

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

Example

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

Read one

GET/sales-orders/{id}

Needs: sales.read
Scopes: 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.

Parameters

Field	Type	Description
`id`PathRequired	`string`

Code samples

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

Responses

200OK

Field	Type	Description
`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, …).
Example
```
{
  "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).
Example
```
{
  "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).
Example
```
{
  "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).
Example
```
{
  "error": "Not found.",
  "code": "NOT_FOUND"
}
```

409A conflict: an externalId taken, or a change that could not be saved (EXTERNAL_ID_TAKEN, CONFLICT).

Example

{
  "error": "That externalId is already used by another record of this company.",
  "code": "EXTERNAL_ID_TAKEN"
}

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

Example

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

Print

GET/sales-orders/{id}/pdf

Needs: sales.read
Scopes: sales:read

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

Parameters

Field	Type	Description
`id`PathRequired	`string`
`lang`Query	`string`

Code samples

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

Responses

200OK
400Refused: the request or a business rule. The code says which (REQUEST_INVALID, RULE_REFUSED, …).
Example
```
{
  "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).
Example
```
{
  "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).
Example
```
{
  "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).
Example
```
{
  "error": "Not found.",
  "code": "NOT_FOUND"
}
```

409A conflict: an externalId taken, or a change that could not be saved (EXTERNAL_ID_TAKEN, CONFLICT).

Example

{
  "error": "That externalId is already used by another record of this company.",
  "code": "EXTERNAL_ID_TAKEN"
}

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

Example

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