الفواتير

إنشاء مسودة فاتورة

POST/invoices

يتطلب

sales.write

النطاقات

sales:write

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

A draft invoice for a customer of this company (customerId). Approve and issue it to send it for clearance. Requires Idempotency-Key.

المعاملات

جسم الطلب

أمثلة برمجية

curl -sS -X POST "https://app.kwn.tax/api/v1/invoices" \
  -H "X-Api-Key: $KWN_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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
    }
  ]
}'

الاستجابات

• 201Created

  الحقل	النوع	الوصف
  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"
  }

• 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/invoices

يتطلب

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.

المعاملات

أمثلة برمجية

curl -sS -X GET "https://app.kwn.tax/api/v1/invoices" \
  -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"
  }

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

  مثالنسخ

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

إشعار دائن لفاتورة مخلّصة

POST/invoices/{id}/credit-notes

يتطلب

sales.write

النطاقات

sales:write

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

A draft credit note against a cleared invoice, with its reason. Issue it like an invoice. Requires Idempotency-Key.

المعاملات

جسم الطلب

أمثلة برمجية

curl -sS -X POST "https://app.kwn.tax/api/v1/invoices/<id>/credit-notes" \
  -H "X-Api-Key: $KWN_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "reason": "Two chairs returned unused.",
  "date": "2026-10-20"
}'

الاستجابات

• 201Created

  الحقل	النوع	الوصف
  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"
  }

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

تعديل مسودة

PUT/invoices/{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).

المعاملات

جسم الطلب

أمثلة برمجية

curl -sS -X PUT "https://app.kwn.tax/api/v1/invoices/<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/invoices/{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.

المعاملات

أمثلة برمجية

curl -sS -X GET "https://app.kwn.tax/api/v1/invoices/<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/invoices/{id}/request-approval

يتطلب

sales.write

النطاقات

sales:write

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

المعاملات

أمثلة برمجية

curl -sS -X POST "https://app.kwn.tax/api/v1/invoices/<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"
  }

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

  مثالنسخ

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

الاعتماد للإصدار

POST/invoices/{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.

المعاملات

أمثلة برمجية

curl -sS -X POST "https://app.kwn.tax/api/v1/invoices/<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"
  }

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

  مثالنسخ

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

الإصدار والإرسال للتخليص

POST/invoices/{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.

المعاملات

أمثلة برمجية

curl -sS -X POST "https://app.kwn.tax/api/v1/invoices/<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"
  }

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

  مثالنسخ

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

إلغاء

POST/invoices/{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.

المعاملات

أمثلة برمجية

curl -sS -X POST "https://app.kwn.tax/api/v1/invoices/<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"
  }

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

  مثالنسخ

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

الإرجاع إلى مسودة

POST/invoices/{id}/reset-to-draft

يتطلب

sales.write

النطاقات

sales:write

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

المعاملات

أمثلة برمجية

curl -sS -X POST "https://app.kwn.tax/api/v1/invoices/<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"
  }

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

  مثالنسخ

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

حالة التخليص

GET/invoices/{id}/clearance

يتطلب

sales.read

النطاقات

sales:read

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

المعاملات

أمثلة برمجية

curl -sS -X GET "https://app.kwn.tax/api/v1/invoices/<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/invoices/{id}/clearance/retry

يتطلب

sales.write

النطاقات

sales:write

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

المعاملات

أمثلة برمجية

curl -sS -X POST "https://app.kwn.tax/api/v1/invoices/<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/invoices/{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.

المعاملات

أمثلة برمجية

curl -sS -X POST "https://app.kwn.tax/api/v1/invoices/<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/invoices/{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.

المعاملات

أمثلة برمجية

curl -sS -X GET "https://app.kwn.tax/api/v1/invoices/<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"
  }