Client

Representa a un cliente o comprador de una Company. Sus credenciales viven en Account (account_id); este modelo guarda el perfil de compra, ubicación, rating y configuración.

{warning} Los atributos name, last_name, email y phone son datos personales protegidos. Solo los ven los administradores; los repartidores únicamente cuando acceden al cliente a través de una Order o un OrderProvider. Otros clientes nunca los ven.

Nombres e identificación

name / last_name — nombre y apellido reales (protegidos).
full_name — nombre completo.
names — array con las partes sueltas: [nombre1, nombre2, apellido1, apellido2].
display_name — nombre de usuario para preservar la confidencialidad del nombre real. Autogenerado; hoy no se usa en la interfaz.
uuid — id público de 7 caracteres (derivado de account_id). Se usa para referidos (settings.referral_id) e identificación del cliente. Se puede filtrar por él (?uuid= / ?uuid in).
dni — documento, normalizado a partir de settings.dni.

Ubicación

latitude_e6 / longitude_e6 — reservados (siempre 0); previstos para la vertical de Taxi.
current_city — ciudad del cliente, derivada de la última Order que hizo.

Fidelización (en construcción)

level — ClientLevel calculado por volumen y monto de compras. El cliente sube de nivel y obtiene medallas; los beneficios asociados aún no existen (roadmap).
titles — medallas / insignias obtenidas.
rating_e2 — promedio real de calificación (rating_sum / rating_count, × 100).
public_rating_e2 — valor mostrado públicamente (suavizado / con mínimo garantizado).

Configuración del cliente (`settings`)

settings es un objeto con la configuración y las estadísticas del cliente. editable_settings devuelve solo las claves que el propio cliente puede modificar (endpoint PATCH settings); allowed_settings (solo super-admin) devuelve todas las filas ClientSetting en crudo.

Claves editables por el cliente:

Clave	Tipo	Descripción
`dni`	string	Documento de identidad
`born_at`	date	Fecha de nacimiento
`gender`	string	`male` \| `female` \| `other`
`lang`	string	Idioma: `en` \| `es`
`selected_address_id`	int	ClientAddress activa para los próximos pedidos
`payout_accounts`	array	Cuentas para recibir pagos (payout)
`referral_id`	string	`uuid` (7–10 chars) del cliente que lo refirió. Solo se puede fijar una vez

Claves visibles (solo lectura, estadísticas):

Clave	Tipo	Descripción
`current_balance_e2`	int	Saldo actual del cliente (× 100)
`addresses_count`	int	Cantidad de direcciones guardadas
`transactions_count`	int	Cantidad de transacciones
`pending_invoices_count`	int	Facturas pendientes
`pending_total_e2`	int	Monto pendiente total (× 100)
`orders_per_month`	int	Órdenes por mes (promedio)
`orders_per_month_trend`	string\|null	Tendencia de `orders_per_month`
`weekly_average`	int	Gasto semanal promedio (× 100)
`average_time`	int	Tiempo promedio entre pedidos
`average_cost_e2`	int	Ticket promedio (× 100)

Los setting_* del modelo son el acceso tipado a estas mismas claves; el resto de setting_* (register_source, ridery_id, stripe_id, selected_stripe_card_id) son de uso interno.

Estructura de Datos

