Provider

Un proveedor de la company: repartidor (rider), shopper o prestador de servicios. Sus credenciales viven en Account (account_id); este modelo guarda el perfil operativo, ubicación, rating, disponibilidad y accesos.

Roles (`status`)

status es un bitmask; los flags booleanos derivados se definen en onInitializeBitMaskBags(). Un proveedor puede tener varios roles a la vez:

is_deliverer — reparte productos y comida.
is_shopper — hace la compra en el supermercado y se la entrega al repartidor. shopping_count es la cantidad de órdenes de compra activas que tiene.
is_service_provider — presta servicios (jardinería, limpieza, etc.); ver skills / serviceProfiles.
is_shipping_provider — encomiendas / envíos punto A → B.
is_trip_provider — traslado de personas (viajes / taxi).

Disponibilidad:

is_status_online / is_online — el proveedor está conectado. Se marca con set-online y expira a los 15 minutos (ONLINE_EXPIRATION_IN_MINUTES) salvo settings.is_active_forever.
is_status_free / is_busy — si tiene o no órdenes activas asignadas.

Score y plan financiero

score, setting_score_for_delivery y setting_score_for_shopping son el puntaje del proveedor, usado para priorizar la asignación automática de órdenes:

Campo	Tipo	Descripción
`score`	float\|null	Puntaje actual
`count`	int	Órdenes consideradas para el cálculo
`badge_idx`	int\|null	Índice de la insignia obtenida
`rank`	int\|null	Posición en el ranking
`days`	int	Ventana de días del cálculo
`is_ranked`	bool	Si el proveedor entró en el ranking

setting_financial_plan es el plan de financiamiento/comisiones del proveedor (p. ej. la compra de un vehículo a cuotas descontadas de sus pagos):

Campo	Tipo	Descripción
`name`	string	Nombre del plan
`total_amount_e2`	int	Monto total a pagar (× 100)
`grace_period_in_days`	int	Días de gracia antes de la primera cuota
`pay_frequency_in_days`	int	Cada cuántos días se cobra una cuota
`initial_payment_prc`	float	Porcentaje del pago inicial (fracción 0–1)
`initial_payment_amount_e2`	int	Monto del pago inicial (× 100)
`installments_count`	int	Cantidad de cuotas
`installments_amount_e2`	int	Monto de cada cuota (× 100)
`installments`	array	Detalle de cada cuota
`is_enabled`	bool	El plan está activo
`is_started`	bool	El plan ya comenzó a cobrarse

Accesos

accesses (ProviderAccess) define a qué Branch o Company puede atender el proveedor. Se gestiona con grant-access / revoke-access.

Configuración del proveedor (`settings`)

settings es un objeto con la configuración del proveedor. editable_settings devuelve solo las claves modificables; allowed_settings (solo super-admin) devuelve las filas ProviderSetting en crudo. Los setting_* del modelo son el acceso tipado.

Claves editables:

Clave	Tipo	Descripción
`profile_extract`	object	Extracto del perfil (`extract`, `languages`)
`payout_accounts`	array	Cuentas para recibir pagos
`is_active_forever`	bool	El proveedor no expira su estado online a los 15 min
`pos_serial`	string	Serial del POS asignado al proveedor
`rif`	string	Identificador fiscal
`invoice_address`	string	Dirección para facturación
`financial_plan`	object	Plan de financiamiento (ver arriba; solo admins)

Claves visibles (solo lectura): profile_extract, rif, score_for_delivery, score_for_shopping.

Estructura de Datos

