Integrate with ICORE eTIMS
Start with a read-only request. Fiscal writes require a registered client, a correctly initialized device, and valid KRA item and tax codes.
OSCU initialization exists in the application, but OSCU invoice submission is not enabled in this release. Gateway access does not imply KRA integrator certification or production approval.
- Create a client workspace with the correct business tax PIN and device identity.
- Copy the API key and one-time secret from the client portal. Store them on your server.
- Confirm device registration and initialize it using details issued for your KRA test or production environment.
- Register your items before submitting sales. Keep the original request and receipt for reconciliation.
Authentication
API requests use Api-Key and Api-Secret headers. Each key is tied to one client taxpayer; client requests cannot query another client’s invoices. Never embed the secret in public browser code or a mobile application.
curl 'https://api.icorehost.co.ke/api/v1/items' \ -H 'Accept: application/json' \ -H 'Api-Key: YOUR_API_KEY' \ -H 'Api-Secret: YOUR_API_SECRET'
The API secret is shown when issued or rotated, not retrieved as plaintext later. Rotation invalidates the old credentials; update your connected systems at the same time.
Device identity
device_id is assigned by ICORE when a device record is created. It is a stable identifier for your POS or integration, not a value returned by KRA. Read your devices using GET /api/v1/devices.
Initialization returns device.device_id and device.initialized. A successful installation response does not need a KRA device ID. Any fiscal control_unit_id is stored separately and must not be replaced with the gateway ID on receipts.
If several devices are initialized, include device_id or device_serial_no with a sale to select the intended installation. Editing a serial keeps the gateway ID but requires fiscal reinitialization.
API resources
| Method | Path | Purpose |
|---|---|---|
| GET | /api/health | Public application liveness. This does not prove KRA connectivity. |
| GET | /api/v1/devices | Read this client’s gateway IDs and initialization states. |
| POST | /api/v1/devices/initialize | Initialize the client’s VSCU or OSCU device. |
| GET / POST | /api/v1/items | Read the client catalog / register an item. |
| GET | /api/v1/master-data/codes | Read KRA classification and reference codes. |
| GET | /api/v1/master-data/item-classifications | Read item classifications. |
| GET | /api/v1/customers/{pin} | Look up taxpayer details. |
| POST | /api/v1/sales | Submit a VSCU sale or credit note. |
| GET | /api/v1/sales/{invcNo} | Read the saved invoice state and receipt. |
| GET / POST | /api/v1/purchases | Purchase records and submissions. |
| GET / POST | /api/v1/stock/movements | Stock movement records and submissions. |
| POST | /api/v1/stock/master | Submit stock master quantities. |
| GET / PATCH | /api/v1/imports | Read imports / update an import record. |
| POST | /api/v1/adapters/webhook/{identifier} | Receive mapped payloads using the adapter’s webhook authentication. |
| GET | /api/v1/adapters/transactions | Read the client’s adapter transaction log. |
Invoices & credit notes
Submit to POST /api/v1/sales. The gateway supplies the authenticated client’s tin and initialized device’s bhfId. Do not reuse an invoice number for different sale contents.
| Field | Gateway validation |
|---|---|
invcNo | Positive integer, unique for this client. |
rcptTyCd | S for a sale; R for a credit note. |
orgInvcNo | Original invoice number, required and positive for a credit note. |
totTaxblAmt, totTaxAmt, totAmt | Non-negative numeric totals matching the original invoice and tax allocation. |
itemList | At least one item with itemCd, itemNm, qty, prc, totAmt, taxTyCd; quantity must be positive. |
These are gateway checks, not the entire KRA payload specification. Include the other required KRA transaction, tax-bucket, receipt, and item fields from the technical specification. Use the registered item and current applicable tax codes; the gateway does not determine your tax treatment.
On a successful submission, data contains rcptNo, rcptSign, intrlData, and the returned receipt fields, plus qrCodeData and invoiceVerificationUrl. The gateway saves this evidence before returning success.
Credit notes go through the same /sales endpoint, not a separate /credit-notes URL. Preserve the original invoice reference and follow KRA’s rules for issuing credit notes from the original solution.
Receipts & retries
Check GET /api/v1/sales/{invcNo} after a lost or timed-out response. A signed response can be retrieved without issuing another fiscal invoice.
| State | Meaning & action |
|---|---|
signed | A complete signed VSCU receipt is saved. Repeating unchanged contents returns the saved receipt and replayed: true. |
failed | A definitive rejection was received. Correct the rejected request before submitting the same invoice number again. |
processing | The invoice number is reserved while a request is in flight. Wait and inspect the saved state. |
unknown | The outcome could not be confirmed. Reconcile with the VSCU before any retry; the gateway blocks blind resubmission. |
journaled | Historical local journal. A missing signature is not evidence of a signed receipt. Reconcile against original records. |
Errors
| Status | Action |
|---|---|
| 401 / 403 | Check credentials and the account’s allowed workspace. |
| 409 | Device missing, duplicate contents conflict, another submission in progress, or reconciliation required. Inspect the error and saved invoice state. |
| 422 | Validation failure or definitive service rejection. Inspect errors, error, or kra_response.resultMsg. |
| 429 | Rate limit exceeded. Wait before sending another request. |
| 502 | Unconfirmed upstream outcome. Check invoice status; do not automatically issue a replacement invoice. |
KRA onboarding & certification
Integrator certification is a separate KRA process involving development, testing, vetting, and approval. This portal provides application access; it does not certify your solution or approve a production taxpayer installation.