Atributo	Tipo	Descripción
`id`	`int`
`name`	`string`	Nombre real (protegido: solo admins / repartidor vía orden)
`display_name`	`string`	Nombre de usuario autogenerado para preservar la confidencialidad; hoy sin uso en UI
`email`	`string`	Email (protegido)
`phone`	`string`	Teléfono con prefijo internacional, ej. `+58412...` (protegido)
`avatar_url`	`string\\|null`	URL del avatar; se asigna uno por defecto al crear
`rating_e2`	`int`	Promedio real de calificación del cliente (× 100)
`rating_sum`	`int`	Suma de calificaciones recibidas
`rating_count`	`int`	Cantidad de calificaciones recibidas
`latitude_e6`	`int`	Reservado (siempre `0`); previsto para Taxi
`longitude_e6`	`int`	Reservado (siempre `0`); previsto para Taxi
`created_at`	`datetime\\|null`
`updated_at`	`datetime\\|null`
`deleted_at`	`datetime\\|null`
`account_id`	`int`	{@link Account} con las credenciales de este cliente
`company_id`	`int`	Company a la que pertenece el cliente (oculto)
`last_name`	`string\\|null`	Apellido real (protegido)
`setting_last_cart_id`	`int`
`setting_last_payment_id`	`int`
`setting_rating_updated_at`	`datetime\\|null`
`setting_facebook_user`	`array\\|null`
`setting_dni`	`string\\|null`	Documento del cliente (clave editable `dni`)
`setting_gender`	`string\\|null`	Género: `male` \| `female` \| `other` (clave editable `gender`)
`setting_born_at`	`datetime\\|null`	Fecha de nacimiento (clave editable `born_at`)
`setting_lang`	`string`	Idioma: `en` \| `es` (clave editable `lang`)
`setting_register_source`	`string\\|null`	Origen del registro (interno)
`setting_referral_id`	`string\\|null`	`uuid` de quien lo refirió (clave editable `referral_id`, se fija una sola vez)
`setting_ridery_id`	`string\\|null`	Id del cliente en Ridery (interno)
`setting_stripe_id`	`string\\|null`	Customer id en Stripe (interno)
`setting_selected_address_id`	`int\\|null`	{@link ClientAddress} activa del cliente (clave editable `selected_address_id`)
`setting_selected_stripe_card_id`	`string\\|null`	Tarjeta de Stripe seleccionada (interno)
`setting_payout_accounts`	`PayoutAccount[]\\|null`	Cuentas de payout (clave editable `payout_accounts`)
`setting_current_balance_e2`	`int`	Saldo actual del cliente (× 100)
`setting_addresses_count`	`int`	Cantidad de direcciones guardadas
`setting_transactions_count`	`int`	Cantidad de transacciones
`setting_pending_invoices_count`	`int`	Facturas pendientes
`setting_pending_total_e2`	`int`	Monto pendiente total (× 100)
`setting_orders_per_month`	`int`	Órdenes por mes (promedio)
`setting_orders_per_month_trend`	`string\\|null`	Tendencia de `orders_per_month`
`setting_weekly_average`	`int`	Gasto semanal promedio (× 100)
`setting_average_time`	`int`	Tiempo promedio entre pedidos
`setting_average_cost_e2`	`int`	Ticket promedio (× 100)
`account`	`Account`
`addresses`	`ClientAddress>`	Direcciones guardadas del cliente
`adminClients`	`AdminClient>`
`admin_url`	`string`
`allLogs`	`ApiLog>`
`allOrders`	`Order>`	Órdenes del cliente, incluidas las archivadas
`allSettings`	`ClientSetting>`
`allowed_settings`	`array`	Todas las filas de configuración en crudo (solo super-admin)
`associatedAdmins`	`Admin>`
`bids`	`Bid>`
`company`	`Company`
`current_city`	`City\\|null`	Ciudad del cliente, derivada de su última orden
`dni`	`string\\|null`	Documento normalizado (a partir de `settings.dni`)
`editable_settings`	`array`	Configuración que el cliente puede modificar (ver "Configuración del cliente")
`favorites`	`Good>`	Productos marcados como favoritos
`full_name`	`string`	Nombre completo
`givenRatings`	`ProviderRating>`	Calificaciones que el cliente dio a repartidores
`goodRatings`	`GoodRating>`	Calificaciones que el cliente dio a productos
`google_maps_url`	`string\\|null`
`is_email_valid`	`bool`
`is_phone_user`	`bool`	Cuenta creada solo con teléfono (sin email real)
`level`	`ClientLevel\\|null`	Nivel de fidelización, calculado por volumen y monto de compras
`logs`	`ApiLog>`
`mainAssociatedAdmin`	`Admin>`
`names`	`array`	Partes del nombre: `[nombre1, nombre2, apellido1, apellido2]`
`notifications`	`Notification>`
`orderedGoods`	`OrderedGood>`
`orders`	`Order>`	Órdenes activas del cliente
`payments`	`Payment>`
`phone_prefix`	`string\\|null`	Prefijo internacional del teléfono
`phone_suffix`	`string\\|null`	Teléfono sin el prefijo internacional
`profileRatings`	`ClientRating>`	Calificaciones recibidas por el cliente
`public_rating_e2`	`int`	Calificación mostrada públicamente (suavizada; × 100)
`related_coupons`	`Collection`	Cupones relacionados al cliente (solo admins)
`resources`	`UploadedResource>`
`ridery_id`	`string\\|null`
`settings`	`array`	Configuración y estadísticas del cliente (ver "Configuración del cliente")
`titles`	`Title>`	Medallas / insignias obtenidas
`uuid`	`string`	Id público de 7 caracteres (referidos e identificación)

