CAI and CAI Ranges API — Fiscal Invoice Authorization

A CAI (Código de Autorización de Impresión) is a government-issued authorization code required for printing tax-compliant invoices in Honduras. In Credith, every store must have exactly one active CAI and one active CAI Range at any given time. When a new CAI is created, all previously active CAIs for that store are automatically deactivated. Each CAI owns one or more CAI Ranges, which define the numeric window (minRange–maxRange) from which sequential bill numbers are drawn. The system tracks currentNumber within the active range so that every invoice receives a unique, SAR-compliant bill number.

CAI Endpoints

Base path: /api/cais

`GET /api/cais`

Returns a paginated list of CAIs. By default, only the most recent CAI per store is returned. Pass ?history=true to retrieve the full historical list across all stores. Query parameters

limit

integer

default:"10"

Maximum number of records to return. Defaults to 10.

offset

integer

default:"0"

Number of records to skip for pagination.

history

boolean

default:"false"

When true, returns all historical CAIs. When false (default), returns only the latest CAI per store via a DISTINCT ON (store_id) query.

Response

{
  "total": 2,
  "data": [
    {
      "caiId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "governmentId": "A1B2C3-D4E5F6-G7H8I9-J0K1L2-M3N4O5-06",
      "expirationDate": "2027-06-30T00:00:00.000Z",
      "documentType": "01",
      "isActive": true,
      "storeId": "b75438e5-9ae8-4597-b95e-9889028f4737",
      "caiRanges": [ { "caiRangeId": "...", "minRange": 1, "maxRange": 50000, "currentNumber": 142, "isActive": true } ],
      "store": { "storeId": "...", "storeNumber": 1, "address": "101", "company": { "name": "Credith HN" } }
    }
  ]
}

`POST /api/cais`

Creates a new CAI together with its initial bill number range. Inside a single database transaction the server:

Deactivates all currently active CAIs for the same store.
Creates the new CAI record.
Creates the initial CaiRange child record with currentNumber = 0.

Creating a new CAI deactivates all previously active CAIs belonging to the same store. Any in-flight bill creation that reads the old active CAI will receive a 404 after this point. If you intend to renew an existing CAI rather than conflict with the active-CAI guard, set isRenewal: true.

Request body

governmentId

string

required

The official CAI code issued by SAR, e.g. "A1B2C3-D4E5F6-G7H8I9-J0K1L2-M3N4O5-06". Must be unique across all CAIs.

storeId

string (UUID)

required

UUID of the store this CAI belongs to. The store must exist.

expirationDate

string (date)

required

ISO 8601 date string for when the CAI authorization expires, e.g. "2027-06-30". Must be a future date.

range

object

required

The initial bill number range to create alongside this CAI.

Show range fields

range.minRange

integer

required

The first bill number in the range. Must be greater than the highest maxRange ever registered for this store across all CAIs (prevents overlap).

range.maxRange

integer

required

The last bill number in the range. Must be ≥ minRange.

documentType

string

default:"01"

SAR document-type code. Defaults to "01" (standard invoice). This value is embedded in the formatted bill number.

isRenewal

boolean

default:"false"

When true, skips the check that blocks creating a new CAI while one is already active. Use this when renewing an expiring CAI without an operational gap.

Example — create a CAI

curl -X POST https://your-domain.com/api/cais \
  -H "Content-Type: application/json" \
  -d '{
    "governmentId": "A1B2C3-D4E5F6-G7H8I9-J0K1L2-M3N4O5-06",
    "storeId": "b75438e5-9ae8-4597-b95e-9889028f4737",
    "expirationDate": "2027-06-30",
    "range": {
      "minRange": 1,
      "maxRange": 50000
    },
    "documentType": "01",
    "isRenewal": false
  }'

Error responses

Status	Cause
`400`	Missing/invalid fields, negative ranges, `minRange > maxRange`, duplicate `governmentId`, or `minRange` does not exceed the store’s highest recorded `maxRange`
`404`	Store not found
`409`	Store already has an active CAI and `isRenewal` was not sent as `true`

`DELETE /api/cais/:id`

Hard-deletes a CAI and all of its associated CAI Ranges inside a single transaction. The operation is blocked if any range belonging to this CAI has at least one invoice already issued against it. Path parameter

string (UUID)

required

UUID of the CAI to delete.

Error responses

Status	Cause
`400`	One or more ranges have associated bills
`404`	CAI not found

CAI Range Endpoints

Base path: /api/cai-ranges and /api/cais/:caiId/ranges A CAI Range defines a contiguous block of bill numbers (minRange to maxRange). The active range’s currentNumber counter is incremented atomically on every invoice creation. When a new range is added to an active CAI, all previous ranges for that CAI are deactivated.

Range overlap validation is enforced store-wide. The minRange of any new range must be strictly greater than the highest maxRange ever registered for that store (across all CAIs and ranges). This prevents duplicate bill numbers even after CAI renewal.

`GET /api/cai-ranges`

Returns a paginated, time-descending list of all CAI Ranges. Each record includes the parent CAI object. Query parameters

