Copy page

eTIMS branch

Querying List Endpoints

Every eTIMS list endpoint (GET collections such as /api/etims/item_classifications/) takes the same set of query parameters, so you can pick out the fields you need, filter, search, and paginate. Use them rather than pulling a whole collection and trimming it on the client.

The examples below use the item classifications list, but the parameters are the same on every list endpoint.

Base URLs. Development https://api-dev.slade360edi.com/erp, Production https://api.erp.slade360.co.ke. All examples require Authorization: Bearer <access_token> (see Start Using the eTIMS API).

Field selection (sparse fieldsets)

Pass a comma-separated fields parameter and each result comes back with only those fields. Payloads shrink and responses get faster.

Code
curl --request GET \
  --url 'https://api-dev.slade360edi.com/erp/api/etims/item_classifications/?fields=classification_code,classification_name' \
  --header 'Authorization: Bearer <access_token>'

Each result then contains only the requested fields:

Code
{
  "count": 1240,
  "next": "...?page=2",
  "previous": null,
  "page_size": 15,
  "current_page": 1,
  "total_pages": 83,
  "start_index": 1,
  "end_index": 15,
  "results": [
    { "classification_code": "50131600", "classification_name": "Eggs and egg substitutes" }
  ]
}

Notes:

• fields is honoured on GET requests only. It has no effect on writes.

• List the top-level field names, comma-separated. Spaces are not required.

• An unknown field name is rejected with 400 Bad Request, and the error lists the fields you can use, so a typo shows up straight away instead of being quietly dropped:

  Code
  {
    "fields": "Unknown field(s): ['classificaton_name']. Allowed fields: ['active', 'classification_code', 'classification_name', 'created', 'id', ...]."
  }

• Omit fields to get the full representation.

Filtering

Filter on any model field with ?<field>=<value>. Text fields such as classification_name match on partial values and ignore case (contains); most other fields need an exact match.

Code
# Exact match on the KRA classification code
curl --url '.../api/etims/item_classifications/?classification_code=50131600' ...

# Partial, case-insensitive match on the name
curl --url '.../api/etims/item_classifications/?classification_name=egg' ...

Search

Use ?search= to match a term across the endpoint's searchable fields. For item classifications those are classification_name and classification_code, and a single term matches either:

Code
curl --url '.../api/etims/item_classifications/?search=egg' ...

Pagination

List responses are paginated and wrapped in an envelope with count, next, previous, page_size, current_page, total_pages, start_index, end_index, and results.

Parameter	Default	Notes
page	1	Page number to fetch.
page_size	15	Results per page. Capped at 50: larger values are clamped down to 50 rather than honoured.

Code
curl --url '.../api/etims/item_classifications/?page=2&page_size=50' ...

Why page_size looks broken. Values above 50 are clamped to 50 without an error, so a single page will never hold more than 50 records. If you are after one specific record, filter or search for it (above) rather than paging through the whole collection. To pull an entire collection, page through it with ?page=N&page_size=50 until next is null.

Combining parameters

The parameters compose. This fetches page 1 of the egg-related classifications, 50 at a time, with only the code and name in each result:

Code
curl --request GET \
  --url 'https://api-dev.slade360edi.com/erp/api/etims/item_classifications/?search=egg&fields=classification_code,classification_name&page=1&page_size=50' \
  --header 'Authorization: Bearer <access_token>'

Related

• Item Classification (KRA) lists the classification codes and the hierarchy.
• eTIMS API Reference has all the endpoints, each with an interactive "Try it".