# API — ClickDelivery Platform V0.6.1 Mobile Production

Las rutas privadas usan `Authorization: Bearer <token>`. Las escrituras de creación de viaje admiten `Idempotency-Key`.

## Sistema y autenticación
- `GET /api/v1/health`
- `POST /api/v1/auth/login`
- `POST /api/v1/auth/logout`
- `POST /api/v1/auth/refresh` — rota refresh token móvil
- `POST /api/v1/auth/mobile/revoke` — revoca refresh token
- `GET /api/v1/me`

## Plataforma / onboarding
- `GET /api/v1/contracts/current`
- `POST /api/v1/onboarding`
- `GET /api/v1/dashboard`
- `GET /api/v1/operators`
- `POST /api/v1/operators/:id/{approve|reject|suspend|reactivate}`
- `GET/PATCH /api/v1/settings`
- `PATCH /api/v1/organizations/:id/branding`
- `GET/POST /api/v1/documents`
- `POST /api/v1/documents/:id/review`

## Mobile bootstrap y APK
- `GET /api/v1/mobile/bootstrap`
- `GET /api/v1/mobile/contract`
- `GET /api/v1/mobile/brand-assets`
- `GET /api/v1/mobile/apps` — administración
- `GET /api/v1/admin/mobile-health` — salud operativa de dispositivos, push, storage, builds e integraciones

`bootstrap` devuelve el rol de app (`administrator`, `comercio`, `delivery`, `repartidor`), package/build, features, endpoints y las rutas de los **assets originales oficiales**.


## Sincronización offline
- `GET /api/v1/mobile/sync/pull?since=<ISO>`
- `POST /api/v1/mobile/sync/push`
- `POST /api/v1/driver/locations/batch`

Las operaciones de `sync/push` requieren `client_operation_id`. Los puntos GPS en lote requieren `client_point_id`; ambos mecanismos son idempotentes.

## Dispositivos y notificaciones
- `GET /api/v1/mobile/devices`
- `POST /api/v1/mobile/devices`
- `POST /api/v1/mobile/heartbeat`
- `DELETE /api/v1/mobile/devices/:id`
- `GET /api/v1/notifications`
- `POST /api/v1/notifications/:id/read`
- `POST /api/v1/notifications/test`
- `POST /api/v1/admin/notifications`

El inbox es durable. El push físico se despacha por `push_outbox`; si no hay gateway configurado, el evento no se pierde ni afecta la transacción del viaje.

## Storage privado de evidencia

### 1. Solicitar slot
`POST /api/v1/storage/evidence/uploads`

```json
{
  "trip_id":"TRP-1",
  "stage":"delivery",
  "proof_type":"photo",
  "mime_type":"image/jpeg",
  "size_bytes":152000,
  "filename":"entrega.jpg"
}
```

### 2. Subir binario
`PUT /api/v1/storage/uploads/:upload_id`

Headers:
- `Authorization: Bearer ...`
- `X-Upload-Token: ...`
- `Content-Type: image/jpeg`
- `Content-Length: ...`

La API valida límite, MIME y firma binaria, calcula SHA-256 y crea un `private_storage_object`.

### 3. Vincular evidencia
En `verify-pickup` / `verify-delivery`:

```json
{
  "pin":"9876",
  "evidence":{"type":"photo","storage_key":"obj_xxx"}
}
```

### 4. Descargar de forma autorizada
- `GET /api/v1/storage/objects/:object_id`
- `HEAD /api/v1/storage/objects/:object_id`

No existe ruta pública directa al filesystem privado.

## Logistics Core
- `GET/PATCH /api/v1/logistics/settings`
- `GET/POST /api/v1/app-users`
- `GET/POST /api/v1/drivers`
- `GET /api/v1/drivers/nearby`
- `POST /api/v1/drivers/:id/{approve|reject|availability}`
- `POST /api/v1/drivers/:id/location`
- `GET/POST /api/v1/merchants`
- `POST /api/v1/merchants/:id/{approve|reject}`
- `GET/POST /api/v1/territories`
- `GET /api/v1/admin/dispatch`
- `GET /api/v1/admin/live-map`

## Viajes
- `GET /api/v1/trips`
- `POST /api/v1/trips`
- `POST /api/v1/trips/:id/assign`
- `POST /api/v1/trips/:id/status`
- `PATCH /api/v1/trips/:id/coordinates`
- `GET /api/v1/trips/:id/candidates`
- `POST /api/v1/trips/:id/auto-assign`
- `GET /api/v1/trips/:id/tracking`
- `GET /api/v1/trips/:id/proofs`
- `POST /api/v1/trips/:id/verify-pickup`
- `POST /api/v1/trips/:id/verify-delivery`

## APK Repartidor
- `GET /api/v1/driver/me`
- `GET /api/v1/driver/trips`
- `POST /api/v1/driver/availability`
- `POST /api/v1/driver/location`
- `POST /api/v1/driver/locations/batch`
- `POST /api/v1/driver/trips/:id/accept`
- `POST /api/v1/driver/trips/:id/reject`
- `POST /api/v1/driver/trips/:id/start-delivery`
- `GET /api/v1/driver/earnings`
- `GET /api/v1/driver/settlements`

## APK Comercio
- `GET/POST /api/v1/merchant/branches`
- `PATCH /api/v1/merchant/branches/:id`
- `GET/POST /api/v1/merchant/catalog`
- `PATCH /api/v1/merchant/catalog/:id`
- `GET /api/v1/merchant/orders`
- `PATCH /api/v1/merchant/orders/:id/status`