Atributo	Tipo	Descripción
`id`	`int`
`name`	`string`	Nombre del proveedor
`display_name`	`string`	Nombre de usuario
`email`	`string`	Email
`phone`	`string`	Teléfono con prefijo internacional
`avatar_url`	`string\\|null`	URL del avatar
`status`	`int`	Bitmask de roles y disponibilidad (ver "Roles")
`rating_e2`	`int`	Rating del proveedor (× 100)
`rating_sum`	`int`	Suma de calificaciones recibidas
`rating_count`	`int`	Cantidad de calificaciones recibidas
`latitude_e6`	`int`	Última latitud conocida del proveedor (× 1e6)
`longitude_e6`	`int`	Última longitud conocida del proveedor (× 1e6)
`online_at`	`datetime\\|null`	Última vez que el proveedor se marcó online
`created_at`	`datetime\\|null`
`updated_at`	`datetime\\|null`
`deleted_at`	`datetime\\|null`
`account_id`	`int`	{@link Account} con las credenciales del proveedor
`company_id`	`int`	Company a la que pertenece el proveedor (oculto)
`is_status_free`	`bool`	BitMask (({@link self::status} & 0x1) !== 0)
`is_status_online`	`bool`	BitMask (({@link self::status} & 0x10) !== 0)
`is_service_provider`	`bool`	BitMask (({@link self::status} & 0x100) !== 0)
`is_deliverer`	`bool`	BitMask (({@link self::status} & 0x200) !== 0)
`is_shopper`	`bool`	BitMask (({@link self::status} & 0x400) !== 0)
`shopping_count`	`int`	BitMask (({@link self::status} & 0xf000) >> 12)
`is_shipping_provider`	`bool`	BitMask (({@link self::status} & 0x10000) !== 0)
`is_trip_provider`	`bool`	BitMask (({@link self::status} & 0x20000) !== 0)
`setting_profile_extract`	`string\\|null`	Extracto del perfil (clave editable `profile_extract`)
`setting_payout_accounts`	`PayoutAccount[]\\|null`	Cuentas de payout (clave editable `payout_accounts`)
`setting_is_active_forever`	`bool\\|null`	El estado online no expira a los 15 min (clave editable `is_active_forever`)
`setting_pos_serial`	`string\\|null`	Serial del POS asignado (clave editable `pos_serial`)
`setting_last_turned_online_at`	`datetime\\|null`	Última vez que el proveedor se conectó (interno)
`setting_rif`	`string\\|null`	Identificador fiscal (clave editable `rif`)
`setting_invoice_address`	`string\\|null`	Dirección de facturación (clave editable `invoice_address`)
`setting_score_for_delivery`	`ProviderScoreData\\|null`	Puntaje del proveedor para reparto
`setting_score_for_shopping`	`ProviderScoreData\\|null`	Puntaje del proveedor para compras
`setting_financial_plan`	`FinancialPlan\\|null`	Plan de financiamiento del proveedor (clave editable `financial_plan`)
`setting_financial_plan_id`	`int\\|null`	Id del plan de financiamiento
`accesses`	`ProviderAccess>`	Sucursales / companies que el proveedor puede atender
`account`	`Account`
`activeAssignments`	`OrderProvider>`	Asignaciones de órdenes activas
`activeShoppingOrders`	`Order>`	Órdenes de compra activas (rol shopper)
`admin`	`Admin`
`admin_url`	`string`
`allLogs`	`ApiLog>`
`allSettings`	`ProviderSetting>`
`allowedServices`	`GoodRequirement>`	Servicios que el proveedor está habilitado a atender
`allowed_settings`	`array`	Todas las filas de configuración en crudo (solo super-admin)
`attendedClients`	`Client>`	Clientes atendidos por el proveedor
`bids`	`Bid>`
`city_by_location`	`City\\|null`	Ciudad según su ubicación actual
`client`	`Client`
`company`	`Company`
`current_city`	`City\\|null`	Ciudad del proveedor (derivada de su actividad reciente)
`deliveryVehicles`	`DeliveryVehicle>`	Vehículos del proveedor
`editable_settings`	`array`	Configuración que el proveedor/admin puede modificar
`fleetMembers`	`FleetMember>`	Membresías de flota del proveedor
`full_name`	`string`	Nombre completo
`givenRatings`	`ClientRating>`	Calificaciones que el proveedor dio a clientes
`google_maps_url`	`string\\|null`
`is_busy`	`bool`	El proveedor tiene órdenes activas asignadas
`is_email_valid`	`bool`
`is_online`	`bool`	El proveedor está conectado (`online_at` dentro de los últimos 15 min)
`is_phone_user`	`bool`	Cuenta creada solo con teléfono
`latestCompletedDelivery`	`OrderProvider\\|null`	Última entrega completada
`logs`	`ApiLog>`
`names`	`array`	Partes del nombre
`notifications`	`Notification>`
`payments`	`Payment>`
`pendingFeeConciliations`	`PendingFeeConciliation>`
`profile_data`	`array`	Datos del perfil del proveedor para mostrar
`profileRatings`	`ProviderRating>`	Calificaciones recibidas por el proveedor
`provider`	`Provider`
`public_rating_e2`	`int`	Rating mostrado públicamente (suavizado; × 100)
`resources`	`UploadedResource>`
`score`	`array`	Puntaje del proveedor (ver "Score y plan financiero")
`serviceProfiles`	`Collection<int, ServiceProfile>`	Perfiles de servicio del proveedor
`settings`	`array`	Configuración del proveedor (ver "Configuración del proveedor")
`skills`	`ServiceSkill>`	Habilidades del proveedor para prestar servicios

