Add Reverse Invoice with Items

POST/api/v1/reverse-invoices-with-items

Submit a reverse invoice (return) with automatic item registration. Use POST {{API_PATH}}/sales-with-items with rcptTyCd set to 'R'. When autoRegisterItems is true, each line item is registered with Kenya Revenue Authority before the return is submitted.

Requires x-api-key

http://localhost:8100/api/v1/reverse-invoices-with-items

How to Submit

Field	Type	Required	Description
transaction.rcptTyCd	string	Required	Set to 'R' for a return.
transaction.orgInvcNo	number	Required	Original invoice number being reversed.
autoRegisterItems	boolean	Optional	When true, registers line items with Kenya Revenue Authority before submitting the return.
lineItems	array	Required	Line items with itemClsCd for auto-registration.

Request

{
  "autoRegisterItems": true,
  "transaction": {
    "invcNo": "RET-2024-001",
    "orgInvcNo": 42,
    "salesDt": "20240116",
    "pmtTyCd": "09",
    "rcptTyCd": "R",
    "salesSttsCd": "02",
    "currency": "KES",
    "exchangeRate": 1,
    "destnCountryCd": "KE",
    "totTaxblAmt": 4310.34,
    "totTax": 689.66,
    "totAmt": 5000,
    "regrId": "USR01",
    "regrNm": "Admin",
    "modrId": "USR01",
    "modrNm": "Admin"
  },
  "lineItems": [
    {
      "itemClsCd": "5020230000",
      "itemCd": "SV0000000Z001",
      "itemNm": "Monthly SaaS Subscription",
      "qtyUnitCd": "U",
      "taxTyCd": "B",
      "prc": 5000,
      "qty": 1,
      "taxblAmt": 4310.34,
      "taxAmt": 689.66,
      "totAmt": 5000
    }
  ]
}

Response

{
  "success": true,
  "message": "Return submitted to Kenya Revenue Authority.",
  "data": {
    "cisInvcNo": 44,
    "intrlData": "AbCdEfGhIjKlMnOpQrStUvWxYz...",
    "rcptSign": "XxXxXxXxXxXxXxXxXxXxXxXx...",
    "sdcDateTime": "20240116110000",
    "totRcptNo": 44
  }
}

curl -X POST http://localhost:8100/api/v1/sales-with-items \\
  -H "x-api-key: YOUR_API_KEY" \\
  -H "Content-Type: application/json" \\
  -d '{
    "autoRegisterItems": true,
    "transaction": {
      "invcNo": "RET-2024-001",
      "orgInvcNo": 42,
      "salesDt": "20240116",
      "pmtTyCd": "09",
      "rcptTyCd": "R",
      "salesSttsCd": "02",
      "currency": "KES",
      "exchangeRate": 1,
      "destnCountryCd": "KE",
      "totTaxblAmt": 4310.34,
      "totTax": 689.66,
      "totAmt": 5000,
      "regrId": "USR01",
      "regrNm": "Admin",
      "modrId": "USR01",
      "modrNm": "Admin"
    },
    "lineItems": [{
      "itemClsCd": "5020230000",
      "itemCd": "SV0000000Z001",
      "itemNm": "Monthly SaaS Subscription",
      "qtyUnitCd": "U",
      "taxTyCd": "B",
      "prc": 5000,
      "qty": 1,
      "taxblAmt": 4310.34,
      "taxAmt": 689.66,
      "totAmt": 5000
    }]
  }'