eTIMS Reverse Invoices API

Manage reverse invoices (supplier-side invoice reversals) in eTIMS. Reverse invoices handle scenarios where a supplier issues a corrected or cancelled invoice that your business needs to acknowledge.

Table of Contents

1. Overview
2. Submit Reverse Invoice
3. List Reverse Invoices
4. Get Reverse Invoice
5. Authorization Types
6. Status Codes

Overview

Required Scopes

Endpoint Summary

What Is a Reverse Invoice?

A reverse invoice (also called a debit note from the supplier's perspective) is generated when:

• A supplier cancels or corrects a previously issued invoice
• KRA notifies your system of an incoming invoice reversal
• You need to record a supplier-side return/credit

Unlike credit notes (which you issue for your own sales), reverse invoices are for purchase-side corrections from suppliers.

Submit Reverse Invoice

Submit a reverse invoice to acknowledge a supplier's invoice correction.

Endpoint: POST /api/etims/reverse-invoices/submit

Required Scope: etims:write

Request Body:

Item Fields

Request:

curl -X POST \
  https://yourtenant.salami.dgl.co.ke/api/etims/reverse-invoices/submit \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "trd_invc_no": "SUP-INV-2026-001",
    "spplr_tin": "P051234567B",
    "spplr_nm": "Premium Furniture Suppliers Ltd",
    "auth_type": "IMPLICIT",
    "sales_dt": "2026-03-25",
    "remark": "Supplier corrected pricing error on original invoice",
    "items": [
      {
        "item_seq": 1,
        "item_code": "RAW001",
        "item_name": "Raw Material A",
        "quantity": 10,
        "unit_price": 800.00,
        "tax_type": "B"
      }
    ]
  }'

Response:

{
  "success": true,
  "data": {
    "id": 78,
    "invc_no": null,
    "trd_invc_no": "SUP-INV-2026-001",
    "spplr_tin": "P051234567B",
    "spplr_nm": "Premium Furniture Suppliers Ltd",
    "auth_type": "IMPLICIT",
    "total_items": 1,
    "total_taxable_amount": 6896.55,
    "total_tax_amount": 1103.45,
    "total_amount": 8000.00,
    "status": "submitted",
    "submitted_at": "2026-03-29T17:00:00Z"
  },
  "message": "Reverse invoice submitted successfully"
}

List Reverse Invoices

Retrieve all reverse invoices.

Endpoint: GET /api/etims/reverse-invoices

Required Scope: etims:read

Query Parameters:

Request:

curl -X GET \
  'https://yourtenant.salami.dgl.co.ke/api/etims/reverse-invoices?spplr_tin=P051234567B' \
  -H 'Authorization: Bearer YOUR_API_TOKEN'

Response:

{
  "success": true,
  "data": [
    {
      "id": 78,
      "trd_invc_no": "SUP-INV-2026-001",
      "spplr_tin": "P051234567B",
      "spplr_nm": "Premium Furniture Suppliers Ltd",
      "total_amount": 8000.00,
      "total_tax_amount": 1103.45,
      "auth_type": "IMPLICIT",
      "status": "submitted",
      "submitted_at": "2026-03-29T17:00:00Z"
    }
  ],
  "pagination": {
    "total": 1,
    "per_page": 50,
    "current_page": 1,
    "last_page": 1
  }
}

Get Reverse Invoice

Retrieve details of a specific reverse invoice.

Endpoint: GET /api/etims/reverse-invoices/{id}

Required Scope: etims:read

Request:

curl -X GET \
  https://yourtenant.salami.dgl.co.ke/api/etims/reverse-invoices/78 \
  -H 'Authorization: Bearer YOUR_API_TOKEN'

Response:

{
  "success": true,
  "data": {
    "id": 78,
    "invc_no": null,
    "trd_invc_no": "SUP-INV-2026-001",
    "spplr_tin": "P051234567B",
    "spplr_nm": "Premium Furniture Suppliers Ltd",
    "spplr_bhf_id": "00",
    "rcpt_ty_cd": "R",
    "pmt_ty_cd": "02",
    "auth_type": "IMPLICIT",
    "sales_dt": "2026-03-25",
    "total_items": 1,
    "tax_breakdown": {
      "A": {"taxable": 0, "tax": 0},
      "B": {"taxable": 6896.55, "tax": 1103.45},
      "C": {"taxable": 0, "tax": 0},
      "D": {"taxable": 0, "tax": 0},
      "E": {"taxable": 0, "tax": 0}
    },
    "total_taxable_amount": 6896.55,
    "total_tax_amount": 1103.45,
    "total_amount": 8000.00,
    "remark": "Supplier corrected pricing error on original invoice",
    "status": "submitted",
    "submitted_at": "2026-03-29T17:00:00Z",
    "confirmed_at": null
  }
}

Authorization Types

Reverse invoices can use two authorization modes:

IMPLICIT Authorization

• Default mode
• Reverse invoice is processed immediately
• Suitable for routine corrections and small amounts
• No additional steps required after submission

EXPLICIT Authorization

• Used for reversals requiring management approval
• Reverse invoice is submitted in pending status
• Requires a separate authorization step (through KRA system)
• Use when internal controls require two-step approval

When to use EXPLICIT:

• Reversals above a certain threshold
• Reversals from new or unverified suppliers
• When your internal policy requires dual authorization

Status Codes

Best Practices

1. Verify supplier TIN -- Ensure the supplier TIN matches the original purchase
2. Match original invoice -- Reference the correct trade invoice number
3. Use IMPLICIT for routine -- Only use EXPLICIT when policy requires it
4. Document reasons -- Always provide clear remarks for audit trail
5. Reconcile with purchases -- Update your purchase records after processing

Related Documentation

• eTIMS Credit Notes -- Your own sales reversals (seller-side)
• eTIMS Purchases -- Purchase management
• eTIMS Customers & Suppliers -- Supplier directory

Back to: eTIMS Credit Notes | eTIMS Verification