API reference

Reports

The VAT 201 return and the ageing reports, with the same figures as the app.

VAT 201 return

GET/reports/vat-201

Needs: reports.read + (sales.read | purchases.read)
Scopes: 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.

Parameters

Field	Type	Description
`from`Query	`date`
`to`Query	`date`

Code samples

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

Responses

200OK
Field Type Description
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, …).
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
`from`	`date`
`to`	`date`
`output`	`object[]`
`input`	`object[]`
`net`	`object[]`
`excludedDocuments`	`integer`
`unassignedDocuments`	`integer`
`source`	`string`	LIVE (computed now) or FILED (as filed).

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

Aged receivable

GET/reports/aged-receivable

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

Parameters

Field	Type	Description
`asOf`Query	`date`

Code samples

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

Responses

200OK
Field Type Description
asOf date
buckets object[]
customers 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
`asOf`	`date`
`buckets`	`object[]`
`customers`	`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"
}

Aged payable

GET/reports/aged-payable

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

Parameters

Field	Type	Description
`asOf`Query	`date`

Code samples

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

Responses

200OK
Field Type Description
asOf date
vendors 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
`asOf`	`date`
`vendors`	`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"
}

Trial balance

GET/reports/trial-balance

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

Parameters

Field	Type	Description
`from`Query	`date`
`to`Query	`date`
`includeClosing`Query	`boolean`

Code samples

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

Responses

200OK
Field Type Description
from date
to date
rows object[]
totals 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
`from`	`date`
`to`	`date`
`rows`	`object[]`
`totals`	`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"
}