ServiceSupplier

Un proveedor de servicios (típicamente una empresa de flotas) que pertenece a un owner (una Company o una Branch). Agrupa las Fleet y, a través de ellas, las FleetAssociation. Tiene identidad visible (public_name, logo_url, color) además de un internal_name.

Ciclo de vida y estados

  • submit — marca submitted_at; requiere public_name.
  • approve — marca approved_at; requiere estar enviado y con public_name.
  • refuse — limpia submitted_at (vuelve a borrador).
  • set-enabled / set-disabled — controlan is_enabled, de forma independiente al flujo de aprobación.
  • Un proveedor aprobado (approved_at no nulo) queda disponible como "adjuntable" para cualquier company o branch, no solo para su owner.

Notas y gotchas

  • No se puede eliminar si tiene flotas (ES009).
  • owner_type / owner_id están en $hidden.
  • "Adjuntable a" un destino = los proveedores propios de ese destino más todos los aprobados.

Estructura de Datos

Atributo Tipo Descripción
id int
internal_name string Nombre interno (no visible al público)
public_name string\|null Nombre público del proveedor
is_enabled bool Si el proveedor está activo
submitted_at datetime\|null Momento de envío a revisión (null si no enviado)
approved_at datetime\|null Momento de aprobación (null si no aprobado)
owner_type string Tipo del dueño polimórfico (Company o Branch); oculto
owner_id int Id del dueño; oculto
created_at datetime\|null
updated_at datetime\|null
logo_url string URL del logo del proveedor
color string\|null Color de marca del proveedor
allLogs ApiLog>
fleetAssociations FleetAssociation> Asociaciones de flota del proveedor (a través de sus flotas)
fleets Fleet> Flotas del proveedor
logs ApiLog>
owner Model\|Eloquent Dueño del proveedor (Company o Branch)
resources UploadedResource> Archivos subidos del proveedor (logo) 
{
    "id": 1,
    "internal_name": "Delivery Global",
    "public_name": "Simgulary",
    "is_enabled": true,
    "submitted_at": null,
    "approved_at": null,
    "created_at": "2023-07-07 13:36:34",
    "updated_at": "2025-04-02 14:56:16",
    "logo_url": "http://127.0.0.1:8000/storage/static/default/branch_logo.png",
    "color": null
}

Endpoints

Listar ServiceSupplier

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

Listar proveedores de servicio

Listado paginado global de ServiceSupplier (uso administrativo).

Método URI Cabeceras
GET /service-suppliers Authorization

Mostrar ServiceSupplier

{info} Soporta: Carga dinámica

Mostrar proveedor de servicio

Devuelve el ServiceSupplier por su id.

Método URI Cabeceras
GET /service-suppliers/{serviceSupplierId} N/A

Actualizar ServiceSupplier

Actualizar proveedor de servicio

Modifica internal_name, public_name y color del ServiceSupplier. Si ya está enviado a revisión, public_name no puede quedar vacío.

Método URI Cabeceras
PATCH /service-suppliers/{serviceSupplierId} Authorization 
{
    "internal_name": "string|max:64",
    "public_name": "string|max:32",
    "color": "nullable|string|regex:/^#[0-9a-fA-F]{6}$/"
}

Errores de negocio

Código HTTP Cuándo ocurre
ES003 400 Falta public_name (con el proveedor ya enviado a revisión).

Eliminar ServiceSupplier

Eliminar proveedor de servicio

Borra el ServiceSupplier.

Método URI Cabeceras
DELETE /service-suppliers/{serviceSupplierId} Authorization

Errores de negocio

Código HTTP Cuándo ocurre
ES009 400 El proveedor tiene flotas asociadas.

Acciones de ServiceSupplier

Proveedores asociados a la compañía

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

ServiceSupplier que ya tienen al menos una FleetAssociation con la Company.

Método URI Cabeceras
GET /companies/{companyId}/service-suppliers N/A

Proveedores asociados a la sucursal

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

Igual que el listado de asociados de la compañía, para la Branch.