{
    "id": 36,
    "name": "José Daniel Gómez Ortíz",
    "display_name": "provider_192",
    "email": "joseg@manzanares.com.ve",
    "phone": "+584147851509",
    "avatar_url": "http://127.0.0.1:8000/storage/companies/69/avatar/avatar_192_1749150879.jpg",
    "status": 67361,
    "rating_e2": 430,
    "rating_sum": 327,
    "rating_count": 76,
    "latitude_e6": 10468468,
    "longitude_e6": -64167158,
    "online_at": "2026-02-25 19:21:17",
    "created_at": "2020-04-27 21:26:00",
    "updated_at": "2026-02-25 19:21:17",
    "deleted_at": null,
    "account_id": 192,
    "is_service_provider": true,
    "is_deliverer": true,
    "is_shopper": true,
    "shopping_count": 0,
    "is_shipping_provider": true,
    "is_trip_provider": false,
    "is_online": false,
    "is_busy": false,
    "profile_data": {
        "profile_extract": null
    },
    "score": {
        "delivery_score": {
            "score": 999,
            "count": 1,
            "badge": null,
            "badge_idx": null,
            "rank": null,
            "days": 30,
            "is_ranked": false
        },
        "shopping_score": {
            "score": 999,
            "count": 1,
            "badge": null,
            "badge_idx": null,
            "rank": null,
            "days": 30,
            "is_ranked": false
        }
    }
}

Endpoints

Insertar Provider

Crear proveedor

Da de alta un Provider en la company, creando su Account. Se indican los roles y el acceso (branch o company) que tendrá.

Método	URI	Cabeceras
POST	`/companies/{companyId}/providers`	Authorization

{
    "access_type": "required|string|in:company,branch",
    "access_id": "required|integer",
    "name": "required|max:64",
    "email": "required|email:rfc,filter",
    "phone": "required",
    "status": "integer",
    "profile_data": {
        "extract": "string|max:255",
        "languages": {
            "string": true,
            "max": "255",
            "regex": "/^\w+(,\w+)*$/"
        }
    },
    "is_service_provider": "nullable|boolean",
    "is_deliverer": "nullable|boolean",
    "is_shopper": "nullable|boolean",
    "is_shipping_provider": "nullable|boolean",
    "is_trip_provider": "nullable|boolean"
}

Errores de negocio

Código	HTTP	Cuándo ocurre
`ED204`	400	El acceso indicado no pertenece a esta company.
`ER409`	409	Ya existe un proveedor con ese contacto.

Otorgar acceso al proveedor

Da al Provider acceso a una Branch o a toda la Company, para que pueda tomar sus órdenes.

Método	URI	Cabeceras
POST	`/companies/{companyId}/providers/{providerId}/grant-access`	Authorization

{
    "access_type": "required|string|in:company,branch",
    "access_id": "required|integer"
}

Errores de negocio

Código	HTTP	Cuándo ocurre
`ED204`	400	El acceso indicado no pertenece a esta company.

Listar Provider

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

Listar proveedores

Lista los Provider de la company. Filtrable por rol, estado online y ubicación.

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

{
    "access_type": "string|in:company,branch",
    "access_id": "required_with:access_type"
}

Proveedores dentro de un recuadro

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

Devuelve los Provider cuya última ubicación cae dentro del recuadro geográfico indicado (min_latitude_e6, max_latitude_e6, min_longitude_e6, max_longitude_e6). Útil para mapas de operación.

Método	URI	Cabeceras
GET	`/companies/{companyId}/providers-in-bounding-box`	Authorization

{
    "llat": "required|numeric",
    "rlat": "required|numeric",
    "llon": "required|numeric",
    "rlon": "required|numeric"
}

Listar accesos del proveedor

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

Devuelve los ProviderAccess del proveedor: a qué Branch o Company puede atender.

Método	URI	Cabeceras
GET	`/companies/{companyId}/providers/{providerId}/accesses`	Authorization

Listar Provider de Order

Listar proveedores de una orden

Devuelve los Provider asignados a la orden (shopper y/o repartidor).

Método	URI	Cabeceras
GET	`/companies/{companyId}/orders/{orderId}/providers`	Authorization

Mostrar Provider

{info} Soporta: Carga dinámica

Mostrar proveedor

Devuelve el Provider con su perfil, roles, estado online y score.

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

Estadísticas del proveedor

Devuelve métricas de desempeño del Provider: entregas, tiempos, calificaciones y ganancias en el período consultado.

Método	URI	Cabeceras
GET	`/companies/{companyId}/providers/{providerId}/statistics`	Authorization

Actualizar Provider

Actualizar proveedor