{
    "id": 39,
    "name": "Jose Manuel Salazar",
    "display_name": "user_183",
    "email": "joses@manzanares.com.ve",
    "phone": "+584121179751",
    "avatar_url": "http://127.0.0.1:8000/storage/static/default/avatar_client.png",
    "rating_e2": 450,
    "rating_sum": 27,
    "rating_count": 6,
    "created_at": "2020-04-23 18:28:29",
    "updated_at": "2024-10-27 10:11:12",
    "deleted_at": null,
    "account_id": 183,
    "last_name": null,
    "phone_prefix": "+58",
    "phone_suffix": "4121179751",
    "dni": null,
    "uuid": "CQUQM6Z",
    "settings": {
        "current_balance_e2": 27680,
        "addresses_count": 4,
        "transactions_count": 12,
        "pending_invoices_count": 12,
        "pending_total_e2": 24557,
        "orders_per_month": 0,
        "orders_per_month_trend": null,
        "weekly_average": 0,
        "average_time": 962161,
        "average_cost_e2": 2046,
        "human_current_balance_e2": 276.8,
        "human_pending_total_e2": 245.57,
        "human_average_cost_e2": 20.46
    }
}

Endpoints

Insertar Client

Registrar cliente

Auto-registro de un comprador (endpoint público, sin autenticación). Crea la Account y el Client. Con receive_code_via (phone | email) se envía un código de confirmación y la respuesta incluye validation_token; sin él, la respuesta incluye un access_token listo para usar. Si ya existe un registro sin confirmar creado por un administrador con el mismo email/teléfono, se reutiliza y el cliente completa su registro conservando el historial de pedidos hecho por el admin.

Método	URI	Cabeceras
POST	`/companies/{companyId}/clients`	N/A

{
    "name": "required|max:64|person_name",
    "last_name": "string|max:64|person_name",
    "phone": "string|min:9",
    "password": "string",
    "email": {
        "required": true,
        "email": "rfc,filter",
        "email_check": true
    },
    "receive_code_via": "string|in:email,phone"
}

Errores de negocio

Código	HTTP	Cuándo ocurre
`EB120`	409	Ya existe una cuenta confirmada con ese email.
`EB121`	409	Ya existe una cuenta confirmada con ese teléfono.

Insertar Client de PriceList

Método	URI	Cabeceras
PUT	`/companies/{companyId}/price-lists/{priceListId}/clients/{clientId}`	Authorization

Listar Client

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

Listar clientes

Lista los Client de la company. Además de los filtros genéricos, acepta dni para filtrar por documento (settings.dni).

Método	URI	Cabeceras
GET	`/companies/{companyId}/clients`	Authorization

Listar Client de Admin

Clientes asociados a un administrador (feature no finalizada)

{warning} Corresponde a una feature abandonada: administradores de tipo "seller" que reclutaban compradores y cobraban comisión por sus compras. El desarrollo no continuó y estos endpoints no se usan.