Método URI Cabeceras
GET /branches/{branchId}/service-suppliers N/A

Proveedores adjuntables a la compañía

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

ServiceSupplier que la Company puede adjuntar: los suyos propios más todos los aprobados. Con owning se limita a los propios.

Método URI Cabeceras
GET /companies/{companyId}/service-suppliers/allowed Authorization

Proveedores adjuntables a la sucursal

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

Igual que el listado adjuntable de la compañía, para la Branch (incluye los de su company).

Método URI Cabeceras
GET /branches/{branchId}/service-suppliers/allowed Authorization

Crear proveedor de servicio para una compañía

Crea un ServiceSupplier con la Company como owner. Nace deshabilitado y sin enviar a revisión.

Método URI Cabeceras
POST /companies/{companyId}/service-suppliers Authorization 
{
    "internal_name": "required|string|max:64",
    "public_name": "nullable|string|max:32",
    "color": "nullable|string|regex:/^#[0-9a-fA-F]{6}$/"
}

Crear proveedor de servicio para una sucursal

Igual que la versión para compañía, pero con la Branch como owner.

Método URI Cabeceras
POST /branches/{branchId}/service-suppliers Authorization 
{
    "internal_name": "required|string|max:64",
    "public_name": "nullable|string|max:32",
    "color": "nullable|string|regex:/^#[0-9a-fA-F]{6}$/"
}

Subir logo del proveedor de servicio

Sube el logo (image) del ServiceSupplier. Solo antes de enviarlo a revisión y con public_name ya definido.

Método URI Cabeceras
POST /service-suppliers/{serviceSupplierId}/upload-logo Authorization 
{
    "image": "required|image|mimes:jpeg,png,bmp|max:8192|dimensions:min_width=512,ratio=1/1"
}

Errores de negocio

Código HTTP Cuándo ocurre
ES002 400 El proveedor ya fue enviado a revisión.
ES003 400 Falta public_name.

Enviar proveedor de servicio a revisión

Marca submitted_at en el ServiceSupplier. Requiere public_name y no haber sido enviado ya.

Método URI Cabeceras
POST /service-suppliers/{serviceSupplierId}/submit Authorization

Errores de negocio

Código HTTP Cuándo ocurre
ES002 400 El proveedor ya fue enviado a revisión.
ES003 400 Falta public_name.

Aprobar proveedor de servicio

Marca approved_at en el ServiceSupplier. Requiere estar enviado a revisión y tener public_name. Un proveedor aprobado queda disponible como "adjuntable" para cualquier company o branch.

Método URI Cabeceras
POST /service-suppliers/{serviceSupplierId}/approve Authorization

Errores de negocio

Código HTTP Cuándo ocurre
ES001 400 El proveedor no ha sido enviado a revisión.
ES006 400 El proveedor ya está aprobado.
ES003 400 Falta public_name.

Rechazar proveedor de servicio

Limpia submitted_at: el ServiceSupplier vuelve a borrador y su dueño puede corregirlo y reenviarlo. Requiere estar enviado a revisión y no aprobado.

Método URI Cabeceras
POST /service-suppliers/{serviceSupplierId}/refuse Authorization

Errores de negocio

Código HTTP Cuándo ocurre
ES001 400 El proveedor no ha sido enviado a revisión.
ES006 400 El proveedor ya está aprobado.

Habilitar proveedor de servicio

Pone is_enabled = true en el ServiceSupplier.

Método URI Cabeceras
POST /service-suppliers/{serviceSupplierId}/set-enabled Authorization

Errores de negocio

Código HTTP Cuándo ocurre
ES008 400 El proveedor ya está habilitado.

Deshabilitar proveedor de servicio

Pone is_enabled = false en el ServiceSupplier.

Método URI Cabeceras
POST /service-suppliers/{serviceSupplierId}/set-disabled Authorization

Errores de negocio

Código HTTP Cuándo ocurre
ES007 400 El proveedor no está habilitado.

Relaciones