Actualiza datos del Provider: nombre, teléfono, roles (status), ubicación.

Método	URI	Cabeceras
PATCH	`/companies/{companyId}/providers/{providerId}`	Authorization

{
    "name": "max:64|person_name",
    "email": "email:rfc,filter",
    "phone": "",
    "latitude_e6": "integer|between:-90000000,90000000",
    "longitude_e6": "integer|between:-180000000,180000000",
    "status": "integer",
    "profile_data": {
        "extract": "string|max:255",
        "languages": {
            "string": true,
            "max": "255",
            "regex": "/^\w+(,\w+)*$/"
        }
    },
    "reported_at": "date",
    "is_service_provider": "nullable|boolean",
    "is_deliverer": "nullable|boolean",
    "is_shopper": "nullable|boolean",
    "is_shipping_provider": "nullable|boolean",
    "is_trip_provider": "nullable|boolean",
    "settings": {
        "profile_extract": {
            "extract": "string|max:255",
            "languages": {
                "string": true,
                "max": "255",
                "regex": "/^\w+(,\w+)*$/"
            }
        },
        "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"
            }
        ],
        "is_active_forever": "nullable|boolean",
        "pos_serial": {
            "nullable": true,
            "string": true,
            "regex": "/^LP20[2-9]\d(0[1-9]|1[0-2])\d{7}$/"
        },
        "rif": "nullable|string|regex:/^([VEJGP])-?(\d{7,15}(?:-\d)?)$/",
        "invoice_address": "nullable|string|max:255",
        "financial_plan": {
            "name": "required_with:financial_plan|string|max:80",
            "total_amount_e2": "required_with:financial_plan|integer|min:1",
            "grace_period_in_days": "nullable|integer|min:1",
            "pay_frequency_in_days": "nullable|integer|min:1",
            "initial_payment_prc": "nullable|numeric|min:0.0|max:1.0",
            "installments_count": "nullable|integer|min:1",
            "started_at": "nullable|date",
            "is_enabled": "nullable|boolean"
        }
    }
}

Eliminar Provider

Revocar acceso del proveedor

Quita al Provider el acceso a la Branch o Company indicada.

Método	URI	Cabeceras
POST	`/companies/{companyId}/providers/{providerId}/revoke-access`	Authorization

{
    "access_type": "required|string|in:company,branch",
    "access_id": "required|integer"
}

Errores de negocio

Código	HTTP	Cuándo ocurre
`ED204`	400	El acceso indicado no pertenece a esta company.

Acciones de Provider

Subir avatar del proveedor

Reemplaza avatar_url del Provider con la imagen subida (campo avatar).

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

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

Conectar proveedor

Marca el Provider como online (online_at = ahora). El estado expira a los 15 minutos salvo settings.is_active_forever. Idempotente.

Método	URI	Cabeceras
POST	`/companies/{companyId}/providers/{providerId}/set-online`	Authorization

Desconectar proveedor

Marca el Provider como offline. Idempotente.

Método	URI	Cabeceras
POST	`/companies/{companyId}/providers/{providerId}/set-offline`	Authorization

Relaciones

accesses HasMany ProviderAccess
account BelongsTo Account
activeAssignments HasMany OrderProvider
activeShoppingOrders HasMany Order
admin BelongsTo Admin
allLogs HasMany ApiLog
allowedServices HasMany GoodRequirement
attendedClients HasMany Client
bids HasMany Bid
client BelongsTo Client
company BelongsTo Company
deliveryVehicles HasMany DeliveryVehicle
fleetMembers HasMany FleetMember
givenRatings HasMany ClientRating
latestCompletedDelivery HasOne OrderProvider
logs HasMany ApiLog
payments HasMany Payment
pendingFeeConciliations HasMany PendingFeeConciliation
profileRatings HasMany ProviderRating
provider BelongsTo Provider
serviceProfiles HasMany ServiceProfile
skills HasMany ServiceSkill

Administración

Métodos de Pago

Calificaciones

Provider

Roles (status)

Score y plan financiero

Accesos

Configuración del proveedor (settings)

Estructura de Datos

Endpoints

Insertar Provider

Errores de negocio

Otorgar acceso al proveedor

Errores de negocio

Listar Provider

Proveedores dentro de un recuadro

Listar accesos del proveedor

Listar Provider de Order

Mostrar Provider

Estadísticas del proveedor

Actualizar Provider

Eliminar Provider

Revocar acceso del proveedor

Errores de negocio

Acciones de Provider

Subir avatar del proveedor

Conectar proveedor

Desconectar proveedor

Relaciones

Roles (`status`)

Configuración del proveedor (`settings`)