Zippi Business Dashboard and Analytics API Reference

The Business Dashboard endpoints give authenticated business users a live view of their operational health, sales analytics, recent activity, and pending notifications — all scoped to their JWT-resolved business context. Every request passes through the require_business_portal guard, which reads the JWT, resolves the business scope, and injects that scope into the downstream service layer before any handler logic runs.

Authentication and the `require_business_portal` guard

All endpoints in the Business Portal are protected by the require_business_portal(module) decorator. It performs three checks in order:

JWT validation — calls get_current_user() to verify and decode the Bearer token.
Module access — looks up the caller’s role in BUSINESS_ROLE_MODULES and confirms the role is allowed to access the requested module.
Business operating check — calls assert_business_operating(scope, module, method=request.method) to ensure the business scope is active before mutating operations proceed.

If any check fails, the guard raises an HttpError with 403 Forbidden.

Role	Modules accessible
`business_owner`	dashboard, orders, products, options, branches, settlements, analytics, profile, activity, onboarding, team
`business_admin`	dashboard, orders, products, options, branches, settlements, analytics, profile, activity, onboarding, team
`business_branch_admin`	dashboard, orders, products, options, branches, analytics, activity, team
`kitchen_staff`	dashboard, orders, activity
`cashier`	dashboard, orders, settlements, analytics, activity
`waiter`	dashboard, orders, activity
`super_admin` / `platform_admin`	all modules

GET /api/v1/business/dashboard

Returns a live operational summary for the authenticated business scope. The response includes active order counts, today’s revenue totals, branch statuses, and recent high-priority events.

curl -X GET https://api.zippi.app/api/v1/business/dashboard \
  -H "Authorization: Bearer <token>"

Response 200 OK

{
  "success": true,
  "data": {
    "active_orders": 14,
    "revenue_today_centavos": 345000,
    "branches": [
      { "branch_id": "br_01", "nombre": "Sede Centro", "status": "operando" }
    ],
    "recent_activity": []
  }
}

success

boolean

Always true on a 2xx response.

data

object

Show Dashboard data object

active_orders

integer

Count of orders currently in a non-terminal state within the business scope.

revenue_today_centavos

integer

Gross revenue for the current calendar day, expressed in centavos (COP). Never a float.

branches

array

List of branch summaries, each containing branch_id, nombre, and status.

recent_activity

array

Latest audit events for the scope. Mirrors the /activity feed, limited to the most recent entries.

GET /api/v1/business/analytics

Returns aggregated sales trends and top-product rankings for the business scope. Backed by the same BusinessPortalService.dashboard() handler as /dashboard but presented with an analytics-oriented projection.

curl -X GET "https://api.zippi.app/api/v1/business/analytics?from_date=2024-01-01&to_date=2024-01-31" \
  -H "Authorization: Bearer <token>"

Required role: business_owner, business_admin, business_branch_admin, cashier, super_admin, or platform_admin (module: analytics).

GET /api/v1/business/notifications

Returns pending notifications for the authenticated business scope. Routed through the orders module permission check.

curl -X GET https://api.zippi.app/api/v1/business/notifications \
  -H "Authorization: Bearer <token>"

Response 200 OK

{
  "success": true,
  "data": [
    {
      "id": "notif_abc",
      "tipo": "order_pending",
      "mensaje": "Nuevo pedido esperando confirmación",
      "leida": false,
      "fecha": "2024-06-01T14:35:00Z"
    }
  ]
}

GET /api/v1/business/activity

Returns a paginated audit log of actions taken within the business scope. Useful for compliance review and operational traceability.

curl -X GET "https://api.zippi.app/api/v1/business/activity?page=1&page_size=50" \
  -H "Authorization: Bearer <token>"

Query parameters

page

integer

default:"1"

Page number, 1-indexed.

page_size

integer

default:"20"

Maximum records per page. Recommended maximum: 100.

POST /api/v1/business/activity

Records a custom activity entry against the authenticated business scope. Returns 201 Created.

curl -X POST https://api.zippi.app/api/v1/business/activity \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"tipo": "manual_note", "descripcion": "Stock revisado mañana"}'

tipo

string

required