Método	URI	Cabeceras
GET	`/companies/{companyId}/admins/{adminId}/clients`	Authorization

Listar Client de PriceList

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

Método	URI	Cabeceras
GET	`/companies/{companyId}/price-lists/{priceListId}/clients`	Authorization

Configuración editable del cliente

Devuelve las claves de Client settings que el cliente puede modificar, más gender_options con los valores válidos de gender.

Método	URI	Cabeceras
GET	`/companies/{companyId}/clients/{clientId}/settings`	Authorization

Mostrar Client

{info} Soporta: Carga dinámica

Mostrar cliente

Devuelve el Client. Para repartidores se ocultan los datos personales; para administradores se agrega related_coupons.

Método	URI	Cabeceras
GET	`/companies/{companyId}/clients/{clientId}`	Authorization

Actualizar Client

{info} Soporta: Carga dinámica

Actualizar cliente

Actualiza datos del Client. Solo los administradores pueden cambiar phone; si un cliente cambia (o reconfirma) su teléfono, se le envía un código por SMS y la respuesta incluye data_verification. push_token registra el token de notificaciones de la cuenta autenticada.

Método	URI	Cabeceras
PATCH	`/companies/{companyId}/clients/{clientId}`	Authorization

{
    "name": "max:64|person_name",
    "last_name": "max:64|person_name",
    "phone": "",
    "latitude_e6": "integer|between:-90000000,90000000",
    "longitude_e6": "integer|between:-180000000,180000000"
}

Errores de negocio

Código	HTTP	Cuándo ocurre
`EB121`	409	Otro cliente ya tiene ese teléfono verificado.

Actualizar configuración del cliente

Actualiza las claves editables de Client settings (dni, born_at, gender, lang, selected_address_id, payout_accounts, referral_id). Las claves no editables se ignoran. Devuelve la configuración editable resultante.

Método	URI	Cabeceras
PATCH	`/companies/{companyId}/clients/{clientId}/settings`	Authorization

{
    "dni": "string",
    "born_at": "date",
    "selected_address_id": "integer|exists:client_addresses,id",
    "payout_accounts": [
        {
            "type": "required_with:payout_accounts.*|string|in:national_bank_account,mobile_payment",
            "document": "required_if:type,national_bank_account|required_if:type,mobile_payment|string|regex:/^[VEJGP].{7,15}$/",
            "name": "required_if:type,national_bank_account|string",
            "account": "required_if:type,national_bank_account|string|min:20",
            "bank_name": "required_if:type,national_bank_account|string|min:3|max:64",
            "bank_code": "required_if:type,mobile_payment|string|size:4",
            "phone": "required_if:type,mobile_payment|string|max:32",
            "email": "nullable|email:rfc,filter",
            "alias": "nullable|string|max:40"
        }
    ],
    "gender": "string|in:male,female,other",
    "lang": "string|in:en,es",
    "referral_id": {
        "string": true,
        "min": "7",
        "max": "10"
    }
}

Vincular Client

Vincular Client de Admin

Asociar un cliente a un administrador (feature no finalizada)

{warning} Corresponde a una feature abandonada: administradores de tipo "seller" que reclutaban compradores y cobraban comisión por sus compras. El desarrollo no continuó y estos endpoints no se usan.

Método	URI	Cabeceras
PUT	`/companies/{companyId}/admins/{adminId}/clients/{clientId}`	Authorization

Desvincular Client

Desvincular Client de Admin

Desasociar un cliente de un administrador (feature no finalizada)

{warning} Corresponde a una feature abandonada: administradores de tipo "seller" que reclutaban compradores y cobraban comisión por sus compras. El desarrollo no continuó y estos endpoints no se usan.

Método	URI	Cabeceras
DELETE	`/companies/{companyId}/admins/{adminId}/clients/{clientId}`	Authorization

Sincronizar Client

Sincronizar Client de Admin

