Admin drivers

Review and manage drivers (cisterneros): KYC, documents, status, certification, and their wallets. Paths are relative to the /api/v1 prefix; these are back-office endpoints requiring an admin token.

Requires an admin bearer token (see Admin auth). Admin only.

See Common errors.

For the list and stats, an admin only sees drivers with activity in their assigned cities. Wallet money fields are USD (*_usd).

Endpoints

The driver detail object

show, certify, kyc/approve, and kyc/reject all return the same full payload:

{
  "driver": {
    "id": 3,
    "user": {
      "id": 7,
      "name": "Carlos Rodríguez",
      "phone": "+584241001001",
      "email": "carlos@example.com",
      "created_at": "2026-05-01T09:00:00+00:00"
    },
    "status": "ACTIVE",
    "kyc_state": "APPROVED",
    "kyc_review_note": null,
    "kyc_submitted_at": "2026-05-02T10:00:00+00:00",
    "kyc_reviewed_at": "2026-05-03T11:00:00+00:00",
    "is_online": true,
    "avg_rating": 4.8,
    "total_ratings": 25,
    "completed_orders": 120,
    "total_liters_delivered": 600000,
    "available_liters": 5000,
    "current_lat": 10.49,
    "current_lng": -66.85,
    "last_location_at": "2026-06-29T12:34:00+00:00",
    "is_certified": true,
    "created_at": "2026-05-01T09:00:00+00:00"
  },
  "vehicle": { "id": 4, "plate": "ABC-123", "capacity_liters": 5000, "status": "ACTIVE" },
  "documents": [
    {
      "id": 1,
      "type": "LICENSE",
      "url": "https://…",
      "status": "APPROVED",
      "review_note": null,
      "reviewed_at": "2026-05-03T11:00:00+00:00",
      "expires_at": "2027-01-01T00:00:00+00:00",
      "is_expired": false
    }
  ],
  "wallet": {
    "balance_usd": 124.5,
    "pending_payout_usd": 0,
    "cash_debt_usd": 0,
    "cash_debt_cap_usd": 50
  },
  "payout_config": {
    "method": "PAGO_MOVIL",
    "bank_code": "0102",
    "id_number": "12345678",
    "phone": "+584241234567",
    "account_number": null,
    "account_type": null,
    "updated_at": "2026-06-01T10:00:00+00:00"
  }
}

vehicle, wallet, and payout_config are null when the driver has none.

payout_config.method is PAGO_MOVIL or BANK_TRANSFER. For PAGO_MOVIL, bank_code + id_number + phone are set and account_number + account_type are null. For BANK_TRANSFER, account_number + account_type are set.

GET /admin/drivers/stats

Counters for the dashboard cards, scoped to the admin's cities.

Response 200

{ "total_active": 12, "total_pending_review": 3, "total_suspended": 1 }

GET /admin/drivers

Page-paginated driver list (newest first). See Pagination → page-based.

Query

Response 200

{
  "items": [
    {
      "id": 3,
      "name": "Carlos Rodríguez",
      "phone": "+584241001001",
      "status": "ACTIVE",
      "kyc_state": "APPROVED",
      "is_online": true,
      "avg_rating": 4.8,
      "completed_orders": 120,
      "available_liters": 5000,
      "balance_usd": 124.5
    }
  ],
  "meta": { "total": 42, "per_page": 25, "current_page": 1, "last_page": 2 }
}

GET /admin/drivers/{driverId}

Full driver detail. See the driver detail object.

Response 200 — { "driver": { … }, "vehicle": { … }, "documents": [ … ], "wallet": { … } }.

Errors

GET /admin/drivers/{driverId}/documents

Lists the driver's KYC documents with their expiry state.

Response 200

{
  "driver_id": 3,
  "items": [
    {
      "id": 1,
      "type": "LICENSE",
      "url": "https://…",
      "approval_status": "APPROVED",
      "review_note": null,
      "reviewed_at": "2026-05-03T11:00:00+00:00",
      "expires_at": "2027-01-01T00:00:00+00:00",
      "validity_state": "vigente",
      "days_to_expire": 186
    }
  ]
}

validity_state is one of vigente, por_vencer (expires within 30 days), vencido (past expires_at), or sin_vencimiento (no expiry). days_to_expire is null when the document has no expires_at.

Errors

PATCH /admin/drivers/{driverId}/documents/{documentId}/approve

Marks a single document as approved.

Response 200

{
  "document": {
    "id": 1,
    "type": "LICENSE",
    "url": "https://…",
    "status": "APPROVED",
    "review_note": null,
    "reviewed_at": "2026-06-29T12:00:00+00:00",
    "expires_at": "2027-01-01T00:00:00+00:00"
  }
}