Activity type identifier, e.g. manual_note, config_change.

descripcion

string

required

Human-readable description of the activity event.

metadata

object

Optional arbitrary key/value pairs to attach to the entry.

POST /api/v1/business/activity/operational

Records a structured operational activity event — typically triggered by automated processes or integrations rather than direct user action. Returns 201 Created.

curl -X POST https://api.zippi.app/api/v1/business/activity/operational \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"event": "shift_opened", "branch_id": "br_01", "actor_id": "user_99"}'

event

string

required

Canonical event name, e.g. shift_opened, branch_paused, catalog_synced.

branch_id

string

Branch scope for the event, if applicable.

actor_id

string

User ID of the actor who triggered the event.

GET /api/v1/business/profile

Returns the full profile record for the authenticated business scope, including name, business type, contact details, commission rate, contract status, and creation date.

curl -X GET https://api.zippi.app/api/v1/business/profile \
  -H "Authorization: Bearer <token>"

Response fields

id_negocio

integer

Internal primary key of the business record.

nombre

string

Business display name, up to 140 characters.

tipo_negocio

string

Business type (e.g. restaurante, tienda, farmacia).

tasa_comision

string

Zippi commission rate as a decimal string (e.g. "12.00"). This value is versioned — changes do not retroactively affect settled periods.

estado_contrato

string

Contract status: activo, suspendido, or terminado.

activo

boolean

Whether the business is currently enabled on the platform.

PUT /api/v1/business/profile

Updates the mutable fields of the business profile. Requires business_owner or business_admin.

curl -X PUT https://api.zippi.app/api/v1/business/profile \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "nombre": "La Buena Mesa",
    "telefono": "+573001234567",
    "descripcion": "Cocina casera desde 1998",
    "imagen_url": "https://cdn.zippi.app/negocios/la-buena-mesa.jpg"
  }'

nombre

string

Business display name (max 140 characters).

telefono

string

Contact phone number (max 30 characters).

string

Contact email address.

descripcion

string

Public description shown to customers.

imagen_url

string

Absolute URL to the business logo/banner image (max 500 characters).

GET /api/v1/business/onboarding/status

Returns the onboarding checklist status for the business scope. Use this to drive the setup wizard in the Business Portal frontend and to determine whether the business is ready to receive live orders.

curl -X GET https://api.zippi.app/api/v1/business/onboarding/status \
  -H "Authorization: Bearer <token>"

Response 200 OK

{
  "success": true,
  "data": {
    "profile_complete": true,
    "branch_created": true,
    "catalog_published": false,
    "payment_method_configured": false,
    "overall_complete": false
  }
}

Until overall_complete is true, the business scope may be restricted from accepting live customer orders depending on platform policy. Complete all checklist items via the corresponding API endpoints before going live.

Authentication

Marketplace & Customer

Business Portal

Operations

Zippi Business Dashboard and Analytics API Reference

Authentication and the `require_business_portal` guard

GET /api/v1/business/dashboard

GET /api/v1/business/analytics

GET /api/v1/business/notifications

GET /api/v1/business/activity

POST /api/v1/business/activity

POST /api/v1/business/activity/operational

GET /api/v1/business/profile

PUT /api/v1/business/profile

GET /api/v1/business/onboarding/status

Build docs developers (and LLMs) love

Authentication

Marketplace & Customer

Business Portal

Operations

Documentation Index

​Authentication and the require_business_portal guard

​GET /api/v1/business/dashboard

​GET /api/v1/business/analytics

​GET /api/v1/business/notifications

​GET /api/v1/business/activity

​POST /api/v1/business/activity

​POST /api/v1/business/activity/operational

​GET /api/v1/business/profile

​PUT /api/v1/business/profile

​GET /api/v1/business/onboarding/status

Build docs developers (and LLMs) love

Authentication and the `require_business_portal` guard

GET /api/v1/business/dashboard

GET /api/v1/business/analytics

GET /api/v1/business/notifications

GET /api/v1/business/activity

POST /api/v1/business/activity

POST /api/v1/business/activity/operational

GET /api/v1/business/profile

PUT /api/v1/business/profile

GET /api/v1/business/onboarding/status