Sincronizar clientes de un administrador (feature no finalizada)

{warning} Corresponde a una feature abandonada: administradores de tipo "seller" que reclutaban compradores y cobraban comisión por sus compras. El desarrollo no continuó y estos endpoints no se usan.

Método	URI	Cabeceras
PUT	`/companies/{companyId}/admins/{adminId}/clients`	Authorization

[
    "integer"
]

Eliminar Client

Eliminar Client de PriceList

Método	URI	Cabeceras
DELETE	`/companies/{companyId}/price-lists/{priceListId}/clients/{clientId}`	Authorization

Acciones de Client

Mostrar mi perfil de cliente

{info} Soporta: Carga dinámica

Devuelve el Client asociado a la cuenta autenticada. Solo para cuentas de tipo cliente.

Método	URI	Cabeceras
GET	`/companies/{companyId}/clients/me`	Authorization

Subir avatar del cliente

Reemplaza avatar_url con la imagen subida (campo avatar).

Método	URI	Cabeceras
POST	`/companies/{companyId}/clients/{clientId}/upload-avatar`	Authorization

{
    "avatar": "required|image|mimes:jpeg,png,bmp|max:2048|dimensions:ratio=1/1"
}

Alta directa de cliente (administrador)

Un administrador da de alta un Client sin flujo de confirmación: la cuenta queda no verificada y con contraseña aleatoria. Si el cliente luego se auto-registra con el mismo contacto, se reutiliza este registro. Si ya existe una cuenta con ese contacto cuya confirmación aún no venció, la operación falla.

Método	URI	Cabeceras
POST	`/companies/{companyId}/admins/{adminId}/clients`	Authorization

{
    "name": "required|max:64",
    "phone": "string",
    "email": "email:rfc,filter",
    "dni": "nullable|string"
}

Errores de negocio

Código	HTTP	Cuándo ocurre
`ER007`	409	Ya existe una cuenta con ese teléfono para la company.

Configuración completa del cliente (super-admin)

Devuelve todas las filas ClientSetting en crudo. Restringido a super-admin.

Método	URI	Cabeceras
GET	`/companies/{companyId}/clients/{clientId}/allowed-settings`	Authorization

Listar clientes de un comercio

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

Lista los Client que tienen al menos una orden en la sucursal indicada.

Método	URI	Cabeceras
GET	`/companies/{companyId}/branches/{branchId}/clients`	Authorization

Relaciones

account BelongsTo Account
addresses HasMany ClientAddress
adminClients HasMany AdminClient
allLogs HasMany ApiLog
allOrders HasMany Order
associatedAdmins HasMany Admin
bids HasMany Bid
company BelongsTo Company
favorites HasMany Good
givenRatings HasMany ProviderRating
goodRatings HasMany GoodRating
level HasOne ClientLevel
logs HasMany ApiLog
mainAssociatedAdmin HasMany Admin
orderedGoods HasMany OrderedGood
orders HasMany Order
payments HasMany Payment
profileRatings HasMany ClientRating
titles HasMany Title

Administración

Métodos de Pago

Calificaciones

Client

Nombres e identificación

Ubicación

Fidelización (en construcción)

Configuración del cliente (settings)

Estructura de Datos

Endpoints

Insertar Client

Errores de negocio

Insertar Client de PriceList

Listar Client

Listar Client de Admin

Listar Client de PriceList

Configuración editable del cliente

Mostrar Client

Actualizar Client

Errores de negocio

Actualizar configuración del cliente

Vincular Client

Vincular Client de Admin

Desvincular Client

Desvincular Client de Admin

Sincronizar Client

Sincronizar Client de Admin

Eliminar Client

Eliminar Client de PriceList

Acciones de Client

Mostrar mi perfil de cliente

Subir avatar del cliente

Alta directa de cliente (administrador)

Errores de negocio

Configuración completa del cliente (super-admin)

Listar clientes de un comercio

Relaciones

Configuración del cliente (`settings`)