Invoice Submission Workflow

The integration hooks into ERPNext's document submission lifecycle. No manual action is needed from users as the submission to Tevin happens as a background consequence of posting an invoice.

Sales Invoices

Full Workflow

User creates Sales Invoice in ERPNext
         |
         v
User clicks Submit (docstatus changes to 1)
         |
         v
ERPNext fires on_submit hook
         |
         v
TIMS app constructs payload:
  - Invoice number, date, due date
  - Customer details (name, PIN if available)
  - Line items (description, quantity, unit price)
  - VAT amounts (16% standard, exempt, zero-rated)
  - Company PIN
  - Sender ID (from TIMS Settings)
         |
         v
HTTP POST request to Tevin API Server
         |
    +---------+---------+
    |                   |
  Success             Failure
    |                   |
    v                   v
CU Number &       Integration Request
QR Code stored    marked "Failed"
on invoice        Scheduled task
Integration       queues retry
Request marked
"Completed"

What Gets Submitted

The payload sent to Tevin's API includes all fields required by KRA's TIMS specification:

• Trader information: Your company's KRA PIN, name, and address
• Invoice header: Invoice number, invoice date, currency
• Customer details: Customer name, customer PIN (if B2B and configured)
• Line items: Each item sold with its description, quantity, unit price, discount (if any), and applicable VAT type
• VAT summary: Breakdown by VAT rate i.e standard rated (16%), zero-rated (0%), and exempt
• Invoice totals: Net amount, VAT amount, gross amount

After Successful Submission

Once Tevin returns a success response:

1. The CU Number (KRA Control Unit Number) is written back to the Sales Invoice record
2. A QR Code is generated from the response data and stored against the invoice
3. The Integration Request record for this submission is marked "Completed" with the full API response stored for audit
4. The QR code will appear automatically on the invoice print format

Output on Tevins Successful Submission

Credit Notes (Returns)

When a Sales Invoice is returned and a Credit Note is created and submitted in ERPNext, the same submission flow is triggered. The credit note details are sent to Tevin, referencing the original invoice's CU Number, and KRA records the reversal in compliance with TIMS regulations.

This ensures that even reversals and adjustments are visible to KRA in real time — maintaining the integrity of your VAT return filings.