City

Ciudad: agrupación geográfica dentro de un Country. Fija un centro (latitude_e6/longitude_e6), si es seleccionable por los usuarios (is_visible) y un teléfono de soporte propio.

Propósito

  • Los comercios y repartidores se asignan a una ciudad (por cercanía al centro o por geocerca). find-by-location devuelve la ciudad visible más cercana a unas coordenadas dentro de un radio.
  • Es un "balance owner": tiene su propio monedero (balance_e2 y derivados, en la moneda setting_wallet_currency_iso o la de la compañía) y wallet_debts resume lo que la zona debe (órdenes de comercios, facturas pendientes, saldos de clientes y repartidores).
  • Se le enlazan geocercas (LinkedGeofence) para delimitar su cobertura.

Notas y gotchas

  • No tiene timestamps.
  • code se autogenera a partir del boundary geográfico; no se edita directamente.
  • support_phone cae al contact_phone_whatsapp de la compañía si no tiene valor propio.

Estructura de Datos

Atributo Tipo Descripción
id int
name string Nombre de la ciudad.
code string Código de la ciudad (autogenerado desde el boundary); único por país.
country_id int País al que pertenece la ciudad.
latitude_e6 int Latitud del centro de la ciudad (grados × 1e6).
longitude_e6 int Longitud del centro de la ciudad (grados × 1e6).
is_visible bool true si la ciudad puede seleccionarse; los no administradores sólo ven las visibles.
support_phone string Teléfono de soporte de la ciudad; cae al de la compañía si está vacío.
setting_wallet_currency_iso string\|null ISO de la moneda del monedero de la ciudad; null usa la de la compañía.
activeBalanceModifiers BalanceModifier> Modificadores de saldo promocional vigentes del monedero de la ciudad.
allLogs ApiLog> Registros de auditoría de la API, incluidos los internos.
allSettings CitySetting> Todos los ajustes de la ciudad.
allowed_settings array Claves de ajuste visibles para el rol actual.
available_balance_e2 int Saldo disponible del monedero de la ciudad (céntimos).
available_for_withdrawal_balance_e2 int Saldo disponible para retiro (céntimos).
balance_e2 int Saldo total del monedero de la ciudad (céntimos).
balanceModifiers BalanceModifier> Modificadores de saldo promocional del monedero de la ciudad.
balanceMovements BalanceMovement> Movimientos del monedero de la ciudad.
country Country País al que pertenece la ciudad.
editable_settings array Claves de ajuste editables por el rol actual.
geofences BranchGeofence> Geocercas asociadas a la ciudad.
google_maps_url string\|null Enlace a Google Maps del centro de la ciudad.
lastBalanceMovement BalanceMovement\|null Último movimiento del monedero de la ciudad.
linkedGeofences LinkedGeofence> Geocercas enlazadas que delimitan la cobertura de la ciudad.
locked_for_withdrawal_balance_e2 int Saldo bloqueado para retiro (céntimos).
logs ApiLog> Registros de auditoría de la API visibles.
settings array Ajustes de la ciudad visibles para el rol actual.
wallet_debts array Resumen de deudas de la zona (órdenes, facturas y saldos de clientes/repartidores). 
{
    "id": 16,
    "name": "Turmero",
    "code": "CB_00001710",
    "country_id": 15,
    "latitude_e6": 10221718,
    "longitude_e6": -67486580,
    "is_visible": true,
    "support_phone": "584141942279"
}

Endpoints

Insertar City

Crear una ciudad

Crea una City en el país indicado (name, centro latitude_e6/ longitude_e6, is_visible, support_phone).

Método URI Cabeceras
POST /companies/{companyId}/cities Authorization 
{
    "name": "required|string|min:2|max:128",
    "latitude_e6": "required|integer|between:-90000000,90000000",
    "longitude_e6": "required|integer|between:-180000000,180000000",
    "country_id": "required|integer",
    "support_phone": "nullable|string|max:32"
}

Listar City

{info} Soporta: Paginación Filters Carga dinámica

Listar ciudades

Devuelve las City de la compañía, paginadas. Los usuarios no administradores sólo ven las que tienen is_visible = true.

Método URI Cabeceras
GET /companies/{companyId}/cities N/A

Mostrar City

{info} Soporta: Carga dinámica

Ver una ciudad

Devuelve la City indicada.

Método URI Cabeceras
GET /companies/{companyId}/cities/{cityId} N/A

Actualizar City

Actualizar una ciudad

Modifica la City indicada. Cambiar el país exige permiso sobre el país destino.

Método URI Cabeceras
PATCH /companies/{companyId}/cities/{cityId} Authorization 
{
    "name": "string|min:2|max:128",
    "latitude_e6": "integer|between:-90000000,90000000",
    "longitude_e6": "integer|between:-180000000,180000000",
    "country_id": "integer",
    "is_visible": "boolean",
    "support_phone": "nullable|string|max:32"
}

Eliminar City

Eliminar una ciudad

Borra la City indicada.

Método URI Cabeceras
DELETE /companies/{companyId}/cities/{cityId} Authorization

Acciones de City

Buscar la ciudad por ubicación

{info} Soporta: Carga dinámica

Devuelve la City visible más cercana a las coordenadas dadas dentro del radio distance (metros, por defecto 25000); null si ninguna cae en el radio.

Método URI Cabeceras
GET /companies/{companyId}/cities/find-by-location N/A 
{
    "latitude_e6": "required|integer|between:-90000000,90000000",
    "longitude_e6": "required|integer|between:-180000000,180000000",
    "distance": "integer|min:10000"
}

Relaciones