Errors

PATCH /admin/drivers/{driverId}/documents/{documentId}/reject

Rejects a single document with a reason.

Request body

Response 200 — same { "document": { … } } shape with status: "REJECTED" and review_note set.

Errors

PATCH /admin/drivers/{driverId}/certify

Marks the driver as certified. Returns the full driver detail object.

Response 200 — { "driver": { … }, "vehicle": { … }, "documents": [ … ], "wallet": { … } }.

Errors

PATCH /admin/drivers/{driverId}/status

Changes the driver's lifecycle status.

Request body

Response 200

{ "driver": { "id": 3, "status": "SUSPENDED" } }

Errors

POST /admin/drivers/{driverId}/kyc/approve

Approves a KYC submission. The driver must be in PENDING_REVIEW. Returns the full driver detail object.

Request body

Response 200 — { "driver": { … }, "vehicle": { … }, "documents": [ … ], "wallet": { … } } with kyc_state: "APPROVED".

Errors

POST /admin/drivers/{driverId}/kyc/reject

Rejects a KYC submission with a required reason. The driver must be in PENDING_REVIEW. Returns the full driver detail object.

Request body

Response 200 — { "driver": { … }, "vehicle": { … }, "documents": [ … ], "wallet": { … } } with kyc_state: "REJECTED".

Errors

POST /admin/drivers/{driverId}/wallet/adjust

Applies a manual credit or debit. A debit may take the balance negative, so balance_after_usd can be negative.

Request body

Response 200

{
  "transaction": {
    "id": 55,
    "type": "MANUAL_ADJUSTMENT",
    "direction": "CREDIT",
    "amount_usd": 10.0,
    "balance_after_usd": 134.5,
    "description": "credit manual: ajuste por reclamo",
    "created_at": "2026-06-29T12:00:00+00:00"
  }
}

Errors

POST /admin/drivers/{driverId}/wallet/settle-cash-debt

Settles the driver's outstanding cash debt (cashDebtUSD). mode picks the accounting: external_payment lowers only the cash debt (balance_after_usd unchanged); offset_earnings lowers the cash debt and the balance by the same amount, and requires the driver's withdrawable earnings to cover it. When amount is omitted the full outstanding debt is settled.

Request body

Response 200

{
  "transaction": {
    "id": 71,
    "type": "CASH_DEBT_PAYMENT",
    "direction": "CREDIT",
    "amount_usd": 3.6,
    "balance_after_usd": 124.5,
    "description": "Saldo de deuda en efectivo (pago externo): pagó en oficina",
    "created_at": "2026-06-29T12:00:00+00:00"
  },
  "wallet": {
    "balance_usd": 124.5,
    "cash_debt_usd": 0.0,
    "can_go_online": true
  }
}

transaction.type is CASH_DEBT_PAYMENT for external_payment (direction CREDIT) or CASH_DEBT_OFFSET for offset_earnings (direction DEBIT).

Errors

GET /admin/drivers/{driverId}/transactions

Page-paginated wallet transactions (newest first). See Pagination → page-based. A driver with no wallet returns an empty list with 200.

Query

Response 200

{
  "items": [
    {
      "id": 55,
      "type": "ORDER_EARNING",
      "direction": "CREDIT",
      "is_credit": true,
      "amount_usd": 16.24,
      "balance_after_usd": 124.5,
      "exchange_rate_amount": 540.043,
      "description": "Ganancia pedido #42",
      "order_id": 42,
      "created_at": "2026-06-29T12:00:00+00:00"
    }
  ],
  "meta": { "total": 80, "per_page": 25, "current_page": 1, "last_page": 4 }
}

exchange_rate_amount is the BCV VES rate (Bs/USD) snapshot of the related order; null for movements without an order (PAYOUT_SENT, MANUAL_ADJUSTMENT, PROMO_BONUS). PROMO_BONUS is a milestone campaign reward and PROMO_REIMBURSEMENT is the cash a client's promotional credit took off a cash order; both are CREDIT. direction is CREDIT (adds to the balance) or DEBIT (subtracts); is_credit is true exactly when direction is CREDIT.

Errors

GET /admin/drivers/{driverId}/transactions/export

Streams the filtered wallet transactions as a CSV download (Content-Type: text/csv); there is no JSON body. Accepts the same type, from, and to filters as the list. Columns: id, fecha, tipo, credito, monto_usd, saldo_despues_usd, tasa_cambio, descripcion, order_id.

Errors