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 Reports API provides access to Zippi’s operational and financial analytics. Summary data is returned as structured JSON; the export endpoint streams a downloadable CSV file directly to the caller. Both endpoints accept the same date-range and view-scope parameters so that a UI can show a live table and offer a matching download without re-querying different logic.
All monetary values returned by report endpoints — totals, revenues, fees, settlements, and variances — are expressed as integer centavos (Colombian pesos × 100). Divide by 100 before displaying currency in the UI.

​
Permissions

PermissionDescription
reports.readQuery and view operational and financial report data
reports.exportDownload reports as CSV files
Both permissions are included in the cashier, finance_admin, city_admin, country_admin, business_owner, business_admin, and business_branch_admin roles.

​
GET /api/v1/reports/summary

Returns an aggregated operational and financial summary for the given time window. The view parameter allows callers to scope the summary to a specific operational lens (e.g. orders, revenue, couriers). Permission required: reports.read

​
Query Parameters

​
start_date
string
ISO 8601 date (YYYY-MM-DD) — start of the reporting window (inclusive). If omitted, the service applies a default lookback (typically the current calendar month).
​
end_date
string
ISO 8601 date (YYYY-MM-DD) — end of the reporting window (inclusive). Defaults to today.
​
view
string
Scope filter for the summary. Controls which metric groups are included in the response. Typical values: orders, revenue, couriers, cashier. When omitted, a full cross-domain summary is returned.
curl -X GET "https://api.zippi.co/api/v1/reports/summary?start_date=2024-01-01&end_date=2024-01-31&view=orders" \
  -H "Authorization: Bearer <token>"

​
Response

​
success
boolean
Whether the request succeeded.
​
data
object
Summary payload. Structure varies by view; the full summary includes all groups.
​
data.orders
object
Order metrics — total count, completed, cancelled, and failed counts; average delivery time in seconds.
​
data.revenue
object
Revenue metrics — gross_revenue, service_fees, net_revenue, all in centavos.
​
data.couriers
object
Courier performance metrics — active courier count, total deliveries, average deliveries per courier.
​
data.cashier
object
Cashier metrics — total collections by method (cash, Wompi, other), total variance across closed shifts — all in centavos.
​
data.period
object
Echoes back the resolved start_date and end_date used for the query.
{
  "success": true,
  "data": {
    "period": {
      "start_date": "2024-01-01",
      "end_date": "2024-01-31"
    },
    "orders": {
      "total": 312,
      "completed": 289,
      "cancelled": 18,
      "failed": 5,
      "avg_delivery_seconds": 1840
    },
    "revenue": {
      "gross_revenue": 156000000,
      "service_fees": 12480000,
      "net_revenue": 143520000
    },
    "couriers": {
      "active_count": 14,
      "total_deliveries": 289,
      "avg_deliveries_per_courier": 20
    },
    "cashier": {
      "cash_collected": 62400000,
      "wompi_collected": 93600000,
      "other_collected": 0,
      "total_variance": -50000
    }
  }
}

​
GET /api/v1/reports/summary/export

Streams the same summary data as a UTF-8 encoded CSV file. The filename is generated by the service and returned in the Content-Disposition header. Accepts the same query parameters as GET /api/v1/reports/summary. Permission required: reports.export

​
Query Parameters

​
start_date
string
ISO 8601 date (YYYY-MM-DD) — start of the reporting window (inclusive).
​
end_date
string
ISO 8601 date (YYYY-MM-DD) — end of the reporting window (inclusive).
​
view
string
Scope filter controlling which metric groups are included in the CSV export. Same values as the JSON summary endpoint.
curl -X GET "https://api.zippi.co/api/v1/reports/summary/export?start_date=2024-01-01&end_date=2024-01-31" \
  -H "Authorization: Bearer <token>" \
  --output "zippi_summary_january_2024.csv"

​
Response Headers

HeaderValue
Content-Typetext/csv; charset=utf-8
Content-Dispositionattachment; filename="<generated_filename>.csv"
The response body is a raw CSV stream. Each row represents one metric. All monetary columns contain integer centavos — remember to format them as currency (÷ 100) when opening in spreadsheet software.
The export filename is server-generated based on the report scope and date range (e.g. zippi_summary_2024-01-01_2024-01-31.csv). It is safe to use directly as a save-as filename.

Build docs developers (and LLMs) love

Get started for freeTalk to us