Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/CRISTIANCAMACH34/Zippi/llms.txt

Use this file to discover all available pages before exploring further.

The Cashier API manages the full lifecycle of a cashier shift — from opening with an initial float through intra-shift cash movements, summary inspection, and final arqueo (close-out reconciliation). All monetary values are expressed as integer centavos (Colombian pesos × 100). Every endpoint is scoped to the authenticated user’s branch and enforces fine-grained RBAC permissions defined in rbac.py.

​
Permissions

PermissionDescription
cashier.readConsult the cashier overview, shift list, movements, summaries, and liquidations
cashier.reconcileOpen shifts, register the initial base, record movements, and close shifts
The cashier built-in role automatically receives both cashier.read and cashier.reconcile.

​
GET /api/v1/cashier/overview

Returns an at-a-glance summary of the current cashier state for the caller’s branch: active shift count, total cash on hand, and any pending reconciliation flags. Permission required: cashier.read 
curl -X GET https://api.zippi.co/api/v1/cashier/overview \
  -H "Authorization: Bearer <token>"

​
Response

​
success
boolean
Whether the request succeeded.
​
data
object
Overview payload with branch cashier state.

​
GET /api/v1/cashier/shifts

Returns a paginated list of cashier shifts. Optionally filter to a specific courier/cashier or restrict results to active shifts only. Permission required: cashier.read

​
Query Parameters

​
page
integer
default:"1"
Page number (1-indexed).
​
page_size
integer
default:"20"
Number of results per page.
​
courier_id
integer
Filter shifts belonging to a specific courier/cashier user ID.
​
active_only
boolean
default:"false"
When true, only returns shifts that are currently open.
curl -X GET "https://api.zippi.co/api/v1/cashier/shifts?active_only=true&page=1" \
  -H "Authorization: Bearer <token>"

​
Response

​
success
boolean
Whether the request succeeded.
​
data
object
Paginated list of shift objects.
​
data.items
array
Array of shift records.
​
data.total
integer
Total number of matching shifts.
​
data.page
integer
Current page.
​
data.page_size
integer
Page size used.

​
POST /api/v1/cashier/shifts

Opens a new cashier shift. The caller becomes the shift owner. Returns 201 Created. Permission required: cashier.reconcile

​
Body

​
initial_amount
integer
required
Opening float in centavos (e.g. 5000000 = $50,000 COP). Must be a non-negative integer.
​
note
string
Optional free-text note attached to the shift opening event.
curl -X POST https://api.zippi.co/api/v1/cashier/shifts \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "initial_amount": 5000000,
    "note": "Morning shift float"
  }'

​
Response

​
success
boolean
Always true on success.
​
data
object
Newly created shift record including shift_id, status, opened_at, and the caller’s user info.

​
GET /api/v1/cashier/shifts/

Retrieves the full detail of a single shift. Permission required: cashier.read

​
Path Parameters

​
shift_id
integer
required
The numeric ID of the shift.
curl -X GET https://api.zippi.co/api/v1/cashier/shifts/42 \
  -H "Authorization: Bearer <token>"

​
Response

​
success
boolean
Whether the request succeeded.
​
data
object
Full shift object including status, amounts, timestamps, and owner.

​
POST /api/v1/cashier/shifts//base

Registers (or updates) the initial cash base for a shift. Useful when the float is counted after opening, or corrected before the first movement. Permission required: cashier.reconcile

​
Path Parameters

​
shift_id
integer
required
ID of the target shift.

​
Body

​
amount
integer
required
Verified base amount in centavos.
​
note
string
Optional auditor note.
curl -X POST https://api.zippi.co/api/v1/cashier/shifts/42/base \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"amount": 5000000}'

​
Response

​
success
boolean
Always true on success.
​
data
object
Updated shift record.

​
GET /api/v1/cashier/shifts//movements

Lists all cash movements (income, expenses, adjustments) recorded under a shift. Permission required: cashier.read

​
Path Parameters

​
shift_id
integer
required
ID of the target shift.
curl -X GET https://api.zippi.co/api/v1/cashier/shifts/42/movements \
  -H "Authorization: Bearer <token>"

​
Response

​
success
boolean
Whether the request succeeded.
​
data
array
List of movement objects, each with type, amount (centavos), description, created_at, and the recording user.

​
POST /api/v1/cashier/shifts//movements

Records a new cash movement against an open shift. Use this to log collections, petty cash disbursements, or Wompi reconciliation entries. Permission required: cashier.reconcile

​
Path Parameters

​
shift_id
integer
required
ID of the target shift.

​
Body

​
type
string
required
Movement type. Typical values: income, expense, adjustment.
​
amount
integer
required
Movement value in centavos. Always positive — the type field determines sign.
​
description
string
Human-readable label for the movement (e.g. "Order #1023 cash collection").
​
reference_id
string
Optional external reference (order ID, payment ID, etc.).
curl -X POST https://api.zippi.co/api/v1/cashier/shifts/42/movements \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "income",
    "amount": 2500000,
    "description": "Order #1023 cash collection",
    "reference_id": "1023"
  }'

​
Response

​
success
boolean
Always true on success.
​
data
object
The newly created movement record.

​
GET /api/v1/cashier/shifts//summary

Returns a computed summary of the shift: expected cash (base + movements), total income, total expenses, and net balance. Permission required: cashier.read

​
Path Parameters

​
shift_id
integer
required
ID of the target shift.
curl -X GET https://api.zippi.co/api/v1/cashier/shifts/42/summary \
  -H "Authorization: Bearer <token>"

​
Response

​
success
boolean
Whether the request succeeded.
​
data
object
Summary with expected_cash, total_income, total_expenses, net_balance — all in centavos.

​
POST /api/v1/cashier/shifts//close

Closes a shift and records the physically counted cash amount (arqueo). The system computes the variance between expected and actual cash and stores it for reconciliation. Permission required: cashier.reconcile
Closing a shift is idempotent. If the shift is already closed, the request succeeds silently and returns the existing closed shift — it does not create a second closing entry or throw an error. Safe to call more than once (e.g. from a retry loop).

​
Path Parameters

​
shift_id
integer
required
ID of the shift to close.

​
Body

​
actual_amount
integer
required
Physically counted cash in the drawer, expressed in centavos (e.g. 6800000 = $68,000 COP).
​
note
string
Optional closing note or supervisor signature reference.
curl -X POST https://api.zippi.co/api/v1/cashier/shifts/42/close \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "actual_amount": 6800000,
    "note": "Counted by supervisor Maria G."
  }'

​
Response

​
success
boolean
Always true on success.
​
data
object
Closed shift record including status: "closed", closed_at, actual_amount, expected_amount, and variance (all in centavos).

​
GET /api/v1/cashier/shifts//liquidation

Returns the full liquidation report for a closed shift, including a breakdown of collections by payment method (cash, Wompi, other), total deliveries, and any outstanding discrepancies. Permission required: cashier.read

​
Path Parameters

​
shift_id
integer
required
ID of the (closed) shift.
curl -X GET https://api.zippi.co/api/v1/cashier/shifts/42/liquidation \
  -H "Authorization: Bearer <token>"

​
Response

​
success
boolean
Whether the request succeeded.
​
data
object
Liquidation breakdown: cash_total, wompi_total, other_total, grand_total, variance, and a line-by-line items array — all monetary values in centavos.

Build docs developers (and LLMs) love

Get started for freeTalk to us