eTIMS API Reference - Sync2Books

Complete reference for the eTIMS endpoints on the Sync2Books API. All endpoints are authenticated with your API key and scoped to a company:

/companies/{companyId}/integrations/etims/…

Base URL: https://api.sync2books.com

Authentication

Send your API key in the X-API-Key header:

X-API-Key: sk_development_…    (or sk_production_…)

Optional HMAC signature

For stronger security you may sign requests. When you send signature headers, both are validated:

Header	Value
`X-Signature`	`HMAC-SHA256(clientSecret, "{METHOD}{PATH}{BODY}{TIMESTAMP}")`, hex
`X-Timestamp`	Unix time in milliseconds; must be within 5 minutes of server time

The signature is optional — if you omit both headers, the API key alone authenticates. If present, it must be valid.

Errors

Status	Meaning
`401`	Missing/invalid API key, or invalid signature
`409`	Conflict (e.g. connecting a company that’s already connected)
`429`	Rate limit exceeded (per-application, per-minute)

Conventions

Async endpoints return { "syncBatchId": "<uuid>" }. Confirm resolution via the read endpoints or dashboard sync monitoring → Tracking Results.
branchId is your branch key (e.g. HQ), set when the company was connected.
Sales/stock line items reference the item id returned by Sync2Books, not your externalId.
For valid field codes (tax category, units, packaging, payment, classification), see Codes & Values.

Endpoint summary

Method	Path	Mode	Returns
`POST`	`/companies/{companyId}/integrations/etims/catalog/items`	async	`{ syncBatchId }`
`GET`	`/companies/{companyId}/integrations/etims/catalog/items`	sync	item list
`POST`	`/companies/{companyId}/integrations/etims/catalog/items/sync`	async	`{ syncBatchId }`
`POST`	`/companies/{companyId}/integrations/etims/sales`	async	`{ syncBatchId }`
`GET`	`/companies/{companyId}/integrations/etims/sales`	sync	sales list
`GET`	`/companies/{companyId}/integrations/etims/sales/{saleId}`	sync	sale
`POST`	`/companies/{companyId}/integrations/etims/sales/credit-notes/express`	async	`{ syncBatchId }`
`POST`	`/companies/{companyId}/integrations/etims/stock/transfer`	async	`{ syncBatchId }`
`PUT`	`/companies/{companyId}/integrations/etims/stock/adjust`	async	`{ syncBatchId }`
`POST`	`/companies/{companyId}/integrations/etims/provision`	sync	connection result (advanced)

Connecting a company is normally done in the dashboard; the provision endpoint is for programmatic onboarding only. See Connecting a Company.

Catalog

Register item

POST /companies/{companyId}/integrations/etims/catalog/items

Field	Type	Required
`externalId`	string	✅
`name`	string	✅
`itemType`	`GOODS` \| `SERVICE`	✅
`taxCategory`	`VAT_STANDARD` \| `VAT_ZERO` \| `EXEMPT` \| `OTHER`	✅
`classificationCode`	string	⚠️ effectively required (KRA item classification)
`unitCode`	string	—
`packagingUnitCode`	string	—
`sku`	string	—
`internalUnit`, `taxTyCd`, `productTypeCode`	string	—

itemType determines stock behavior: GOODS are stock-tracked (sales deduct inventory), SERVICE items are non-stock (sales ignore inventory). See Goods vs Services. Returns { syncBatchId }.

List items

GET /companies/{companyId}/integrations/etims/catalog/items — returns your catalog (each item has its Sync2Books id, your externalId, and a registration status).

Sync items to eTIMS

POST /companies/{companyId}/integrations/etims/catalog/items/sync

Field	Type	Required	Default
`branchId`	string	✅
`itemIds`	string[]	—	all
`onlyPending`	boolean	—	`true`
`force`	boolean	—	`false`

Returns { syncBatchId }. Details: Catalog.

Sales

Create sale

POST /companies/{companyId}/integrations/etims/sales — query ?submit=true|false (default true).

Field	Type	Required
`branchId`	string	✅
`saleDate`	string `YYYY-MM-DD`	✅
`traderInvoiceNumber`	string	✅
`receiptTypeCode`	string	✅
`paymentTypeCode`	string	✅
`invoiceStatusCode`	string	✅
`customerTin`, `customerName`	string	—
`items`	line item[] (min 1)	✅

Line item

Field	Type	Required
`id`	string (the item `id` from Sync2Books)	✅
`quantity`	number	✅
`unitPrice`	number	✅
`taxCategory`	string	✅
`taxAmount`	number	✅
`discountRate`, `discountAmount`, `itemDescription`	—	—

Returns { syncBatchId }.

List sales

GET /companies/{companyId}/integrations/etims/sales — query: before, after, startDate, endDate, pageSize.

Get sale

GET /companies/{companyId}/integrations/etims/sales/{saleId} (saleId = the sale’s id).

Express credit note

POST /companies/{companyId}/integrations/etims/sales/credit-notes/express — query ?submit=true|false.

Field	Type	Required
`branchId`	string	✅
`saleId`	string (the accepted sale’s `id`)	✅
`traderInvoiceNumber`	string	✅
`returnDate`	string `YYYY-MM-DD`	✅
`paymentTypeCode`, `invoiceStatusCode`	string	—

Returns { syncBatchId }. Details: Sales & Credit Notes.

Stock

Adjust stock

PUT /companies/{companyId}/integrations/etims/stock/adjust

Field	Type	Required
`itemId`	string (the item `id`)	✅
`branchId`	string	✅
`quantity`	number	✅
`action`	`ADD` \| `DEDUCT`	✅
`movementTypeCode`, `referenceId`	string	—

Returns { syncBatchId }.

Transfer stock

POST /companies/{companyId}/integrations/etims/stock/transfer

Field	Type	Required
`itemId`	string	✅
`fromBranchId`	string	✅
`receivingItemId`	string	✅
`toBranchId`	string	✅
`quantity`	number	✅
`referenceId`	string	—

Returns { syncBatchId }. Details: Stock.

Connect a company (advanced)

POST /companies/{companyId}/integrations/etims/provision

Most integrations connect companies in the dashboard. Use this endpoint only for programmatic onboarding.

Field	Type	Required
`kraPin`	string (min 3)	✅
`environment`	`SANDBOX` \| `PRODUCTION`	✅
`dvcSrlNo`	string	✅
`displayName`	string	—
`sync2booksBranchKey`	string	—
`kraBhfId`	string	—

Synchronous; returns the connection result. 409 if the company is already connected. Details: Connecting a Company.

Enums

Enum	Values
`environment`	`SANDBOX`, `PRODUCTION`
`itemType`	`GOODS`, `SERVICE`
`taxCategory`	`VAT_STANDARD`, `VAT_ZERO`, `EXEMPT`, `OTHER`
stock `action`	`ADD`, `DEDUCT`

Interactive reference. The live, always-current schema is in the Sync2Books API docs at https://api.sync2books.com/api.

​Authentication

​Optional HMAC signature

​Errors

​Conventions

​Endpoint summary

​Catalog

​Register item

​List items

​Sync items to eTIMS

​Sales

​Create sale

​List sales

​Get sale

​Express credit note

​Stock

​Adjust stock

​Transfer stock

​Connect a company (advanced)

​Enums