limit

integer

default:"10"

Maximum records to return.

offset

integer

default:"0"

Records to skip.

`GET /api/cais/:caiId/ranges`

Returns all CAI Ranges belonging to a specific CAI, paginated. Path parameter

caiId

string (UUID)

required

UUID of the parent CAI.

Query parameters

limit

integer

default:"10"

Maximum records to return.

offset

integer

default:"0"

Records to skip.

`GET /api/cai-ranges/:id`

Returns a single CAI Range by its UUID, including the parent CAI object. Path parameter

string (UUID)

required

UUID of the CAI Range.

`POST /api/cai-ranges`

Creates a new bill-number range under an active, non-expired CAI. On success:

All currently active ranges for the parent CAI are deactivated.
The new range is created with currentNumber = 0 and isActive = true.

Request body

caiId

string (UUID)

required

UUID of the parent CAI. Must be active and not expired.

minRange

integer

required

Starting bill number for this range. Must exceed the store’s global highest maxRange.

maxRange

integer

required

Ending bill number for this range. Must be ≥ minRange.

Error responses

Status	Cause
`400`	Invalid/negative ranges, CAI is inactive or expired, or overlap with existing store ranges
`404`	CAI not found

`PUT /api/cai-ranges/:id`

Extends the maxRange of an existing CAI Range. This is the only field that can be updated. The new value must be greater than the current maxRange. The operation is blocked if any bills have already been issued against this range. Path parameter

string (UUID)

required

UUID of the CAI Range to update.

Request body

maxRange

integer

required

The new upper bound. Must be greater than both the current maxRange and the current currentNumber.

Error responses

Status	Cause
`400`	New `maxRange` is not greater than the current value, is less than `currentNumber`, or bills already exist for this range
`404`	Range not found

`DELETE /api/cai-ranges/:id`

Hard-deletes a single CAI Range. Blocked if any bill has been issued against this range. Path parameter

string (UUID)

required

UUID of the CAI Range to delete.

Error responses

Status	Cause
`400`	Range has associated bills
`404`	Range not found

Data Models

CAI

caiId

string (UUID)

Primary key, auto-generated UUIDv4.

governmentId

string

The official CAI authorization code from SAR. Maximum 75 characters. Unique index enforced.

expirationDate

string (date-time)

Date after which the CAI is no longer valid for new invoices.

documentType

string

SAR document type. Defaults to "01" (standard invoice). Embedded in the formatted billNumberFinal.

isActive

boolean

Whether this CAI is currently the active one for its store. Only one CAI per store can be active at a time.

storeId

string (UUID)

Foreign key to the stores table.

createdAt

string (date-time)

Record creation timestamp.

deletedAt

string (date-time) | null

Soft-delete timestamp. Non-null means the record is archived.

CaiRange

caiRangeId

string (UUID)

Primary key, auto-generated UUIDv4.

caiId

string (UUID)

Foreign key linking this range to its parent CAI.

minRange

integer

Lowest bill number in this authorized range.

maxRange

integer

Highest bill number in this authorized range.

currentNumber

integer

Offset from minRange representing how many bills have been issued. The next bill number is minRange + currentNumber. Starts at 0.

isActive

boolean

Whether this is the currently active range for its parent CAI. Only one range per CAI can be active at a time.

createdAt

string (date-time)

Record creation timestamp.

deletedAt

string (date-time) | null

Soft-delete timestamp.

Overview

Users & Access

Organization

Catalog

Billing & Payments

Analytics

CAI and CAI Ranges API — Fiscal Invoice Authorization

CAI Endpoints

`GET /api/cais`

`POST /api/cais`

`DELETE /api/cais/:id`

CAI Range Endpoints

`GET /api/cai-ranges`

`GET /api/cais/:caiId/ranges`

`GET /api/cai-ranges/:id`

`POST /api/cai-ranges`

`PUT /api/cai-ranges/:id`

`DELETE /api/cai-ranges/:id`

Data Models

CAI

CaiRange

Build docs developers (and LLMs) love

Overview

Users & Access

Organization

Catalog

Billing & Payments

Analytics

Documentation Index

​CAI Endpoints

​GET /api/cais

​POST /api/cais

​DELETE /api/cais/:id

​CAI Range Endpoints

​GET /api/cai-ranges

​GET /api/cais/:caiId/ranges

​GET /api/cai-ranges/:id

​POST /api/cai-ranges

​PUT /api/cai-ranges/:id

​DELETE /api/cai-ranges/:id

​Data Models

​CAI

​CaiRange

Build docs developers (and LLMs) love

CAI Endpoints

`GET /api/cais`

`POST /api/cais`

`DELETE /api/cais/:id`

CAI Range Endpoints

`GET /api/cai-ranges`

`GET /api/cais/:caiId/ranges`

`GET /api/cai-ranges/:id`

`POST /api/cai-ranges`

`PUT /api/cai-ranges/:id`

`DELETE /api/cai-ranges/:id`

Data Models

CAI

CaiRange