Admin config

Platform configuration for the back office: payment-method commissions, the solidarity percentages, and support contact details. Paths are relative to the /api/v1 prefix; these are back-office endpoints that require an admin token.

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

See Common errors and the commission & solidarity rules.

Endpoints

Method	URI	Access	Description
`GET`	`/admin/config/payment-methods`	Admin	List payment methods and their commission split
`PATCH`	`/admin/config/payment-methods/{method}`	Admin	Toggle a method or set its Agüita percentage
`GET`	`/admin/config/solidary`	Admin	Current solidarity percentages
`PATCH`	`/admin/config/solidary`	Admin	Update solidarity percentages
`GET`	`/admin/config/orders`	Admin	Current order & payment expiration windows
`PATCH`	`/admin/config/orders`	Admin	Update order & payment expiration windows
`GET`	`/admin/config/support`	Admin	Current support contact config
`PATCH`	`/admin/config/support`	Admin	Update support contact config

GET /admin/config/payment-methods

Lists the payment-method catalogue (ordered by sort order, then code) with the commission split. driver_gross_pct is the driver's share of the payment.

Response 200

{
  "methods": [
    {
      "method": "CASH_USD",
      "active": true,
      "label": "Efectivo (USD)",
      "aguita_pct": 18.0,
      "driver_gross_pct": 82.0,
      "commission_tiers": [
        { "min_amount": 0, "max_amount": 20, "aguita_prc": 15 }
      ]
    }
  ]
}

commission_tiers is null when the method has no tiers. When present, it is a list of { min_amount, max_amount|null, aguita_prc } (amounts in USD).

PATCH /admin/config/payment-methods/{method}

Updates a single method by code (case-insensitive — the panel sends slugs like cash_usd). You cannot disable the last remaining active method.

Request body

Field	Type	Required	Rules
`active`	boolean	no	enable/disable the method
`aguita_pct`	number	no	0–50 (the platform's commission percentage)
`commission_tiers`	array\|null	no	optional commission tiers; `null` clears them
`commission_tiers[].min_amount`	number	yes (per item)	≥ 0 (USD)
`commission_tiers[].max_amount`	number\|null	yes (per item)	≥ 0 and > `min_amount`; `null` = open-ended
`commission_tiers[].aguita_prc`	number	yes (per item)	0–50

Response 200 — { "methods": [ … ] } (the full updated list).

Errors

Status	Body	When
`404`	`{ "error": "InvalidPaymentMethod" }`	Unknown method code
`422`	`{ "error": "AtLeastOneMethodRequired", "message": "…" }`	Disabling the last active method
`422`	`{ "error": "ValidationError", "details": { "fieldErrors": { … } } }`	A tier is malformed, out of range, or tiers overlap

GET /admin/config/solidary

Returns the solidarity percentages.

Response 200

{ "solidary": { "client_solidary_pct": 1.0, "driver_solidary_pct": 1.0 } }

PATCH /admin/config/solidary

Updates the solidarity percentages (merge — only the fields you send change).

Request body

Field	Type	Required	Rules
`client_solidary_pct`	number	no	0–20
`driver_solidary_pct`	number	no	0–20

Response 200

{ "solidary": { "client_solidary_pct": 1.5, "driver_solidary_pct": 1.0 } }

GET /admin/config/orders

Returns the expiration windows, in minutes, for the order acceptance phase and the payment phase.

Response 200

{ "orders": { "order_expiry_minutes": 5, "payment_expiry_minutes": 15 } }

PATCH /admin/config/orders

Updates the expiration windows (merge — only the fields you send change).

Request body

Field	Type	Required	Rules
`order_expiry_minutes`	integer	no	1–120
`payment_expiry_minutes`	integer	no	1–120

Response 200

{ "orders": { "order_expiry_minutes": 5, "payment_expiry_minutes": 20 } }

Errors

Status	Body	When
`422`	`{ "error": "ValidationError", "details": { "fieldErrors": { … } } }`	A value is not an integer, < 1, or > 120

GET /admin/config/support

Returns the support contact configuration.

Response 200

{
  "support": {
    "phone": "+584121234567",
    "schedule": "Lunes a Viernes 8am–6pm",
    "off_hours_message": "Estamos fuera de horario, te atenderemos pronto."
  }
}

PATCH /admin/config/support

Updates the support contact config (merge — only the non-null fields you send change).

Request body

Field	Type	Required	Rules
`phone`	string	no	≤ 20 chars, matches `^\+?[0-9\s\-]{7,20}$`
`schedule`	string	no	≤ 200 chars
`off_hours_message`	string	no	≤ 500 chars

Response 200 — { "support": { … } } (the merged config).