Estados comerciales: `pending_confirmation → confirmed → preparing → ready`; `cancelled` se permite desde estados no terminales definidos. Al entrar en `ready`, el backend crea el viaje de Logistics Core.

## APK Delivery / Cliente
- `GET /api/v1/customer/marketplace`
- `GET/POST /api/v1/customer/addresses`
- `GET/POST /api/v1/customer/orders`
- `GET /api/v1/customer/trips`
- `GET /api/v1/customer/trips/:id`

El backend obtiene precios del catálogo y calcula subtotal/total; no acepta como fuente de verdad el precio enviado por la APK.

## Liquidaciones — Administrador
- `POST /api/v1/admin/drivers/:driverId/settlements`
- `POST /api/v1/admin/settlements/:id/paid`

## Realtime SSE
- `GET /api/v1/realtime/me/stream`
- `GET /api/v1/realtime/organization/stream` — despacho/admin
- `GET /api/v1/realtime/trips/:id/stream`

Eventos: creación, asignación, aceptación/rechazo, ubicación, entrada a geocerca, pickup verificado, en camino, delivery verificado, completado/cancelado y notificación creada.

## Integraciones futuras LM Networks

Manager Pay y ChefManager AI **no están activos ni son dependencias de ClickDelivery en V0.7.2**. La API solo expone el roadmap administrativo:

- `GET /api/v1/integrations/roadmap`
- `GET /api/v1/integrations/payments` — compatibilidad de lectura; devuelve estado `future`.
- `PATCH /api/v1/integrations/payments` — bloqueado hasta una versión futura.

Los endpoints de `payment-intent` se mantienen únicamente como reserva de contrato y responden `FUTURE_INTEGRATION_NOT_RELEASED`; no intervienen en la creación de pedidos.

## Finanzas / auditoría
- `GET /api/v1/finance/charges`
- `GET /api/v1/finance/ledger`
- `GET /api/v1/audit`
- `GET /api/v1/app-builds`


## V0.7.1 — Sub-Administración, pagos directos y canales

### Sub-Administración
- `GET /api/v1/subadmin/me`
- `GET|POST /api/v1/subadmin/profiles`
- `GET /api/v1/dashboard` (interceptado y filtrado por zonas)
- `GET /api/v1/subadmin/tracking`
- `GET /api/v1/subadmin/orders/status`
- `GET /api/v1/subadmin/deliveries/status`
- `GET /api/v1/subadmin/payments/review`
- `GET /api/v1/subadmin/coupons`
- `POST /api/v1/subadmin/merchants/:id/coupons`
- `GET /api/v1/subadmin/reports/sales.xls`
- `GET /api/v1/subadmin/reports/deliveries.xls`
- `GET|POST /api/v1/subadmin/banners`
- `GET /api/v1/realtime/territories/stream`
- `GET|POST /api/v1/drivers` y `GET|POST /api/v1/merchants` se interceptan para este rol y se limitan a sus polígonos.

### Administración de Sub-Administradores
- `GET|POST /api/v1/admin/subadmins`
- `PATCH /api/v1/admin/subadmins/:id`

### Pago directo
- `GET|PATCH /api/v1/merchant/payment-profile`
- `GET /api/v1/customer/merchants/:id/payment-profile`
- `POST /api/v1/customer/orders/:id/payment-proof`
- `GET /api/v1/merchant/payment-reviews`
- `POST /api/v1/merchant/payment-reviews/:id/approve|reject`
- `GET /api/v1/admin/payment-reviews`
- `POST /api/v1/admin/merchants/:id/debt-payments` — registra pagos del comercio contra su deuda de comisión/carrera.
- `POST /api/v1/storage/generic/uploads`

### Cupones propios
- `GET|POST /api/v1/merchant/coupons`
- `PATCH /api/v1/merchant/coupons/:id`
- `POST /api/v1/customer/checkout/preflight` acepta `coupon_code`.

### Delivery Express
- `GET|POST /api/v1/merchant/delivery-express`

### WhatsApp
- `GET|PATCH /api/v1/merchant/channels`
- `GET /api/v1/merchant/whatsapp/outbox`


## V0.7.1/0.7.2 — Tarifas, despacho y liquidaciones

### Prepago de plataforma
- `POST /api/v1/customer/checkout/payment-intent`
- `GET /api/v1/customer/checkout/payment-intents/:id`
- `POST /api/v1/integrations/manager-pay/webhook`
- `POST /api/v1/integrations/chefmanager-pay/webhook`

Cuando `require_platform_payment_before_order=true` y el conector está listo, una orden con `payment_destination=platform` requiere un intento `authorized` o `paid`.

### Tarifas por territorio
- `GET|POST /api/v1/admin/territory-tariffs`
- `PATCH /api/v1/admin/territory-tariffs/:id`
- `GET /api/v1/subadmin/territory-tariffs`

Las tarifas distinguen `marketplace` y `delivery_express`.

### Despacho optimizado
- `POST /api/v1/admin/dispatch-batches/optimize`
- `POST /api/v1/subadmin/dispatch-batches/optimize`
- `POST /api/v1/admin/dispatch-batches/optimize/:planId/commit`
- `POST /api/v1/subadmin/dispatch-batches/optimize/:planId/commit`

### Liquidación automática de comercios
- `GET|PATCH /api/v1/merchant/settlement-rule`
- `GET /api/v1/admin/merchant-settlement-rules`

### Guardrail de comisión SubAdmin
`GET|POST /api/v1/admin/subadmins` y `PATCH /api/v1/admin/subadmins/:id` administran `commission_min_percent` y `commission_max_percent`. `PATCH /api/v1/subadmin/merchants/:id/commission` solo acepta valores dentro del rango.