API docs by Redocly

Sistema de Ventas API (v1)

Download OpenAPI specification:

License: MIT

Documentación oficial de la API de Sistema de Ventas. Esta documentación sirve como "Single Source of Truth" para Frontend, QA y Consumidores Externos.

Autenticación

Endpoints para el flujo completo de autenticación del sistema. Gestiona la obtención del Token Maestro (login), el Token Empresarial (company-access) y el cierre de sesión (logout).

Inicio de sesión

Autentica al usuario con correo y contraseña. Devuelve un Token Maestro y la lista de empresas vinculadas al usuario.

Lógica del frontend según la respuesta:

  • Si user.roleSystem es "superadmin" o "soporte" → redirigir al dashboard global. No requiere Token Empresarial.
  • Si user.roleSystem es null y companies tiene 1 elemento → el Token Empresarial ya viene precargado en companies[0].company.auth. Redirigir al dashboard empresarial.
  • Si user.roleSystem es null y companies tiene más de 1 elemento → todos los company.auth son null. Mostrar selector de empresa y llamar a POST /auth/company-access.
Request Body schema: application/json
required

Credenciales para iniciar sesión en el sistema.

email
required
string <email> <= 255 characters

Correo electrónico registrado del usuario.

password
required
string [ 6 .. 24 ] characters

Contraseña del usuario. Mínimo 6, máximo 24 caracteres.

Responses

Request samples

Content type
application/json
{
  • "email": "usuario1@gmail.com",
  • "password": "Password#123"
}

Response samples

Content type
application/json
Example

roleSystem = "superadmin", companies = []. Entra directo al dashboard global. No necesita Token Empresarial.

{
  • "success": true,
  • "message": "La sesión se ha iniciado correctamente.",
  • "data": {
    },
  • "errors": [ ],
  • "meta": { },
  • "traceId": "38ab526e-97f2-4ece-9bf5-5977940322f9"
}

Acceso empresarial

Genera un Token Empresarial para operar dentro de una empresa específica.

Cuándo usar este endpoint: Solo cuando el usuario tiene más de una empresa vinculada y todos los company.auth en la respuesta del login son null. El usuario debe elegir explícitamente con qué empresa desea operar.

Cómo obtener los valores del body:

  • companyId → campo companyId de la empresa elegida en companies[] del login.
  • companyUserId → campo companyUserId de ese mismo elemento del array.

Resultado: El Token Empresarial recibido reemplaza al Token Maestro como token activo para todos los módulos empresariales (productos, ventas, facturación, clientes, etc.).

Authorizations:
bearerAuth
Request Body schema: application/json
required

Datos para solicitar acceso a una empresa específica. Requiere Token Maestro en el header Authorization.

companyId
required
integer >= 1

ID de la empresa a la que se desea acceder. Debe coincidir con un "companyId" de la lista "companies" retornada en el login.

companyUserId
required
integer >= 1

ID del vínculo usuario-empresa (campo "companyUserId" de la lista "companies" del login). Identifica la relación exacta entre el usuario y la empresa seleccionada.

Responses

Request samples

Content type
application/json
{
  • "companyId": 2,
  • "companyUserId": 2
}

Response samples

Content type
application/json
Example
{
  • "success": true,
  • "message": "El acceso a la empresa ha sido concedido.",
  • "data": {
    },
  • "errors": [ ],
  • "meta": { },
  • "traceId": "f392ed62-d94a-4a1a-94c6-4c72f38faf27"
}

Cierre de sesión

Revoca la sesión completa del usuario. Invalida el Token Maestro y todos los Tokens Empresariales generados a partir de él en una sola operación.

Comportamiento clave:

  • El cierre es total, independientemente de con cuál token se invoque el endpoint.
  • Enviar el Token Maestro o cualquier Token Empresarial produce el mismo resultado.
  • Tras el logout, cualquier request con esos tokens recibirá 401 AUTH_TOKEN_REVOKED.

No requiere body. Solo el header Authorization: Bearer <token>.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "La sesión se ha cerrado correctamente.",
  • "data": null,
  • "errors": [ ],
  • "meta": { },
  • "traceId": "821b948e-4f63-4d53-baa4-aa6aff665b66"
}

Registro Público

Endpoints públicos accesibles sin autenticación previa. Gestionan el registro inicial de empresas en la plataforma SaaS.

Registro público de empresa (SaaS)

Endpoint público que permite a un usuario externo registrar una nueva empresa en el sistema con una estructura mínima y controlada. No requiere autenticación previa.

Dos escenarios principales:

  • Si el correo del propietario no existe en el sistema → se crea el usuario, se crea la empresa, se vinculan con rol owner y se envía correo de bienvenida.
  • Si el correo ya existe → se reutiliza el usuario sin modificar ninguno de sus datos, se crea la empresa, se vincula y se envía correo de nueva vinculación.

Reglas clave del flujo:

  • El NIT debe ser único. Si ya existe, la operación falla completamente (R4, R5).
  • La operación es transaccional: si falla cualquier paso crítico, se revierte todo (R10).
  • La ruta está protegida con limitación de frecuencia: máximo 5 solicitudes por minuto por IP (R13).
  • No se emite token de acceso ni se inicia sesión automáticamente (R12).
  • La respuesta incluye isNewUser en meta para que el frontend interprete el resultado (R18).
Request Body schema: application/json
required

Datos mínimos requeridos para el registro público de una empresa en el sistema SaaS.

nit
required
string <= 30 characters ^\d+$

Número de Identificación Tributaria de la empresa. Solo dígitos numéricos. Debe ser único en el sistema.

category
required
string <= 100 characters

Categoría o rubro de la empresa. Valores permitidos: accessories, food, automotive, barbershop, boutique, coffee-shop, butcher-shop, clinic, commerce, construction, consulting, education, electronics, training, pharmacy, hardware-store, general, gym, home, printing, jewelry, bookstore, liquor-store, logistics, marketing, minimarket, fashion, furniture, stationery, bakery, hair-salon, perfumery, restaurant, health, supermarket, transportation, technology, tourism, veterinary, shoe-store.

legalName
required
string <= 255 characters

Razón social oficial de la empresa.

firstName
required
string <= 120 characters

Nombres del propietario de la empresa.

lastName
required
string <= 120 characters

Apellidos del propietario de la empresa.

email
required
string <email> <= 255 characters

Correo electrónico del propietario. Determina si el usuario ya existe en el sistema. Si existe, se reutiliza sin modificar sus datos. Si no, se crea un nuevo usuario.

password
required
string [ 6 .. 24 ] characters

Contraseña del propietario. Campo obligatorio por consistencia del flujo público, pero solo se aplica si el usuario no existe previamente en el sistema. Debe contener al menos 1 mayúscula, un número y un símbolo especial.

Responses

Request samples

Content type
application/json
{
  • "nit": "1234567890",
  • "category": "technology",
  • "legalName": "Mi Empresa de Prueba S.A.",
  • "firstName": "Juan",
  • "lastName": "Pérez García",
  • "email": "juan.perez@example.com",
  • "password": "Password#123"
}

Response samples

Content type
application/json
Example

El correo no existía en el sistema. Se creó el usuario, se creó la empresa, se vincularon con rol owner y se encoló el correo de bienvenida.

{
  • "success": true,
  • "message": "La empresa se ha registrado correctamente.",
  • "data": null,
  • "errors": [ ],
  • "meta": {
    },
  • "traceId": "8d1a6ef2-c3f7-45ea-a88b-42bfa1c5bc19"
}

Validar verificación de correo de empresa

Endpoint público que consume el token de verificación del correo empresarial, emitido previamente por el flujo de verificación de correo de empresa.

Comportamiento:

  • Si el correo de la empresa ya está verificado, responde rápidamente sin validaciones adicionales.
  • Si el token es válido, no ha expirado y el correo del token coincide con el correo actual de la empresa, se registra la fecha de verificación y se cierra el proceso.
  • Si el correo de la empresa cambió después de emitirse el token, este se considera inválido (409).
  • Si el token ya expiró, se rechaza la operación (410).

Seguridad:

  • No requiere token maestro ni token empresarial.
  • La seguridad recae en el token SHA-256 emitido por el flujo de verificación.
  • Protegido con rate limiting.
Request Body schema: application/json
required
token
required
string non-empty

Token seguro emitido por el flujo de verificación de correo empresarial.

Responses

Request samples

Content type
application/json
{
  • "token": "aB3dEfGhIjKlMnOpQrStUvWxYz0123456789aB3dEfGhIjKlMnOpQrStUvWxYz01"
}

Response samples

Content type
application/json
Example

El token era válido, vigente y coincidía con el correo actual de la empresa. Se registró la fecha de verificación y se cerró el proceso.

{
  • "success": true,
  • "message": "El correo de la empresa se ha verificado correctamente.",
  • "data": {
    },
  • "errors": [ ],
  • "meta": { },
  • "traceId": "d44bb1d1-0b1d-4f91-84ca-c4ac3d4ae7c6"
}

Empresas

Endpoints de gestión de empresas. Incluye gestión del perfil de la empresa actual (requiere Token Empresarial) y administración interna (requiere Token Maestro).

Crear empresa (Administrativo)

Crea una nueva empresa desde el panel administrativo. Si el correo del propietario no existe, se creará el usuario y se le asignará una contraseña autogenerada y enviada a su correo. Si existe, se reutilizará.

Authorizations:
bearerAuth
Request Body schema: application/json
required

Datos requeridos para registrar una nueva empresa y vincular su propietario desde el sistema administrativo.

required
object

Objeto con los datos empresariales.

required
object

Objeto con los datos del propietario.

Responses

Request samples

Content type
application/json
{
  • "company": {
    },
  • "user": {
    }
}

Response samples

Content type
application/json
Example
{
  • "success": true,
  • "message": "La empresa se ha registrado correctamente.",
  • "data": null,
  • "errors": [ ],
  • "meta": {
    },
  • "traceId": "a3f2d1c8-4e5b-4f6a-9c7d-1b2e3f4a5b6c"
}

Listar empresas (Administrativo)

Obtiene un listado paginado de todas las empresas registradas en la plataforma SaaS. Permite filtrar por categoría, estado y estado de verificación, además de buscar por término y ordenar por diferentes columnas.

Authorizations:
bearerAuth
query Parameters
page
integer >= 1
Default: 1

Número de la página para la paginación.

per_page
integer [ 1 .. 100 ]
Default: 10

Cantidad de elementos por página.

search
string
Example: search=El termino a buscar

Término de búsqueda para filtrar los resultados.

sortBy
string
Enum: "nit" "legalName" "tradeName" "owner" "category" "status" "updatedAt"
Example: sortBy=updatedAt

Campo por el cual ordenar el listado.

sortDirection
string
Enum: "asc" "desc"
Example: sortDirection=desc

Dirección del ordenamiento.

category
string
Example: category=technology

Filtro exacto por categoría de la empresa.

verification
string
Enum: "pending" "completed" "rejected"
Example: verification=pending

Filtro por estado de verificación de los documentos de la empresa.

status
string
Enum: "enabled" "disabled" "suspended"
Example: status=enabled

Filtro por estado general de la empresa.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "El listado de empresas se ha obtenido correctamente.",
  • "data": [
    ],
  • "errors": [ ],
  • "meta": {
    },
  • "traceId": "b8c3e4d5-f6a7-8b9c-0d1e-2f3a4b5c6d7e"
}

Listado Rápido de Empresas (Administrativo)

Obtiene un listado rápido de las empresas registradas en la plataforma, optimizado para selectores tipo "combobox" o listas con scroll infinito. Utiliza paginación por cursor en lugar de paginación tradicional para un mejor rendimiento con grandes volúmenes de datos. Solo retorna las empresas habilitadas (estado 'enabled').

Authorizations:
bearerAuth
query Parameters
search
string
Example: search=Tech

Término de búsqueda parcial aplicado sobre el nombre legal (legalName) de la empresa.

orderBy
string
Enum: "id" "legalName" "updatedAt"
Example: orderBy=legalName

Campo por el cual ordenar el listado. Por defecto es legalName.

orderDirection
string
Enum: "asc" "desc"
Example: orderDirection=asc

Dirección del ordenamiento.

limit
integer
Default: 15
Example: limit=15

Cantidad máxima de resultados a retornar en esta solicitud. Por defecto es 15.

cursor
string
Example: cursor=eyJpdiI6IkhDOHVwTkdMOWs0bSIsIm1hYyI6IjFiMjMz...=

Cursor opaco y encriptado para obtener la siguiente página de resultados. Debe enviarse exactamente el valor devuelto en meta.pagination.nextCursor de la solicitud anterior.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "El listado rápido de empresas se ha obtenido correctamente.",
  • "data": [],
  • "errors": [ ],
  • "meta": {
    },
  • "traceId": "b8c3e4d5-f6a7-8b9c-0d1e-2f3a4b5c6d7e"
}

Obtener detalle de empresa (Administrativo)

Obtiene el detalle completo de una empresa desde el entorno interno del sistema. Retorna toda la información necesaria para la revisión, gestión y seguimiento del perfil empresarial, incluyendo los datos completos del propietario principal y una vista resumida (últimos 5 registros) del historial reciente de verificación. Las imágenes y archivos se retornan como rutas completas listas para su consumo, acompañadas de metadatos básicos.

Authorizations:
bearerAuth
path Parameters
id
required
integer >= 1

Identificador único de la empresa.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "Operación exitosa",
  • "data": {
    },
  • "errors": [ ],
  • "meta": {
    },
  • "traceId": "729bb1bf-882d-483b-89d3-5855dc5af3aa"
}

Actualizar empresa (Administrativo)

Actualiza de manera parcial los datos de la empresa y del propietario. Este endpoint requiere rol de superadmin o soporte.

Reglas de negocio críticas:

  • R12 (Datos Sensibles): Si se modifica la category o la legalName (Razón Social), la empresa perderá su estado de verificado automáticamente y se generará una nueva solicitud de verificación en el historial.
  • R16 (Email): El correo electrónico empresarial no puede ser eliminado (setearse a nulo) una vez que ha sido asignado.
  • R17 (Estado): Solo se pueden actualizar empresas que estén en estado enabled.
Authorizations:
bearerAuth
path Parameters
id
required
integer

ID interno de la empresa a actualizar.

Request Body schema: application/json
required

Datos requeridos para actualizar parcialmente una empresa y su propietario.

object

Objeto con los datos empresariales a actualizar.

object

Objeto con los datos del propietario vinculado.

Responses

Request samples

Content type
application/json
{
  • "company": {
    },
  • "user": {
    }
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "Operación exitosa",
  • "data": null,
  • "errors": [ ],
  • "meta": {
    },
  • "traceId": "729bb1bf-882d-483b-89d3-5855dc5af3aa"
}

Eliminar empresa (Administrativo)

Elimina físicamente una empresa y sus dependencias directas desde el entorno administrativo.

Esta operación:

  • Exige token maestro válido con rol de sistema autorizado (superadmin o soporte).
  • No acepta tokens empresariales.
  • Elimina primero las dependencias bloqueantes por restrictOnDelete() (ej. verificaciones NIT y correo, audit).
  • Elimina los vínculos de los usuarios.
  • Evalúa a cada usuario: si no tiene vinculaciones con otras empresas, lo elimina por completo. Si tiene otras, lo conserva intacto.
  • Se ejecuta bajo una transacción atómica para garantizar que la operación es segura y reversible en caso de fallos.
Authorizations:
bearerAuth
path Parameters
id
required
integer >= 1
Example: 1

Identificador único de la empresa a eliminar.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "Empresa eliminada permanentemente a través del endpoint de administración.",
  • "data": null,
  • "errors": [ ],
  • "meta": {
    },
  • "traceId": "729bb1bf-882d-483b-89d3-5855dc5af3aa"
}

Listar verificaciones de empresas (Administrativo)

Obtiene el listado paginado de verificaciones NIT de empresas registradas en la plataforma. Solo muestra el último registro vigente de verificación por empresa dentro de una gestión (año) específica.

Este endpoint permite al equipo administrativo revisar el estado actual de las solicitudes de verificación NIT, identificar procesos pendientes, en revisión, aprobados o rechazados, y priorizar la atención según vencimiento, encargado, categoría, documento y fecha de actualización.

Reglas de negocio:

  • Solo se muestra un registro por empresa (el último estado vigente del ciclo activo).
  • El campo startedAt corresponde a la fecha de la solicitud original del ciclo.
  • El vencimiento se calcula a 72 horas desde startedAt.
  • Para estados approved o rejected, minutesRemaining devuelve 0 de forma fija, isExpired es false y category es 'none'.
  • El encargado (handler) es el usuario que registró el cambio al estado process.
  • Si la solicitud no ha sido tomada en proceso, handler es null.
Authorizations:
bearerAuth
query Parameters
year
required
integer
Example: year=2026

Gestión (año) a consultar. Campo obligatorio. Filtra verificaciones cuya solicitud original pertenece a este año.

page
integer >= 1
Default: 1

Número de la página para la paginación.

per_page
integer [ 1 .. 100 ]
Default: 10

Cantidad de elementos por página.

search
string
Example: search=El termino a buscar

Término de búsqueda para filtrar los resultados.

sortBy
string
Default: "expiration"
Enum: "legalName" "category" "document" "startedAt" "expiration" "handler" "status" "updatedAt"
Example: sortBy=expiration

Campo por el cual ordenar el listado.

sortDirection
string
Default: "asc"
Enum: "asc" "desc"
Example: sortDirection=asc

Dirección del ordenamiento.

category
string
Example: category=pharmacy

Filtro exacto por categoría de la empresa. Solo un valor.

document
string
Enum: "certificate" "exhibition" "code"
Example: document=certificate

Filtro exacto por tipo de documento tributario presentado.

expiration
string
Enum: "high" "medium" "low" "none"
Example: expiration=high

Filtro por rango de vencimiento del ciclo activo. Solo aplica a estados request o process.

  • high: menos de 6 horas para vencer.
  • medium: entre 6 y 12 horas.
  • low: entre 12 y 24 horas.
  • none: más de 24 horas.
status
string
Enum: "request" "process" "approved" "rejected"
Example: status=process

Filtro exacto por estado de la verificación.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "El listado de verificaciones de empresas se ha obtenido correctamente.",
  • "data": [
    ],
  • "errors": [ ],
  • "meta": {
    },
  • "traceId": "f1e2d3c4-b5a6-7890-abcd-ef1234567890"
}

Actualizar datos tributarios de verificación (Administrativo)

Actualiza parcialmente los datos tributarios (NIT, razón social, régimen, representantes legales, etc.) asociados a un registro de verificación de empresa. Debe enviarse al menos un campo a modificar.

Authorizations:
bearerAuth
path Parameters
verificationId
required
integer
Example: 101

ID del registro de verificación.

Request Body schema: application/json
required
nitNumber
string or null <= 30 characters

Número de Identificación Tributaria (NIT).

nitLegalName
string or null <= 255 characters

Razón social asociada al NIT.

nitCertificationCode
string <= 255 characters

Código de certificación tributaria.

nitImage
string <= 255 characters

Ruta o identificador de la imagen del documento NIT.

nitTaxRegime
string or null
Enum: "general" "simplified" "integrated" "unified"

Régimen tributario.

nitTaxCategory
string or null
Enum: "pricos" "gracos" "rest"

Categoría tributaria.

nitTaxpayerType
string or null
Enum: "natural" "legal" "unipersonal"

Tipo de contribuyente.

nitTaxpayerState
string or null <= 255 characters

Estado del contribuyente.

nitEntityType
string or null <= 255 characters

Tipo de entidad.

Array of objects or null non-empty

Lista de actividades económicas. Si se envía, debe tener al menos un elemento.

Array of objects or null non-empty

Lista de representantes legales. Si se envía, debe tener al menos un elemento.

Responses

Request samples

Content type
application/json
{
  • "nitNumber": "123456789",
  • "nitLegalName": "Empresa de Ejemplo S.A.",
  • "nitCertificationCode": "ABC123XYZ",
  • "nitImage": "nit_image_45.jpg",
  • "nitTaxRegime": "general",
  • "nitTaxCategory": "rest",
  • "nitTaxpayerType": "legal",
  • "nitTaxpayerState": "Activo",
  • "nitEntityType": "Sociedad Anónima",
  • "nitEconomicActivities": [
    ],
  • "nitLegalRepresentatives": [
    ]
}

Response samples

Content type
application/json
Example
{
  • "success": true,
  • "message": "Los datos tributarios de la verificación se han actualizado correctamente.",
  • "data": null,
  • "errors": [ ],
  • "meta": [ ],
  • "traceId": "a3f2d1c8-4e5b-4f6a-9c7d-1b2e3f4a5b6f"
}

Obtener detalle de verificación de empresa (Administrativo)

Obtiene toda la información detallada de un registro de verificación NIT de una empresa, incluyendo datos de la empresa, propietario, información tributaria, historial de verificaciones, encargado y metadatos del estado del proceso.

Este endpoint permite al equipo administrativo revisar en profundidad toda la información relacionada con una solicitud de verificación, incluyendo el historial completo de cambios de estado, observaciones, y quién registró cada cambio.

Authorizations:
bearerAuth
path Parameters
verificationId
required
integer
Example: 41

Identificador único del registro de verificación.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "La información de verificación de la empresa se ha obtenido correctamente.",
  • "data": {
    },
  • "errors": [ ],
  • "meta": {
    },
  • "traceId": "f1e2d3c4-b5a6-7890-abcd-ef1234567890"
}

Actualizar estado de verificación

Actualiza el estado del proceso de verificación de una empresa. Permite confirmar una solicitud, aprobar una verificación o rechazar una solicitud/verificación según el estado actual del flujo.

Authorizations:
bearerAuth
path Parameters
verificationId
required
integer
Example: 10

ID de la verificación a gestionar.

Request Body schema: application/json
required

Payload para cambiar el estado de verificación.

status
required
string
Enum: "confirm" "approve" "reject"

Acción a realizar sobre la verificación. Valores: confirm (Confirmar solicitud), approve (Aprobar proceso), reject (Rechazar solicitud o proceso).

observation
string or null <= 1500 characters

Observaciones o motivos de rechazo/aprobación. Requerido para approve y reject (mín 50 caracteres). Opcional para confirm.

Responses

Request samples

Content type
application/json
{
  • "status": "approve",
  • "observation": "Los documentos revisados cumplen con los requisitos legales y tributarios correspondientes a la categoría general. Se aprueba la solicitud."
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "La verificación ha sido confirmada.",
  • "data": {
    },
  • "errors": [ ],
  • "meta": { },
  • "traceId": "123e4567-e89b-12d3-a456-426614174000"
}

Enviar verificación de correo

Inicia el proceso de verificación del correo electrónico empresarial enviando un código o enlace de verificación al correo registrado de la empresa.

Este enlace apunta a la aplicación Frontend (frontend_url) donde el usuario podrá completar el proceso.

Este endpoint puede ser ejecutado por:

  1. Administradores (superadmin o soporte) con token maestro.
  2. El propietario de la empresa con su token empresarial (CONNECTION).
Authorizations:
bearerAuth
path Parameters
companyId
required
integer
Example: 1

ID de la empresa a la que se le enviará la verificación.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "La verificación del correo de la empresa se ha enviado correctamente.",
  • "data": null,
  • "errors": [ ],
  • "meta": { },
  • "traceId": "a3f2d1c8-4e5b-4f6a-9c7d-1b2e3f4a5b6c"
}

Obtener perfil de la empresa activa

Nota de Seguridad: Este endpoint requiere un Token Empresarial (no el Master Token normal). Debe obtenerse previamente mediante el endpoint /api/v1/auth/company-access.

Obtiene el perfil completo de la empresa vinculada al token actual, incluyendo sus datos generales, la información del propietario principal, y el historial agrupado de todas sus solicitudes de verificación.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "El perfil de la empresa se ha obtenido correctamente.",
  • "data": {
    },
  • "errors": [ ],
  • "meta": {
    },
  • "traceId": "729bb1bf-882d-483b-89d3-5855dc5af3aa"
}

Actualizar perfil de empresa (empresa)

Nota de Seguridad: Este endpoint requiere un Token Empresarial activo.

Permite al propietario actualizar parcialmente el perfil de su empresa. Permite modificar datos generales de la empresa, datos básicos del propietario y campos visuales. No se permite actualizar identificadores sensibles como el NIT de la empresa o el correo del propietario.

Reglas Críticas:

  • R5: Si la empresa tiene una verificación en curso (estado request o process), no se permite actualizar.
  • R23/R24: Modificar campos sensibles (category, legalName de la empresa, o datos documentales del propietario) reiniciará el estado de verificación y generará una nueva solicitud automáticamente.
  • R14/R15: Modificar el correo empresarial (email) reiniciará la verificación del correo electrónico.
Authorizations:
bearerAuth
Request Body schema: application/json
required

Datos requeridos para actualizar parcialmente el perfil de la empresa y su propietario.

object

Objeto contenedor de los datos de la empresa.

object

Objeto contenedor de los datos del propietario.

Responses

Request samples

Content type
application/json
{
  • "company": {
    },
  • "user": {
    }
}

Response samples

Content type
application/json
Example
{
  • "success": true,
  • "message": "El perfil de la empresa se ha actualizado correctamente.",
  • "data": null,
  • "errors": [ ],
  • "meta": {
    },
  • "traceId": "5fdb1d84-0c41-49dc-8c38-79f8fb77e7f1"
}

Crear solicitud de verificación de empresa

Inicia el proceso formal de verificación de una empresa. Esta operación es exclusiva para el entorno de empresa y solo puede ser ejecutada por el propietario (owner).

Para poder crear la solicitud, la empresa debe cumplir requisitos mínimos (NIT, Razón Social, Categoría, Correo, Teléfono, Dirección), el propietario debe tener datos básicos completos, tener el correo verificado, y haber adjuntado la evidencia del tipo de documento legal seleccionado.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "La solicitud de verificación de la empresa se ha creado correctamente.",
  • "data": null,
  • "errors": [ ],
  • "meta": { },
  • "traceId": "86161ad0-79e7-4320-9c80-cad3e459122d"
}

Actualizar documentación legal de la empresa

Actualiza la documentación legal que respalda la verificación y el NIT de la empresa actual desde su contexto autenticado. Esta operación es exclusiva para el entorno empresarial y solo puede ser ejecutada por el propietario (OWNER). La actualización de documentación de respaldo no genera una nueva solicitud de verificación por sí misma, sino que actualiza los datos que se enviarán en la solicitud de verificación.

Authorizations:
bearerAuth
Request Body schema: multipart/form-data
required
legalDocumentType
required
string
Enum: "exhibition" "certificate" "code"

Tipo de documento legal de verificación del NIT. Valores permitidos:

  • exhibition: Documento de exhibición.
  • certificate: Certificación de Registro.
  • code: Código de certificación tributaria.
legalDocumentFile
string <binary>

Archivo adjunto de evidencia del documento legal. Es obligatorio si el campo legalDocumentType es exhibition o certificate. Debe estar ausente o ser nulo si el campo legalDocumentType es code. Formatos admitidos: PDF o imágenes (jpg, jpeg, png, webp). Límite de tamaño: 10 MB (10240 KB).

certificationCode
string

Código de certificación tributaria. Es obligatorio si el campo legalDocumentType es code. Debe estar ausente o ser nulo si el campo legalDocumentType es exhibition o certificate. Solo admite letras, números y guiones. No se permiten espacios ni caracteres especiales.

Responses

Response samples

Content type
application/json
Example
{
  • "success": true,
  • "message": "La documentación legal de la empresa se ha actualizado correctamente.",
  • "data": {
    },
  • "errors": [ ],
  • "meta": {
    },
  • "traceId": "9969dc5b-2e28-4d66-aa5f-3974db7754ef"
}

Obtener información de verificación de la empresa activa

Nota de Seguridad: Este endpoint requiere un Token Empresarial (no el Master Token normal). Debe obtenerse previamente mediante el endpoint /api/v1/auth/company-access.

Obtiene la información necesaria para que el propietario revise el estado de verificación de su empresa, los requisitos previos para solicitar una nueva verificación y el historial completo de solicitudes anteriores.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
Example
{
  • "success": true,
  • "message": "La información de verificación de la empresa se ha obtenido correctamente.",
  • "data": {
    },
  • "errors": [ ],
  • "meta": {
    },
  • "traceId": "12d89c4c-7a4a-47ae-bf7a-2237713d5b13"
}

Usuarios

Endpoints de gestión de usuarios. Incluye listados empresariales y operaciones relacionadas con los usuarios del sistema.

Listar usuarios (Administrativo)

Obtiene un listado paginado de usuarios desde la vista administrativa. Permite listar usuarios del sistema (superadmin, support) o usuarios empresariales, con soporte para filtrado, búsqueda y ordenamiento.

Authorizations:
bearerAuth
query Parameters
userType
required
string
Enum: "system" "business"
Example: userType=business

Tipo de usuario a listar. Requerido.

  • system: Lista usuarios con roles globales del sistema.
  • business: Lista usuarios vinculados a empresas.
search
string
Example: search=juan

Término de búsqueda parcial (nombre completo, correo o teléfono).

activity
string
Enum: "today" "yesterday" "last_7_days" "last_30_days" "last_60_days" "over_60_days"
Example: activity=last_30_days

Filtro por última actividad (basado en la última conexión). Valores: today, yesterday, last_7_days, last_30_days, last_60_days, over_60_days.

role
string
Enum: "superadmin" "support" "owner" "manager" "vendor" "assistant"
Example: role=owner

Filtro por rol. Debe ser un rol de sistema si userType=system, o rol empresarial si userType=business. Valores: superadmin, support, owner, manager, vendor, assistant.

state
string
Enum: "enabled" "disabled" "suspended"
Example: state=enabled

Filtro por estado del usuario o vínculo empresarial.

orderBy
string
Default: "updatedAt"
Enum: "fullName" "email" "phone" "company" "role" "state" "lastLoginAt" "updatedAt"

Campo por el cual ordenar. Valores: fullName, email, phone, company, role, state, lastLoginAt, updatedAt.

orderDirection
string
Default: "desc"
Enum: "asc" "desc"

Dirección del ordenamiento.

page
integer >= 1
Default: 1

Número de página para la paginación.

perPage
integer
Default: 10
Enum: 5 10 25 50 100

Cantidad de registros por página.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "El listado de usuarios se ha obtenido correctamente.",
  • "data": [
    ],
  • "meta": {
    },
  • "errors": [ ],
  • "traceId": "d4e5f6a7-b8c9-0123-def0-123456789012"
}

Eliminar usuario de sistema o desvincular empresarial (Administrativo)

Endpoint administrativo para eliminar un usuario de sistema o desvincular un usuario empresarial. Si el usuario de sistema tiene procesos activos (como verificaciones), no podrá ser eliminado. Si el usuario empresarial ya no cuenta con vínculos activos después de la desvinculación, su cuenta será eliminada completamente.

No se permite eliminar o desvincular usuarios con rol superadmin o owner empresarial.

Authorizations:
bearerAuth
Request Body schema: application/json
required
userId
required
integer

ID del usuario a eliminar o desvincular.

companyId
integer

ID de la empresa (obligatorio solo para desvincular usuarios empresariales).

Responses

Request samples

Content type
application/json
{
  • "userId": 45,
  • "companyId": 10
}

Response samples

Content type
application/json
Example
{
  • "success": true,
  • "message": "El usuario de sistema ha sido eliminado correctamente.",
  • "data": {
    },
  • "errors": [ ],
  • "meta": { },
  • "traceId": "a1b2c3d4-e5f6-7a8b-9c0d-1e2f3a4b5c6d"
}

Obtener detalle completo de usuario (Administrativo)

Endpoint administrativo para obtener el detalle completo de un usuario de sistema o empresarial. Devuelve la cuenta principal y todas las secciones del perfil disponibles: datos personales, documentación legal, direcciones personales, contactos de emergencia, formación académica, habilidades, experiencia laboral, contrato laboral y horario de trabajo.

Para usuarios de sistema se ignora el parámetro companyId. Para usuarios empresariales se requiere companyId y se valida la pertenencia del usuario a esa empresa.

Authorizations:
bearerAuth
query Parameters
userId
required
integer
Example: userId=19

Identificador del usuario a consultar.

companyId
integer
Example: companyId=10

Identificador de empresa (obligatorio para usuarios empresariales, ignorado para sistema).

Responses

Response samples

Content type
application/json
Example
{
  • "success": true,
  • "message": "El detalle del usuario se ha obtenido correctamente.",
  • "data": {
    },
  • "errors": [ ],
  • "meta": { },
  • "traceId": "a1b2c3d4-e5f6-7a8b-9c0d-1e2f3a4b5c6d"
}

Registrar o vincular usuario (Administrativo)

Crea un nuevo usuario de sistema (support) o un usuario empresarial (manager, vendor, assistant). Si el usuario empresarial ya existe, se vincula a la empresa especificada sin modificar su cuenta principal.

Reglas Principales:

  • Los roles "superadmin" y "owner" no pueden ser asignados mediante este endpoint.
  • Rol support no requiere companyId. Los roles empresariales sí requieren companyId.
  • Un usuario del sistema no puede estar vinculado a empresas.
  • Si el correo pertenece a un usuario empresarial y se intenta vincular a otra empresa, se crea el vínculo sin modificar su contraseña o datos de cuenta base.
  • Se enviará un correo electrónico correspondiente: de creación de cuenta (con credenciales temporales) o de notificación de nueva vinculación.
  • Operación completamente transaccional.
Authorizations:
bearerAuth
Request Body schema: application/json
required

Datos requeridos para registrar o vincular un usuario de sistema o empresarial.

required
object

Datos principales de la cuenta del usuario.

required
object

Datos personales básicos del perfil del usuario.

object or null

Información del documento de identidad o documentación legal del usuario.

Array of objects or null

Lista de direcciones personales o corporativas asociadas al usuario.

Array of objects or null

Lista de contactos en caso de emergencia.

object or null

Información sobre el nivel educativo o formación académica alcanzada.

Array of objects or null

Lista de habilidades técnicas, conocimientos o idiomas del usuario.

Array of objects or null

Historial de experiencia laboral o empleos anteriores.

object or null

Datos del contrato laboral.

Array of objects or null

Esquema de horarios y turnos de trabajo asignados al usuario.

Responses

Request samples

Content type
application/json
{
  • "account": {
    },
  • "personalData": {
    },
  • "legalDocumentation": {
    },
  • "personalAddresses": [
    ],
  • "emergencyContacts": [
    ],
  • "academicFormation": {
    },
  • "skills": [
    ],
  • "workExperiences": [
    ],
  • "employmentContract": {
    },
  • "workSchedules": [
    ]
}

Response samples

Content type
application/json
Example
{
  • "success": true,
  • "message": "El usuario de sistema ha sido creado correctamente.",
  • "data": {
    },
  • "errors": [ ],
  • "meta": { },
  • "traceId": "a3f2d1c8-4e5b-4f6a-9c7d-1b2e3f4a5b6c"
}

Actualizar usuario (Administrativo)

Permite la actualización parcial de un usuario de sistema o empresarial desde el panel administrativo.

Reglas Principales:

  • Solo usuarios de sistema autorizados (superadmin, support) pueden ejecutar esta operación.
  • El userId es obligatorio y debe corresponder a un usuario existente.
  • Si el usuario es de sistema, companyId se ignora y se actualiza el perfil general.
  • Si el usuario es empresarial, companyId es obligatorio y debe corresponder a una empresa vinculada.
  • La actualización es parcial: solo se envían las secciones/campos que se desean modificar.
  • Debe existir al menos un campo permitido para actualización.
  • No se permite cambiar el correo principal, la empresa vinculada ni el tipo de usuario.
  • No se permite asignar los roles superadmin ni owner.
  • No se permite cambiar el estado desde o hacia suspended.
  • Para usuarios de sistema, el único rol permitido es support.
  • Para usuarios empresariales, los roles permitidos son manager, vendor y assistant.
  • Las secciones únicas (personalData, legalDocumentation, academicFormation, employmentContract) se actualizan o crean.
  • Las secciones múltiples (personalAddresses, emergencyContacts, skills, workExperiences, workSchedules) se reemplazan completamente.
  • Enviar una sección múltiple como [] o null elimina todos los registros existentes de esa sección.
  • Operación completamente transaccional.
Authorizations:
bearerAuth
Request Body schema: application/json
required

Payload de actualización parcial de usuario. Solo se envían las secciones y campos que se desean modificar. El campo userId es obligatorio. El campo companyId es obligatorio para usuarios empresariales.

userId
required
integer

Identificador del usuario a actualizar.

companyId
integer or null

Identificador de la empresa. Obligatorio para usuarios empresariales, se ignora para usuarios de sistema.

object or null

Datos de la cuenta a actualizar. Para usuarios de sistema: phone, role y state se actualizan en la cuenta principal. Para usuarios empresariales: role y state se actualizan en el vínculo, phone en la cuenta principal.

object or null

Datos personales básicos del perfil del usuario. Se actualiza o crea como registro único.

object or null

Información del documento de identidad. Se actualiza o crea como registro único.

Array of objects or null

Lista de direcciones personales. Reemplazo completo: enviar [] o null elimina todas las direcciones existentes.

Array of objects or null

Lista de contactos de emergencia. Reemplazo completo: enviar [] o null elimina todos los contactos existentes.

object or null

Formación académica. Se actualiza o crea como registro único.

Array of objects or null

Lista de habilidades. Reemplazo completo: enviar [] o null elimina todas las habilidades existentes.

Array of objects or null

Historial de experiencia laboral. Reemplazo completo: enviar [] o null elimina todas las experiencias existentes.

object or null

Contrato laboral. Se actualiza o crea como registro único.

Array of objects or null

Horarios de trabajo. Reemplazo completo: enviar [] o null elimina todos los horarios existentes.

Responses

Request samples

Content type
application/json
Example
{
  • "userId": 10,
  • "account": {
    }
}

Response samples

Content type
application/json
Example
{
  • "success": true,
  • "message": "El usuario de sistema ha sido actualizado correctamente.",
  • "data": {
    },
  • "errors": [ ],
  • "meta": { },
  • "traceId": "a3f2d1c8-4e5b-4f6a-9c7d-1b2e3f4a5b6c"
}

Registrar o vincular usuario en la empresa activa (Empresarial)

Crea un nuevo usuario empresarial o vincula un usuario existente a la empresa activa del token. El endpoint debe permitir a usuarios con rol propietario o administrador registrar usuarios empresariales con rol administrador, vendedor o auxiliar.

Reglas Principales:

  • Si el usuario (correo) no existe, se crea la cuenta base y el perfil completo asociado a la empresa. Se envía correo de bienvenida.
  • Si el usuario (correo) ya existe, no se modifican sus datos de cuenta principal, únicamente se crea el vínculo y su perfil dentro de la empresa activa. Se envía correo de aviso de nueva vinculación.
  • No se permite asignar el rol de owner (propietario) por esta vía.
  • El correo proporcionado no puede pertenecer a un usuario administrativo del sistema (superadmin, soporte).
  • La respuesta incluye los identificadores del usuario, su vínculo y la empresa activa.
Authorizations:
bearerAuth
Request Body schema: application/json
required
required
object

Datos principales de la cuenta del usuario. Si el usuario ya existe en el sistema, estos datos no modificarán su cuenta principal existente, únicamente se utilizarán para resolver el vínculo con la empresa.

required
object

Datos personales básicos del perfil del usuario para esta empresa.

object or null

Información del documento de identidad o documentación legal del usuario.

Array of objects or null

Lista de direcciones personales o corporativas asociadas al usuario.

Array of objects or null

Lista de contactos en caso de emergencia.

object or null

Información sobre el nivel educativo o formación académica alcanzada.

Array of objects or null

Lista de habilidades técnicas, conocimientos o idiomas del usuario.

Array of objects or null

Historial de experiencia laboral o empleos anteriores.

object or null

Datos del contrato laboral establecido con la empresa.

Array of objects or null

Esquema de horarios y turnos de trabajo asignados al usuario.

Responses

Request samples

Content type
application/json
{
  • "account": {
    },
  • "personalData": {
    },
  • "legalDocumentation": {
    },
  • "personalAddresses": [
    ],
  • "emergencyContacts": [
    ],
  • "academicFormation": {
    },
  • "skills": [
    ],
  • "workExperiences": [
    ],
  • "employmentContract": {
    },
  • "workSchedules": [
    ]
}

Response samples

Content type
application/json
Example
{
  • "success": true,
  • "message": "El usuario ha sido creado y vinculado exitosamente a la empresa. Se ha enviado un correo con sus credenciales.",
  • "data": {
    },
  • "errors": [ ],
  • "meta": { },
  • "traceId": "a3f2d1c8-4e5b-4f6a-9c7d-1b2e3f4a5b6c"
}

Listar usuarios (Empresarial)

Obtiene el listado paginado de usuarios vinculados a la empresa activa del contexto.

Reglas y Restricciones:

  • Requiere un token empresarial activo.
  • El usuario autenticado debe tener rol de owner o manager.
  • La consulta se restringe internamente a la empresa activa.
  • Retorna información resumida de cada usuario.
Authorizations:
bearerAuth
query Parameters
search
string

Buscar por coincidencia parcial en nombre completo, correo o teléfono.

activity
string
Enum: "today" "yesterday" "last_7_days" "last_30_days" "last_60_days" "over_60_days"

Filtro por rango de última conexión.

role
string
Enum: "owner" "manager" "vendor" "assistant"

Filtrar por rol en la empresa.

state
string
Enum: "enabled" "disabled" "suspended"

Filtrar por estado del vínculo con la empresa.

orderBy
string
Default: "lastUpdate"
Enum: "fullName" "email" "phone" "role" "state" "lastConnection" "lastUpdate"

Campo por el cual ordenar el listado.

orderDirection
string
Default: "desc"
Enum: "asc" "desc"

Dirección del ordenamiento.

page
integer >= 1
Default: 1

Número de página.

perPage
integer
Default: 10
Enum: 5 10 25 50 100

Cantidad de registros por página.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "Listado de usuarios de la empresa obtenido.",
  • "data": [
    ],
  • "errors": [ ],
  • "meta": {
    },
  • "traceId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Listado Rápido de Usuarios (Empresarial)

Obtiene un listado rápido de los usuarios pertenecientes a la empresa activa. Está optimizado para selectores tipo "combobox" o listas con scroll infinito, retornando un contrato reducido con solo ID, nombre completo, rol y avatar. Utiliza paginación por cursor para un rendimiento óptimo.

Authorizations:
bearerAuth
query Parameters
search
string
Example: search=Juan Perez

Término de búsqueda parcial aplicado sobre el nombre completo del usuario.

includeAssistants
boolean
Example: includeAssistants=true

Filtro opcional para incluir o excluir usuarios con rol de auxiliar. El valor predeterminado es true.

sortBy
string
Default: "role"
Enum: "id" "fullName" "role"

Campo por el cual ordenar los resultados. Para garantizar la estabilidad de la paginación, siempre se utiliza el ID de forma interna como criterio de desempate.

sortDirection
string
Default: "asc"
Enum: "asc" "desc"

Dirección de ordenamiento.

limit
integer [ 5 .. 25 ]
Default: 5

Cantidad máxima de elementos a retornar por página. Se permiten valores entre 5 y 25.

cursor
string
Example: cursor=eyJpdiI6Inl1Vn...XoifQ==

Cursor opaco utilizado para obtener la siguiente página de resultados. Debe tomarse directamente del campo nextCursor de la respuesta anterior.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "null",
  • "data": {},
  • "errors": [
    ],
  • "meta": { },
  • "traceId": "729bb1bf-882d-483b-89d3-5855dc5af3aa"
}

Obtener detalle de usuario (Empresarial)

Devuelve el perfil completo de un usuario vinculado a la empresa activa del token. El perfil incluye información de cuenta, datos personales, documentación legal, direcciones, contactos de emergencia, formación académica, habilidades, experiencia laboral, contrato laboral y horarios de trabajo.

Reglas y Restricciones:

  • Requiere un token empresarial activo.
  • Solo usuarios con rol owner (propietario) o manager (administrador) pueden consultar el perfil.
  • El perfil devuelto corresponde exclusivamente al vínculo con la empresa activa. No se exponen datos de otros vínculos del usuario.
  • La cuenta muestra únicamente correo, rol y estado (sin contraseña ni datos sensibles).
  • Para prevenir la enumeración de usuarios, la API retorna 404 tanto si el usuario no existe como si existe pero no está vinculado a la empresa activa.
  • El parámetro idUser debe ser un número entero. Si se envía un valor no numérico, la ruta no hace match y se retorna 404.
  • Las secciones sin datos se devuelven como null (para objetos únicos) o [] (para listas).
Authorizations:
bearerAuth
path Parameters
idUser
required
integer
Example: 6

Identificador único del usuario a consultar.

Responses

Response samples

Content type
application/json
Example
{
  • "success": true,
  • "message": "Perfil de usuario obtenido correctamente.",
  • "data": {
    },
  • "errors": [ ],
  • "meta": { },
  • "traceId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Actualizar usuario (Empresarial)

Actualiza parcialmente el perfil de un usuario vinculado a la empresa activa del token. Permite modificar el rol/estado del vínculo y cualquier sección del perfil empresarial: datos personales, documentación legal, direcciones, contactos de emergencia, formación académica, habilidades, experiencia laboral, contrato laboral y horarios de trabajo.

Reglas y Restricciones:

  • Requiere un token empresarial activo.
  • Solo usuarios con rol owner (propietario) o manager (administrador) pueden actualizar perfiles.
  • Un manager no puede actualizar el perfil de un owner.
  • Ningún usuario puede modificar su propio rol.
  • El rol del vínculo puede ser manager, vendor o assistant. No se permite asignar owner.
  • El estado solo puede cambiar entre enabled y disabled. No se permite cambiar a ni desde suspended.
  • No se modifican datos de la cuenta principal (correo, teléfono de cuenta, credenciales).
  • El payload debe incluir al menos un campo modificable. Si está vacío, se retorna error de validación.
  • Secciones únicas (personalData, legalDocumentation, academicFormation, employmentContract): si se envía null, se elimina el registro existente; si no se envía la llave, no se modifica nada.
  • Secciones múltiples (personalAddresses, emergencyContacts, skills, workExperiences, workSchedules): si se envía la llave (incluso con []), reemplaza completamente el contenido anterior.
  • Para prevenir enumeración, se retorna 404 tanto si el usuario no existe como si no pertenece a la empresa activa.
  • El parámetro idUser debe ser un número entero. Si se envía un valor no numérico, la ruta no hace match y se retorna 404.
Authorizations:
bearerAuth
path Parameters
idUser
required
integer
Example: 6

Identificador único del usuario a actualizar.

Request Body schema: application/json
required
object

Datos de la cuenta o vínculo con la empresa. Ignora campos como email o teléfono de la cuenta si se envían.

object

Datos personales del usuario. Si se incluye, nombres y apellidos no pueden quedar vacíos.

object

Documentación legal del usuario.

Array of objects

Lista de direcciones personales. Al enviarse, reemplaza completamente las direcciones anteriores del vínculo.

Array of objects

Lista de contactos de emergencia. Al enviarse, reemplaza completamente los contactos anteriores.

object

Formación académica del usuario.

Array of objects

Lista de habilidades. Al enviarse, reemplaza completamente las anteriores.

Array of objects

Lista de experiencias laborales. Al enviarse, reemplaza completamente las anteriores.

object

Contrato laboral del usuario.

Array of objects

Lista de horarios de trabajo. Al enviarse, reemplaza completamente los anteriores.

Responses

Request samples

Content type
application/json
Example
{
  • "account": {
    },
  • "personalData": {
    },
  • "legalDocumentation": {
    },
  • "personalAddresses": [
    ],
  • "emergencyContacts": [
    ],
  • "academicFormation": {
    },
  • "skills": [
    ],
  • "workExperiences": [
    ],
  • "employmentContract": {
    },
  • "workSchedules": [
    ]
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "Perfil de usuario actualizado correctamente.",
  • "data": {
    },
  • "errors": [ ],
  • "meta": { },
  • "traceId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Obtener perfil de cuenta

Devuelve el perfil completo del usuario autenticado según el tipo de token utilizado:

  • Token Maestro: perfil general de usuario de sistema. company = null, rol y estado desde la cuenta principal.
  • Token Empresarial: perfil del usuario en la empresa activa. Rol, estado y empresa desde el vínculo vigente.
Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
Example
{
  • "success": true,
  • "message": "Perfil de cuenta obtenido correctamente.",
  • "data": {
    },
  • "errors": [ ],
  • "meta": { },
  • "traceId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Actualizar datos personales de la cuenta

Permite al usuario autenticado actualizar sus datos personales básicos (nombre, teléfono, biografía, etc.).

Reglas y Restricciones:

  • Se debe enviar el objeto personalData en el cuerpo de la petición.
  • Los campos pueden ser null o no enviarse si no se desean modificar, excepto si se envía explícitamente vacío un campo requerido lógicamente (ej. no se puede borrar el firstName).
  • Devuelve el perfil completo actualizado con la estructura AccountProfileData.
Authorizations:
bearerAuth
Request Body schema: application/json
required
required
object

Objeto con los datos personales a actualizar.

Responses

Request samples

Content type
application/json
{
  • "personalData": {
    }
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "Datos personales actualizados correctamente.",
  • "data": {
    },
  • "errors": [ ],
  • "meta": { },
  • "traceId": "d4e5f6a7-b8c9-0123-def0-123456789013"
}

Actualizar documentación legal de la cuenta

Permite al usuario autenticado actualizar su documentación legal (tipo de documento, número, nacionalidad, expiración y adjunto).

Reglas y Restricciones:

  • Se debe enviar el objeto legalDocumentation en el cuerpo de la petición con al menos un campo válido.
  • Los campos pueden ser null o no enviarse si no se desean modificar.
  • El campo complement solo es aceptado y persistido si el tipo de documento (type) es CI.
  • Devuelve el perfil completo actualizado con la estructura AccountProfileData.
Authorizations:
bearerAuth
Request Body schema: application/json
required
required
object

Objeto con la documentación legal a actualizar.

Responses

Request samples

Content type
application/json
{
  • "legalDocumentation": {
    }
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "Documentación legal actualizada correctamente.",
  • "data": {},
  • "errors": [ ],
  • "meta": { },
  • "traceId": "d4e5f6a7-b8c9-0123-def0-123456789013"
}

Actualizar direcciones personales de la cuenta

Permite al usuario autenticado reemplazar completamente sus direcciones personales (casa, oficina, facturación, lugar temporal).

Reglas y Restricciones:

  • Se debe enviar el arreglo personalAddresses en el cuerpo de la petición.
  • Esta operación funciona por reemplazo completo. Las direcciones actuales del contexto se eliminan y se reemplazan por las nuevas.
  • Si se envía un arreglo vacío [] o null, se eliminarán todas las direcciones personales del contexto activo.
  • Solo se permite una dirección principal (isPrimary: true) por solicitud.
  • Devuelve el perfil completo actualizado con la estructura AccountProfileData.
Authorizations:
bearerAuth
Request Body schema: application/json
required
required
Array of objects or null

Arreglo de direcciones personales. Si es un arreglo vacío o nulo, se eliminarán todas las direcciones previas.

Responses

Request samples

Content type
application/json
Example
{
  • "personalAddresses": [
    ]
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "Direcciones personales actualizadas correctamente.",
  • "data": {
    },
  • "errors": [ ],
  • "meta": { },
  • "traceId": "d4e5f6a7-b8c9-0123-def0-123456789013"
}

Actualizar contactos de emergencia de la cuenta

Permite al usuario autenticado reemplazar completamente sus contactos de emergencia.

Reglas y Restricciones:

  • Se debe enviar el arreglo emergencyContacts en el cuerpo de la petición.
  • Esta operación funciona por reemplazo completo. Los contactos actuales del contexto se eliminan y se reemplazan por los nuevos.
  • Si se envía un arreglo vacío [] o null, se eliminarán todos los contactos de emergencia del contexto activo.
  • Los nombres y apellidos se enviarán por separado y el sistema se encargará de generar el nombre completo.
  • Devuelve el perfil completo actualizado con la estructura AccountProfileData.
Authorizations:
bearerAuth
Request Body schema: application/json
required
required
Array of objects or null

Arreglo de contactos de emergencia. Si es un arreglo vacío o nulo, se eliminarán todos los contactos previos.

Responses

Request samples

Content type
application/json
Example
{
  • "emergencyContacts": [
    ]
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "Contactos de emergencia actualizados correctamente.",
  • "data": {
    },
  • "errors": [ ],
  • "meta": { },
  • "traceId": "d4e5f6a7-b8c9-0123-def0-123456789013"
}

Actualizar formación académica de la cuenta

Permite al usuario autenticado actualizar parcial o completamente su información de formación académica.

Reglas y Restricciones:

  • La operación funciona por actualización parcial. Los campos omitidos conservarán su valor actual.
  • Si el contexto no tiene un registro previo de formación académica, este se creará automáticamente con los campos proporcionados.
  • La solicitud debe contener al menos un campo modificable.
  • Los campos pueden ser limpiados enviando el valor explícito null.
  • Devuelve el perfil completo actualizado con la estructura AccountProfileData.
Authorizations:
bearerAuth
Request Body schema: application/json
required
required
object

Objeto que contiene los datos de la formación académica.

Responses

Request samples

Content type
application/json
Example
{
  • "academicFormation": {
    }
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "Formación académica actualizada correctamente.",
  • "data": {},
  • "errors": [ ],
  • "meta": { },
  • "traceId": "d4e5f6a7-b8c9-0123-def0-123456789013"
}

Actualizar habilidades de la cuenta

Permite al usuario autenticado reemplazar completamente sus habilidades o conocimientos.

Reglas y Restricciones:

  • Se debe enviar el arreglo skills en el cuerpo de la petición.
  • Esta operación funciona por reemplazo completo. Las habilidades actuales del contexto se eliminan y se reemplazan por las nuevas.
  • Si se envía un arreglo vacío [] o null, se eliminarán todas las habilidades del contexto activo.
  • No se permiten dos habilidades con el mismo nombre en el mismo arreglo.
  • Devuelve el perfil completo actualizado con la estructura AccountProfileData.
Authorizations:
bearerAuth
Request Body schema: application/json
required
required
Array of objects or null

Arreglo de habilidades. Si es un arreglo vacío o nulo, se eliminarán todas las habilidades previas del contexto activo.

Responses

Request samples

Content type
application/json
Example
{
  • "skills": [
    ]
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "Habilidades actualizadas correctamente.",
  • "data": {
    },
  • "errors": [ ],
  • "meta": { },
  • "traceId": "d4e5f6a7-b8c9-0123-def0-123456789013"
}

Actualizar experiencias laborales de la cuenta

Permite al usuario autenticado reemplazar completamente sus experiencias laborales.

Reglas y Restricciones:

  • Se debe enviar el arreglo workExperiences en el cuerpo de la petición.
  • Esta operación funciona por reemplazo completo. Las experiencias actuales del contexto se eliminan y se reemplazan por las nuevas.
  • Si se envía un arreglo vacío [] o null, se eliminarán todas las experiencias del contexto activo.
  • company, position y startDate son obligatorios por cada experiencia.
  • endDate: null indica que la experiencia laboral continúa vigente.
  • endDate no puede ser anterior a startDate.
  • Devuelve el perfil completo actualizado con la estructura AccountProfileData.
Authorizations:
bearerAuth
Request Body schema: application/json
required
required
Array of objects or null

Arreglo de experiencias laborales. Si es un arreglo vacío o nulo, se eliminarán todas las experiencias previas del contexto activo.

Responses

Request samples

Content type
application/json
Example
{
  • "workExperiences": [
    ]
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "Experiencias laborales actualizadas correctamente.",
  • "data": {
    },
  • "errors": [ ],
  • "meta": { },
  • "traceId": "d4e5f6a7-b8c9-0123-def0-123456789013"
}

Consultar resumen del perfil público

Devuelve un resumen del perfil público de un usuario objetivo. Si el usuario objetivo es empresarial, se requiere obligatoriamente el parámetro companyId. Para usuarios de sistema, companyId es ignorado.

Autorización:

  • Se permite el uso de Token Maestro o Token Empresarial.
  • Un Token Maestro puede consultar a cualquier usuario de sistema o empresarial (siempre que pertenezca a la empresa indicada).
  • Un Token Empresarial solo puede consultar a usuarios empresariales que pertenezcan a su misma empresa activa. No puede consultar a usuarios de sistema ni a usuarios de otras empresas.
Authorizations:
bearerAuth
path Parameters
userId
required
integer
Example: 45

Identificador único del usuario objetivo.

query Parameters
companyId
integer
Example: companyId=12

Identificador de la empresa desde la cual se consulta.

  • Obligatorio si el userId pertenece a un usuario empresarial.
  • Ignorado si el userId pertenece a un usuario de sistema.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "Operación exitosa",
  • "data": {},
  • "errors": [ ],
  • "meta": { },
  • "traceId": "729bb1bf-882d-483b-89d3-5855dc5af3aa"
}

Consultar información del perfil público

Devuelve la sección de información del perfil público de un usuario objetivo. Incluye datos básicos de cuenta, datos personales, documentación legal, biografía, direcciones personales y contactos de emergencia.

Si el usuario objetivo es empresarial, se requiere obligatoriamente el parámetro companyId. Para usuarios de sistema, companyId es ignorado.

Autorización:

  • Se permite el uso de Token Maestro o Token Empresarial.
  • Un Token Maestro puede consultar usuarios de sistema o empresariales (con vinculación vigente).
  • Un Token Empresarial solo puede consultar usuarios empresariales de su misma empresa activa. No puede consultar usuarios de sistema ni usuarios de otras empresas.

Reglas de visibilidad:

  • La visibilidad está implícita en la autorización: solo se devuelven datos del contexto autorizado.
  • No se expone ningún dato a consultantes sin autenticación válida.
Authorizations:
bearerAuth
path Parameters
userId
required
integer
Example: 3

Identificador único del usuario objetivo.

query Parameters
companyId
integer
Example: companyId=1

Identificador de la empresa desde la cual se consulta.

  • Obligatorio si el userId pertenece a un usuario empresarial.
  • Ignorado si el userId pertenece a un usuario de sistema.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "Operación exitosa",
  • "data": {
    },
  • "errors": [ ],
  • "meta": { },
  • "traceId": "729bb1bf-882d-483b-89d3-5855dc5af3aa"
}

Consultar experiencia del perfil público

Devuelve la sección de experiencia del perfil público de un usuario objetivo. Incluye datos básicos de cuenta, formación académica, descripción académica, habilidades (skills) y experiencia laboral ordenada descendentemente por fecha de inicio.

Si el usuario objetivo es empresarial, se requiere obligatoriamente el parámetro companyId. Para usuarios de sistema, companyId es ignorado.

Autorización:

  • Se permite el uso de Token Maestro o Token Empresarial.
  • Un Token Maestro puede consultar usuarios de sistema o empresariales (con vinculación vigente).
  • Un Token Empresarial solo puede consultar usuarios empresariales de su misma empresa activa. No puede consultar usuarios de sistema ni usuarios de otras empresas.

Reglas de visibilidad:

  • La visibilidad está implícita en la autorización: solo se devuelven datos del contexto autorizado.
  • No se expone ningún dato a consultantes sin autenticación válida.
Authorizations:
bearerAuth
path Parameters
userId
required
integer
Example: 3

Identificador único del usuario objetivo.

query Parameters
companyId
integer
Example: companyId=1

Identificador de la empresa desde la cual se consulta.

  • Obligatorio si el userId pertenece a un usuario empresarial.
  • Ignorado si el userId pertenece a un usuario de sistema.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "Operación exitosa",
  • "data": {
    },
  • "errors": [ ],
  • "meta": { },
  • "traceId": "729bb1bf-882d-483b-89d3-5855dc5af3aa"
}

Consultar empresas del perfil público

Devuelve la sección de empresas del perfil público de un usuario objetivo. Incluye datos básicos de cuenta y un listado de las empresas en las que tiene vinculación vigente. Para cada empresa, devuelve datos institucionales, contrato, horarios y un listado de sus miembros (hasta 300).

Si el usuario objetivo es empresarial, se requiere obligatoriamente el parámetro companyId. Para usuarios de sistema, companyId es ignorado.

Autorización e Intersección:

  • Se permite el uso de Token Maestro o Token Empresarial.
  • Un Token Maestro obtiene TODAS las empresas en las que el usuario objetivo está vinculado y habilitado.
  • Un Token Empresarial solo obtiene la intersección de empresas; es decir, aquellas en las que tanto el consultante como el usuario objetivo comparten una vinculación habilitada.

Reglas de visibilidad:

  • La visibilidad está implícita en la autorización y la intersección. No se expone información de otras empresas al consultante empresarial.
Authorizations:
bearerAuth
path Parameters
userId
required
integer
Example: 3

Identificador único del usuario objetivo.

query Parameters
companyId
integer
Example: companyId=1

Identificador de la empresa desde la cual se consulta.

  • Obligatorio si el userId pertenece a un usuario empresarial.
  • Ignorado si el userId pertenece a un usuario de sistema.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "Operación exitosa",
  • "data": {
    },
  • "errors": [ ],
  • "meta": { },
  • "traceId": "729bb1bf-882d-483b-89d3-5855dc5af3aa"
}

Consultar cuenta del perfil público

Devuelve la sección de cuenta del perfil público de un usuario objetivo. El nivel de información (completo o detalle) se determina dinámicamente según el rol y la identidad del consultante.

Si el usuario objetivo es empresarial, se requiere obligatoriamente el parámetro companyId. Para usuarios de sistema, companyId es ignorado.

Niveles de Acceso:

  • full (Completo): Devuelve el detalle de la cuenta, plataformas conectadas, sesiones activas y dispositivos activos. Otorgado a: Token Maestro, perfiles propios, Propietarios y Administradores (de la misma empresa).
  • detail (Detalle): Devuelve solo el detalle de la cuenta. Las plataformas, sesiones y dispositivos se omiten (se envían como null). Otorgado a: Vendedores y Auxiliares (de la misma empresa consultando a otro miembro).

Reglas de autorización:

  • Un Token Empresarial solo puede consultar usuarios de su misma empresa activa. Intentar consultar a un usuario de sistema o de otra empresa retornará un 403 Forbidden.
Authorizations:
bearerAuth
path Parameters
userId
required
integer
Example: 3

Identificador único del usuario objetivo.

query Parameters
companyId
integer
Example: companyId=1

Identificador de la empresa desde la cual se consulta.

  • Obligatorio si el userId pertenece a un usuario empresarial.
  • Ignorado si el userId pertenece a un usuario de sistema.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "Operación exitosa",
  • "data": {
    },
  • "errors": [ ],
  • "meta": { },
  • "traceId": "729bb1bf-882d-483b-89d3-5855dc5af3aa"
}

Consultar actividad del perfil público

Devuelve la sección de actividad del perfil público de un usuario objetivo.

En esta primera versión, la sección activity siempre devuelve un arreglo vacío []. La clave existe obligatoriamente en la respuesta para permitir futuras integraciones sin romper el contrato.

Si el usuario objetivo es empresarial, se requiere obligatoriamente el parámetro companyId. Si el usuario objetivo es de sistema, el parámetro companyId es ignorado.

Reglas de autorización:

  • Token Maestro: puede consultar perfiles de usuarios de sistema y empresariales.
  • Token Empresarial: solo puede consultar usuarios de su misma empresa activa. Intentar consultar un usuario de sistema o de otra empresa retornará 403 Forbidden.
Authorizations:
bearerAuth
path Parameters
userId
required
integer
Example: 3

Identificador único del usuario objetivo.

query Parameters
companyId
integer
Example: companyId=1

Identificador de la empresa desde la cual se consulta.

  • Obligatorio si el userId pertenece a un usuario empresarial.
  • Ignorado si el userId pertenece a un usuario de sistema.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "Operación exitosa",
  • "data": {
    },
  • "errors": [ ],
  • "meta": { },
  • "traceId": "729bb1bf-882d-483b-89d3-5855dc5af3aa"
}

Sucursales

Endpoints de gestión de sucursales. Incluye listados empresariales y operaciones relacionadas con las sucursales de una empresa.

Listado Rápido de Sucursales (Empresarial)

Obtiene un listado rápido de las sucursales pertenecientes a la empresa activa. Está optimizado para selectores tipo "combobox" o listas con scroll infinito, retornando un contrato reducido con solo ID, nombre, dirección completa y banner. Utiliza paginación por cursor para un rendimiento óptimo.

Authorizations:
bearerAuth
query Parameters
search
string
Example: search=Central

Término de búsqueda parcial aplicado sobre el nombre de la sucursal.

sortBy
string
Enum: "id" "name"
Example: sortBy=name

Campo por el cual ordenar el listado. Por defecto es name.

sortDirection
string
Enum: "asc" "desc"
Example: sortDirection=asc

Dirección del ordenamiento. Por defecto es asc.

limit
integer
Default: 5
Example: limit=10

Cantidad máxima de resultados a retornar en esta solicitud (entre 5 y 25). Por defecto es 5.

cursor
string
Example: cursor=eyJpdiI6IkhDOHVwTkdMOWs0bSIsIm1hYyI6IjFiMjMz...=

Cursor opaco y encriptado para obtener la siguiente página de resultados. Debe enviarse exactamente el valor devuelto en meta.pagination.nextCursor de la solicitud anterior.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "Listado rápido de sucursales obtenido correctamente.",
  • "data": [],
  • "errors": [ ],
  • "meta": {
    },
  • "traceId": "b8c3e4d5-f6a7-8b9c-0d1e-2f3a4b5c6d7e"
}

Registrar nueva sucursal

Crea una nueva sucursal para la empresa activa del usuario autenticado. El acceso está restringido a usuarios con rol owner o manager.

Se permite un registro mínimo (solo campos obligatorios) o un registro completo que incluye características, servicios, galería de imágenes ordenadas y horarios de atención. Toda la operación se realiza de forma transaccional.

Authorizations:
bearerAuth
Request Body schema: application/json
required

Cuerpo de la petición para registrar una nueva sucursal.

name
required
string <= 120 characters

Nombre de la sucursal.

department
required
string <= 120 characters

Departamento donde se encuentra la sucursal.

province
string or null <= 120 characters

Provincia donde se encuentra la sucursal.

neighborhood
required
string <= 120 characters

Barrio donde se ubica la sucursal.

avenue
required
string <= 120 characters

Avenida principal de acceso.

street
required
string <= 120 characters

Calle exacta.

building
string or null <= 120 characters

Nombre del edificio (si aplica).

floor
string or null <= 120 characters

Piso del edificio (si aplica).

number
required
string <= 60 characters

Número de puerta o local.

latitude
number or null <float>

Latitud geográfica (entre -90 y 90). Requerido si se envía longitud.

longitude
number or null <float>

Longitud geográfica (entre -180 y 180). Requerido si se envía latitud.

banner
string or null <= 240 characters

Referencia al nombre del archivo del banner. Debe tener extensión jpg, jpeg o png.

phone
string or null <= 24 characters

Teléfono de contacto de la sucursal.

features
Array of strings or null

Lista de características de la sucursal.

services
Array of strings or null

Lista de servicios ofrecidos.

isMain
required
boolean

Indica si es la sucursal principal de la empresa.

state
required
string
Enum: "enabled" "disabled" "suspended"

Estado operativo.

Array of objects or null

Galería de imágenes de la sucursal.

Array of objects or null

Horarios de atención.

Responses

Request samples

Content type
application/json
{
  • "name": "Sucursal Norte",
  • "department": "Santa Cruz",
  • "province": "Andrés Ibáñez",
  • "neighborhood": "Equipetrol",
  • "avenue": "San Martín",
  • "street": "Calle 3",
  • "building": "Torre Norte",
  • "floor": "2",
  • "number": "210",
  • "latitude": -17.783333,
  • "longitude": -63.182222,
  • "banner": "banner_norte.jpg",
  • "phone": "+59133456789",
  • "features": [
    ],
  • "services": [
    ],
  • "isMain": true,
  • "state": "enabled",
  • "images": [
    ],
  • "schedules": [
    ]
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "Operación exitosa",
  • "data": {
    },
  • "errors": [ ],
  • "meta": { },
  • "traceId": "729bb1bf-882d-483b-89d3-5855dc5af3aa"
}

Listado de sucursales de la empresa

Devuelve un listado paginado de las sucursales pertenecientes a la empresa activa del usuario autenticado.

Permite filtrar por búsqueda general, departamento, estado y actividad, así como ordenar por múltiples campos. Solo accesible para usuarios con roles owner o manager.

Authorizations:
bearerAuth
query Parameters
search
string
Example: search=El termino a buscar

Término de búsqueda para filtrar los resultados.

department
string <= 120 characters

Filtra las sucursales por nombre de departamento exacto.

activity
string
Enum: "open" "closed" "not_specified"

Filtra las sucursales por su actividad actual (calculado en base al horario y estado).

state
string
Enum: "enabled" "disabled" "suspended"

Filtra las sucursales por su estado operativo.

sortBy
string
Enum: "name" "department" "fullAddress" "phone" "state" "updatedAt"

Campo por el cual ordenar los resultados.

sortDirection
string
Default: "asc"
Enum: "asc" "desc"

Dirección de ordenamiento.

page
integer >= 1
Default: 1

Número de la página para la paginación.

per_page
integer [ 1 .. 100 ]
Default: 10

Cantidad de elementos por página.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "Listado de sucursales obtenido correctamente.",
  • "data": [
    ],
  • "meta": {
    }
}

Obtener detalle de una sucursal de la empresa activa.

Devuelve la información completa de una sucursal perteneciente a la empresa del usuario autenticado. Requiere rol de propietario (owner) o administrador (manager).

Authorizations:
bearerAuth
path Parameters
branchId
required
integer >= 1

Identificador único de la sucursal

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "Detalle de sucursal obtenido correctamente.",
  • "data": {
    },
  • "errors": [ ],
  • "meta": { },
  • "traceId": "550e8400-e29b-41d4-a716-446655440000"
}

Actualizar sucursal

Actualiza una sucursal perteneciente a la empresa activa del usuario autenticado. El acceso está restringido a usuarios con rol owner o manager.

Permite actualización parcial o completa. Los campos omitidos conservan su valor actual, mientras que enviar null (en los campos que lo soportan) elimina su valor. Las colecciones (imágenes, horarios, características, servicios) se reemplazan completamente cuando se envían, y se eliminan por completo al enviar un arreglo vacío [] o null.

Authorizations:
bearerAuth
path Parameters
branchId
required
integer

ID de la sucursal a actualizar.

Request Body schema: application/json
required

Cuerpo de la petición para actualizar una sucursal existente. Todos los campos son opcionales. Omitir un campo conserva su valor actual, mientras que enviar null en campos que lo soportan eliminará el valor.

name
string <= 120 characters

Nombre de la sucursal. Si se envía, no puede ser vacío.

department
string <= 120 characters

Departamento donde se encuentra la sucursal.

province
string or null <= 120 characters

Provincia donde se encuentra la sucursal. null elimina el valor.

neighborhood
string <= 120 characters

Barrio donde se ubica la sucursal.

avenue
string <= 120 characters

Avenida principal de acceso.

street
string <= 120 characters

Calle exacta.

building
string or null <= 120 characters

Nombre del edificio (si aplica). null elimina el valor.

floor
string or null <= 120 characters

Piso del edificio (si aplica). null elimina el valor.

number
string <= 60 characters

Número de puerta o local.

latitude
number or null <float>

Latitud geográfica (entre -90 y 90).

longitude
number or null <float>

Longitud geográfica (entre -180 y 180).

banner
string or null <= 240 characters

Referencia al nombre del archivo del banner. Debe tener extensión jpg, jpeg o png. null elimina el banner.

phone
string or null <= 24 characters

Teléfono de contacto de la sucursal. null elimina el valor.

features
Array of strings or null

Lista de características. Reemplaza la colección completa. null o [] eliminan todas las características.

services
Array of strings or null

Lista de servicios ofrecidos. Reemplaza la colección completa. null o [] eliminan todos los servicios.

isMain
boolean

Indica si es la sucursal principal de la empresa. No admite null.

state
string
Enum: "enabled" "disabled"

Estado operativo. No se permite transicionar desde/hacia suspended.

Array of objects or null

Galería de imágenes. Reemplaza la colección completa. null o [] eliminan todas las imágenes.

Array of objects or null

Horarios de atención. Reemplaza la colección completa. null o [] eliminan todos los horarios.

Responses

Request samples

Content type
application/json
{
  • "name": "Sucursal Norte VIP Renovada",
  • "department": "Santa Cruz",
  • "province": "Andrés Ibáñez",
  • "neighborhood": "Equipetrol Norte",
  • "avenue": "Cuarto Anillo",
  • "street": "Calle 4",
  • "building": "Torre Empresarial VIP",
  • "floor": "Piso 2",
  • "number": "500-B",
  • "latitude": -17.780123,
  • "longitude": -63.180234,
  • "phone": "+59177777777",
  • "isMain": false,
  • "state": "disabled",
  • "banner": "ofertas_verano_2026.png",
  • "features": [
    ],
  • "services": [
    ],
  • "images": [
    ],
  • "schedules": [
    ]
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "Operación exitosa",
  • "data": {
    },
  • "errors": [ ],
  • "meta": { },
  • "traceId": "729bb1bf-882d-483b-89d3-5855dc5af3aa"
}

Eliminar sucursal

Elimina permanentemente una sucursal perteneciente a la empresa activa del usuario autenticado. Esta operación es destructiva y eliminará en cascada las imágenes y horarios relacionados de la sucursal.

Solo accesible para usuarios con el rol owner.

Authorizations:
bearerAuth
path Parameters
branchId
required
integer

Identificador numérico de la sucursal a eliminar.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "Operación exitosa",
  • "data": {
    },
  • "errors": [ ],
  • "meta": { },
  • "traceId": "729bb1bf-882d-483b-89d3-5855dc5af3aa"
}

Puntos de venta

Endpoints de gestión de puntos de venta. Incluye listados empresariales y operaciones relacionadas con los puntos de venta de una empresa.

Listar puntos de venta

Obtiene el listado paginado de los puntos de venta de la empresa activa del usuario. Permite filtrar por nombre, sucursal, actividad y estado, además de ordenamiento.

Authorizations:
bearerAuth
query Parameters
search
string <= 255 characters

Búsqueda por nombre del punto de venta o nombre completo del responsable de la sesión actual.

branchId
integer >= 1

Filtra por el ID de la sucursal.

activity
string
Enum: "open" "closed"

Filtra por actividad (depende de si existe una sesión de caja abierta actualmente).

state
string
Enum: "enabled" "disabled" "suspended"

Filtra por el estado del punto de venta.

sortBy
string
Default: "name"
Enum: "name" "branchId" "activity" "openedAt" "openedBy" "state" "updatedAt"

Columna por la cual ordenar los resultados.

sortDirection
string
Default: "asc"
Enum: "asc" "desc"

Dirección del ordenamiento.

page
integer >= 1
Default: 1

Número de página para la paginación.

perPage
integer
Default: 10
Enum: 5 10 25 50 100

Cantidad de resultados por página permitidos.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "Operación exitosa",
  • "data": [
    ],
  • "errors": [ ],
  • "meta": {
    },
  • "traceId": "729bb1bf-882d-483b-89d3-5855dc5af3aa"
}

Listado rápido de Puntos de Venta (Empresa)

Obtiene un listado optimizado de puntos de venta de la empresa activa, devolviendo únicamente la información mínima necesaria (id, name, branchName).

Características clave:

  • Contrato reducido: Devuelve solo id, name y el nombre de la sucursal (branchName como cadena directa).
  • Paginación eficiente: Utiliza cursor para mantener un rendimiento óptimo en listas largas.
  • Búsqueda parcial: Permite filtrar puntos de venta por coincidencia parcial en el nombre.
  • Ordenamiento estable: Soporta ordenamiento por id o name, con manejo de colisiones interno.

Nota: Este endpoint es útil para selects, typeaheads o vistas colapsadas donde no se requiere toda la información detallada del punto de venta.

Authorizations:
bearerAuth
query Parameters
search
string <= 120 characters
Example: search=Caja

Término de búsqueda para filtrar puntos de venta. Realiza una búsqueda parcial (LIKE %search%) sobre el campo name.

sortBy
string
Default: "name"
Enum: "id" "name"
Example: sortBy=name

Columna por la cual ordenar los resultados.

sortDirection
string
Default: "asc"
Enum: "asc" "desc"
Example: sortDirection=asc

Dirección del ordenamiento.

limit
integer [ 5 .. 25 ]
Default: 5
Example: limit=10

Número máximo de elementos a devolver por página.

  • Mínimo: 5
  • Máximo: 25
cursor
string <= 500 characters
Example: cursor=eyJsYXN0VmFsdWUiOiJDYWphIFByaW5jaXBhbCIsImxhc3RJZCI6MX0=

Cursor opaco para obtener la siguiente página de resultados. Este valor debe ser exactamente el mismo string devuelto en el campo nextCursor de la petición anterior.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "Petición procesada exitosamente.",
  • "data": {
    },
  • "errors": [ ],
  • "meta": { },
  • "traceId": "982365c3-644b-4307-9d11-44a23e7f6cd3"
}

Registrar Punto de Venta (Empresa)

Registra un nuevo punto de venta en una sucursal de la empresa activa. Requiere token de empresarial y rol de owner, manager, o vendor.

Authorizations:
bearerAuth
Request Body schema: application/json
required
name
required
string <= 120 characters

Nombre del punto de venta. No vacío, max 120 caracteres.

branchId
required
integer >= 1

Identificador de la sucursal activa.

description
required
string <= 240 characters

Descripción del punto de venta.

type
required
string
Enum: "fixed" "mobile"

Tipo de punto de venta. Para 'mobile' la ubicación operativa es obligatoria.

isMain
required
boolean

Indica si es el punto de venta principal de la sucursal.

state
required
string
Enum: "enabled" "disabled"

Estado del punto de venta. No se permite crear en estado suspendido.

neighborhood
string <= 120 characters

Barrio. Obligatorio si type = mobile.

avenue
string <= 120 characters

Avenida. Obligatorio si type = mobile.

street
string <= 120 characters

Calle. Obligatorio si type = mobile.

building
string <= 120 characters

Edificio. Opcional.

floor
string <= 120 characters

Piso. Opcional.

number
string <= 60 characters

Número. Obligatorio si type = mobile.

latitude
number <float> [ -90 .. 90 ]

Latitud. Obligatorio si se envía longitud.

longitude
number <float> [ -180 .. 180 ]

Longitud. Obligatorio si se envía latitud.

Responses

Request samples

Content type
application/json
{
  • "name": "Caja Principal - Planta Baja",
  • "branchId": 1,
  • "description": "Caja principal para cobros en efectivo y tarjeta.",
  • "type": "fixed",
  • "isMain": true,
  • "state": "enabled",
  • "neighborhood": "Equipetrol",
  • "avenue": "Av. San Martín",
  • "street": "Calle 3 Oeste",
  • "building": "Edificio Torre Sur",
  • "floor": "Planta Baja",
  • "number": "245",
  • "latitude": -17.75549,
  • "longitude": -63.19794
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "Operación exitosa",
  • "data": {
    },
  • "errors": [ ],
  • "meta": { },
  • "traceId": "729bb1bf-882d-483b-89d3-5855dc5af3aa"
}

Obtener detalle de punto de venta

Devuelve la información detallada de un punto de venta. El punto de venta debe pertenecer a la empresa activa del usuario autenticado.

Incluye un mapeo completo del punto de venta, mapeo parcial de la sucursal y la sesión actualmente abierta si existe, con cálculos de duración y saldos.

Authorizations:
bearerAuth
path Parameters
pointOfSaleId
required
integer >= 1

Identificador único del punto de venta.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "Operación exitosa",
  • "data": {
    },
  • "errors": [ ],
  • "meta": { },
  • "traceId": "729bb1bf-882d-483b-89d3-5855dc5af3aa"
}

Actualizar punto de venta

Actualiza de forma parcial o total la información de un punto de venta. El punto de venta debe pertenecer a la empresa activa del usuario autenticado.

No se puede actualizar el punto de venta si tiene una sesión de caja abierta actualmente. Tampoco se puede cambiar la sucursal a la que pertenece ni actualizar a estado suspendido. Los campos obligatorios dependen del tipo (fijo o móvil) resultante después de la actualización.

Authorizations:
bearerAuth
path Parameters
pointOfSaleId
required
integer >= 1

Identificador único del punto de venta.

Request Body schema: application/json
required

Al menos un campo debe estar presente en el cuerpo de la solicitud.

name
string <= 120 characters

Nombre del punto de venta. Si se envía, no debe estar vacío.

description
string <= 240 characters

Descripción del punto de venta.

type
string
Enum: "fixed" "mobile"

Tipo de punto de venta. Para 'mobile' la ubicación operativa será obligatoria.

isMain
boolean

Indica si es el punto de venta principal de la sucursal.

state
string
Enum: "enabled" "disabled" "suspended"

Estado del punto de venta. No se permite actualizar a estado 'suspended'.

neighborhood
string or null <= 120 characters

Barrio. Si el tipo final es móvil, será obligatorio.

avenue
string or null <= 120 characters

Avenida. Si el tipo final es móvil, será obligatorio.

street
string or null <= 120 characters

Calle. Si el tipo final es móvil, será obligatorio.

building
string or null <= 120 characters

Edificio. Opcional.

floor
string or null <= 120 characters

Piso. Opcional.

number
string or null <= 60 characters

Número. Si el tipo final es móvil, será obligatorio.

latitude
number or null <float> [ -90 .. 90 ]

Latitud. Obligatorio si se envía longitud.

longitude
number or null <float> [ -180 .. 180 ]

Longitud. Obligatorio si se envía latitud.

Responses

Request samples

Content type
application/json
{
  • "name": "Caja Principal - Planta Baja",
  • "description": "Caja principal para cobros en efectivo y tarjeta.",
  • "type": "fixed",
  • "isMain": true,
  • "state": "enabled",
  • "neighborhood": "Equipetrol",
  • "avenue": "Av. San Martín",
  • "street": "Calle 3 Oeste",
  • "building": "Edificio Torre Sur",
  • "floor": "Planta Baja",
  • "number": "245",
  • "latitude": -17.75549,
  • "longitude": -63.19794
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "Operación exitosa",
  • "data": {
    },
  • "errors": [ ],
  • "meta": { },
  • "traceId": "729bb1bf-882d-483b-89d3-5855dc5af3aa"
}

Eliminar punto de venta

Elimina físicamente un punto de venta perteneciente a la empresa activa. Esta operación también eliminará en cascada las sesiones históricas (cerradas) asociadas a este punto.

Restricciones:

  • Solo el rol propietario (owner) puede ejecutar esta acción.
  • No se puede eliminar si existe una sesión de caja actualmente abierta.
Authorizations:
bearerAuth
path Parameters
pointOfSaleId
required
integer >= 1

Identificador único del punto de venta a eliminar.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "Operación exitosa",
  • "data": {
    },
  • "errors": [ ],
  • "meta": { },
  • "traceId": "729bb1bf-882d-483b-89d3-5855dc5af3aa"
}

Registrar apertura de sesión de Punto de Venta (Empresa)

Registra la apertura de sesión de un punto de venta perteneciente a la empresa activa. Requiere token empresarial y rol de owner, manager o vendor. El rol assistant no tiene permitido abrir sesiones.

Reglas de negocio:

  • El punto de venta debe pertenecer a la empresa, estar habilitado y no tener una sesión abierta.
  • El responsable asignado debe pertenecer a la empresa, estar habilitado, no ser assistant y no tener otra sesión abierta.
  • owner: Puede asignar a cualquier usuario elegible de la empresa.
  • manager: Puede asignarse a sí mismo o a cualquier vendedor.
  • vendor: Solo puede asignarse a sí mismo.
Authorizations:
bearerAuth
Request Body schema: application/json
required
pointOfSale
required
integer >= 1

Identificador del punto de venta.

responsible
required
integer >= 1

Identificador del usuario responsable asignado a la sesión de caja.

openingAmount
required
number <float> >= 0

Monto de apertura en la moneda principal. Debe ser mayor o igual a 0.

note
string <= 500 characters

Nota opcional sobre la apertura.

Responses

Request samples

Content type
application/json
{
  • "pointOfSale": 1,
  • "responsible": 5,
  • "openingAmount": 5000,
  • "note": "Apertura de turno matutino con fondo chico."
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "Operación exitosa",
  • "data": {
    },
  • "errors": [ ],
  • "meta": { },
  • "traceId": "729bb1bf-882d-483b-89d3-5855dc5af3aa"
}

Registrar cierre de sesión de Punto de Venta (Empresa)

Registra el cierre de una sesión abierta de punto de venta. Requiere token empresarial y rol de owner, manager o vendor. El rol assistant no tiene permitido cerrar sesiones.

Reglas de negocio:

  • La sesión debe pertenecer a la empresa activa, ser la sesión actual y estar en estado abierto.
  • El owner puede cerrar cualquier sesión activa de la empresa.
  • El manager puede cerrar sesiones donde él mismo sea el responsable, o donde el responsable tenga rol vendor. No puede cerrar sesiones de propietarios ni de otros administradores.
  • El vendor solo puede cerrar su propia sesión.
  • La operación generará valores mock aleatorios para incomeAmount y expenseAmount hasta la futura integración de la caja.
  • El finalBalance se calcula automáticamente: openingAmount + incomeAmount - expenseAmount.
  • La operación es transaccional; si falla por cualquier motivo, la sesión permanecerá sin cambios.
Authorizations:
bearerAuth
path Parameters
sessionId
required
integer >= 1

Identificador de la sesión de punto de venta a cerrar.

Request Body schema: application/json
optional
note
string <= 500 characters

Nota opcional de cierre de sesión.

Responses

Request samples

Content type
application/json
{
  • "note": "Cierre de turno vespertino sin novedades."
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "Operación exitosa",
  • "data": {
    },
  • "errors": [ ],
  • "meta": { },
  • "traceId": "729bb1bf-882d-483b-89d3-5855dc5af3aa"
}

Historial de actividad de puntos de venta (Empresa)

Obtiene el listado paginado de sesiones de puntos de venta de la empresa activa. Requiere token empresarial y rol permitido (owner, manager, vendor, assistant). Permite filtrar por gestión (obligatorio), búsqueda general, punto de venta, estado, tipo de saldo y ordenar.

Authorizations:
bearerAuth
query Parameters
fiscalYear
required
integer
Example: fiscalYear=2026

Gestión a consultar (año de 4 dígitos). Filtra la fecha de cierre (sesiones cerradas) o fecha de apertura (sesiones abiertas).

search
string
Example: search=El termino a buscar

Término de búsqueda para filtrar los resultados.

pointOfSale
integer >= 1

Filtra por el ID del punto de venta.

balanceType
string
Enum: "positive" "negative" "neutral"

Filtra por tipo de saldo (calculado como openingAmount + incomeAmount - expenseAmount).

state
string
Enum: "open" "closed"

Filtra por el estado de la sesión.

sortBy
string
Default: "updatedAt"
Enum: "code" "pointOfSale" "responsible" "openedAt" "closedAt" "openingAmount" "currentBalance" "state" "updatedAt"

Columna por la cual ordenar los resultados.

sort
string
Example: sort=created_at,desc

Campo por el cual ordenar seguido de su dirección (asc o desc). Ejemplo: nombre,asc

page
integer >= 1
Default: 1

Número de la página para la paginación.

per_page
integer [ 1 .. 100 ]
Default: 10

Cantidad de elementos por página.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "Operación exitosa",
  • "data": [
    ],
  • "errors": [ ],
  • "meta": {
    },
  • "traceId": "729bb1bf-882d-483b-89d3-5855dc5af3aa"
}

Categorías

Endpoints de gestión de categorias. Incluye listados empresariales y operaciones relacionadas con las categorías y subcategorías para los productos de una empresa.

Listado Rápido de Categorías (Empresarial)

Obtiene un listado rápido de las categorías pertenecientes a la empresa activa. Está optimizado para selectores tipo "combobox" o listas con scroll infinito, retornando un contrato reducido con solo ID, nombre, código e ícono. Utiliza paginación por cursor para un rendimiento óptimo.

Authorizations:
bearerAuth
query Parameters
search
string
Example: search=Bebidas

Término de búsqueda parcial aplicado sobre el nombre y el código de la categoría.

type
string
Default: "all"
Enum: "all" "parents" "subcategories"
Example: type=all

Filtro para devolver todas las categorías, solo padres o solo subcategorías. Por defecto es all.

sortBy
string
Default: "name"
Enum: "id" "name"
Example: sortBy=name

Campo por el cual ordenar el listado. Por defecto es name.

sortDirection
string
Default: "asc"
Enum: "asc" "desc"
Example: sortDirection=asc

Dirección del ordenamiento. Por defecto es asc.

limit
integer [ 5 .. 25 ]
Default: 5
Example: limit=10

Cantidad máxima de resultados a retornar en esta solicitud (entre 5 y 25). Por defecto es 5.

cursor
string
Example: cursor=eyJpdiI6IkhDOHVwTkdMOWs0bSIsIm1hYyI6IjFiMjMz...=

Cursor opaco y encriptado para obtener la siguiente página de resultados. Debe enviarse exactamente el valor devuelto en meta.pagination.nextCursor de la solicitud anterior.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "Listado rápido de categorías obtenido correctamente.",
  • "data": [],
  • "errors": [ ],
  • "meta": {
    },
  • "traceId": "b8c3e4d5-f6a7-8b9c-0d1e-2f3a4b5c6d7e"
}

Listar categorías

Obtiene un listado paginado de las categorías y subcategorías pertenecientes a la empresa activa del usuario. Permite filtrar por categoría padre, visibilidad y estado, así como buscar por código o nombre y ordenar los resultados. El listado solo incluirá categorías de la empresa asociada al token activo.

Roles permitidos: propietario, administrador, vendedor, auxiliar.

Authorizations:
bearerAuth
query Parameters
search
string

Término de búsqueda que aplica coincidencia parcial sobre el código o el nombre de la categoría (máx. 255 caracteres).

categoryId
integer

ID de la categoría padre. Retorna las subcategorías cuyo padre coincide con este ID.

visibility
string
Enum: "visible" "hidden"

Filtra por visibilidad en ventas.

state
string
Enum: "enabled" "disabled" "suspended"

Filtra por el estado de la categoría.

sortBy
string
Default: "updatedAt"
Enum: "code" "name" "category" "order" "visibility" "products" "state" "updatedAt"

Nombre del campo por el cual ordenar los resultados.

sortDirection
string
Default: "desc"
Enum: "asc" "desc"

Dirección del ordenamiento.

page
integer
Default: 1

Número de página para la paginación de resultados.

perPage
integer
Default: 10
Enum: 5 10 25 50 100

Cantidad de resultados a devolver por página.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "Operación exitosa",
  • "data": [
    ],
  • "errors": [ ],
  • "meta": {
    },
  • "traceId": "729bb1bf-882d-483b-89d3-5855dc5af3aa"
}

Registrar categoría

Registra una nueva categoría (raíz o subcategoría) asociada a la empresa activa del usuario. Si se proporciona parentId, se registrará como una subcategoría; de lo contrario, será una categoría raíz.

Restricciones:

  • Solo los roles propietario (owner) y administrador (manager) pueden registrar categorías.
  • El código de la categoría debe ser único dentro de la empresa.
  • El estado inicial solo puede ser enabled o disabled.
Authorizations:
bearerAuth
Request Body schema: application/json
required
parentId
integer

ID de la categoría padre (si es subcategoría).

code
required
string

Código único de la categoría dentro de la empresa (máx. 120 caracteres).

name
required
string

Nombre visible de la categoría (máx. 120 caracteres).

description
string

Descripción opcional de la categoría (máx. 240 caracteres).

order
required
integer

Orden de visualización de la categoría.

visibility
required
string
Enum: "visible" "hidden"

Visibilidad de la categoría en ventas.

state
required
string
Enum: "enabled" "disabled"

Estado inicial de la categoría.

color
string

Color hexadecimal de la categoría.

icon
string

Nombre del archivo de ícono (debe tener extensión .jpg, .jpeg o .png).

Responses

Request samples

Content type
application/json
{
  • "parentId": 1,
  • "code": "BEB-001",
  • "name": "Bebidas",
  • "description": "Todas las bebidas disponibles.",
  • "order": 1,
  • "visibility": "visible",
  • "state": "enabled",
  • "color": "#3498DB",
  • "icon": "bebidas.png"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "Operación exitosa",
  • "data": {
    },
  • "errors": [ ],
  • "meta": { },
  • "traceId": "729bb1bf-882d-483b-89d3-5855dc5af3aa"
}

Obtener detalle de categoría

Obtiene el detalle completo de una categoría perteneciente a la empresa activa. Disponible para los roles: owner, manager, vendor, assistant.

Authorizations:
bearerAuth
path Parameters
categoryId
required
integer >= 1

Identificador único de la categoría.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "Detalle de categoría obtenido correctamente.",
  • "data": {
    },
  • "errors": [ ],
  • "meta": { },
  • "traceId": "550e8400-e29b-41d4-a716-446655440000"
}

Actualizar categoría

Actualiza una categoría existente dentro de la empresa activa. Se permite actualización parcial; solo los campos enviados serán modificados.

Restricciones:

  • Solo el rol propietario (owner) y administrador (manager) pueden ejecutar esta acción.
  • La categoría debe pertenecer a la empresa activa.
  • La categoría padre no puede modificarse en ningún caso.
  • No se puede cambiar al estado "suspendido", ni modificar una categoría suspendida.
Authorizations:
bearerAuth
path Parameters
categoryId
required
integer >= 1

Identificador único de la categoría a actualizar.

Request Body schema: application/json
required
code
string <= 120 characters

Código único de la categoría en la empresa.

name
string <= 120 characters

Nombre de la categoría.

description
string or null <= 240 characters

Descripción opcional. Enviar null para limpiarla.

order
integer [ 1 .. 255 ]

Orden de aparición de la categoría.

visibility
string
Enum: "visible" "hidden"

Visibilidad para ventas.

state
string
Enum: "enabled" "disabled"

Estado de la categoría. No se permite enviar suspended.

color
string or null

Color en formato hexadecimal. Enviar null para limpiarlo.

icon
string or null

Nombre de archivo de la imagen de ícono (ej. icon.png). Enviar null para limpiarlo.

Responses

Request samples

Content type
application/json
{
  • "code": "CAT-001",
  • "name": "Electrónica",
  • "description": "Productos electrónicos",
  • "order": 1,
  • "visibility": "visible",
  • "state": "enabled",
  • "color": "#FF5733",
  • "icon": "icon.png"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "Operación exitosa",
  • "data": {
    },
  • "errors": [ ],
  • "meta": { },
  • "traceId": "729bb1bf-882d-483b-89d3-5855dc5af3aa"
}

Eliminar categoría

Elimina físicamente una categoría existente dentro de la empresa activa del usuario. Esta operación eliminará en cascada las subcategorías dependientes (y todos sus descendientes), respetando la jerarquía.

Restricciones:

  • Solo el rol propietario (owner) puede ejecutar esta acción.
  • La categoría debe pertenecer a la empresa activa.
Authorizations:
bearerAuth
path Parameters
categoryId
required
integer >= 1

Identificador único de la categoría a eliminar.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "Operación exitosa",
  • "data": {
    },
  • "errors": [ ],
  • "meta": { },
  • "traceId": "729bb1bf-882d-483b-89d3-5855dc5af3aa"
}

Productos

Endpoints de gestión de productos. Incluye operaciones para el registro de productos, variantes e imágenes en el catálogo de una empresa.

Eliminar producto

Elimina físicamente un producto o servicio existente dentro de la empresa activa del usuario. Esta operación eliminará en cascada todas las variantes e imágenes (generales y de variante) asociadas al producto.

Restricciones:

  • Solo el rol propietario (owner) puede ejecutar esta acción.
  • El producto debe pertenecer a la empresa activa.
Authorizations:
bearerAuth
path Parameters
productId
required
integer >= 1

Identificador único del producto a eliminar.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "Operación exitosa",
  • "data": {
    },
  • "errors": [ ],
  • "meta": { },
  • "traceId": "729bb1bf-882d-483b-89d3-5855dc5af3aa"
}

Listar productos y servicios

Obtiene un listado paginado del catálogo administrativo de productos y servicios pertenecientes a la empresa activa del usuario. Permite filtrar por categoría, tipo de producto y estado, así como buscar por código, nombre o marca y ordenar los resultados. El listado solo incluirá registros de la empresa asociada al token activo.

Roles permitidos: propietario, administrador, vendedor, auxiliar.

Authorizations:
bearerAuth
query Parameters
search
string

Término de búsqueda que aplica coincidencia parcial sobre el código, nombre o marca del producto (máx. 255 caracteres).

categoryId
integer

ID de la categoría asociada al producto.

productType
string
Enum: "product" "service"

Filtra por el tipo de registro (producto o servicio).

state
string
Enum: "enabled" "disabled" "suspended"

Filtra por el estado del producto.

sortBy
string
Default: "updatedAt"
Enum: "code" "name" "category" "brand" "productType" "price" "state" "updatedAt"

Nombre del campo por el cual ordenar los resultados.

sortDirection
string
Default: "desc"
Enum: "asc" "desc"

Dirección del ordenamiento.

page
integer
Default: 1

Número de página para la paginación de resultados.

perPage
integer
Default: 10
Enum: 5 10 25 50 100

Cantidad de resultados a devolver por página.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "Operación exitosa",
  • "data": [],
  • "errors": [ ],
  • "meta": {
    },
  • "traceId": "729bb1bf-882d-483b-89d3-5855dc5af3aa"
}

Registrar producto o servicio

Registra un nuevo producto o servicio dentro del catálogo de la empresa activa del usuario. La categoría informada debe existir y pertenecer a la empresa.

El registro incluye tanto los datos básicos como galerías de imágenes y variantes, ejecutándose toda la persistencia de forma transaccional.

Restricciones:

  • Solo los roles propietario (owner), administrador (manager) y vendedor (vendor) pueden ejecutar esta acción.
  • El código debe ser único dentro de la empresa.
  • El código de barras, si se envía, también debe ser único en la empresa.
  • No se permite registrar el producto en estado suspended.
Authorizations:
bearerAuth
Request Body schema: application/json
required
category
required
integer

ID de la categoría perteneciente a la empresa activa.

code
required
string

Código único del producto en la empresa (máx. 240 caracteres).

name
required
string

Nombre visible del producto o servicio (máx. 240 caracteres).

description
string or null

Texto descriptivo del producto.

supplier
string or null

Proveedor del producto.

brand
string or null

Marca del producto.

note
string or null

Nota interna o administrativa.

barcode
string or null

Código de barras único en la empresa.

price
required
number <float>

Precio base de venta. Debe ser mayor a 0.

cost
number or null <float>

Costo de adquisición.

unitOfMeasure
required
string
Enum: "unit" "kilogram" "liter" "box" "bag" "gram" "milliliter" "meter" "centimeter" "pack" "piece" "service"

Unidad de medida de venta (ej. unit, kilogram, liter, box).

quantityIncrement
required
number <float>

Incremento al vender.

minimumQuantity
required
number <float>

Cantidad mínima por venta.

maximumQuantity
number or null <float>

Cantidad máxima por venta (debe ser mayor o igual a la mínima).

mainImage
string or null

Referencia del archivo de imagen principal (sin URL absoluta).

tags
Array of strings or null

Etiquetas descriptivas.

discountType
string or null
Enum: "percentage" "amount"

Tipo de descuento promocional base.

discountAmount
number or null <float>

Valor del descuento. Si el tipo es porcentaje, no debe superar 100.

discountEndsAt
string or null <date-time>

Fecha de caducidad del descuento (debe ser futura).

visibility
required
string
Enum: "visible" "hidden"

Determina si se muestra en el catálogo de ventas.

featured
boolean or null

Marca si es un producto destacado.

type
required
string
Enum: "product" "service"

Tipo de ítem.

state
required
string
Enum: "enabled" "disabled"

Estado comercial inicial.

Array of objects or null

Galería general de imágenes.

Array of objects or null

Variantes del producto. Cada una debe tener tamaño o color, y un orden único.

Responses

Request samples

Content type
application/json
{
  • "category": 1,
  • "code": "PRD-FULL-001",
  • "name": "Smartphone Galaxy Ultra 5G",
  • "price": 1200.5,
  • "unitOfMeasure": "unit",
  • "quantityIncrement": 1,
  • "minimumQuantity": 1,
  • "visibility": "visible",
  • "type": "product",
  • "state": "enabled",
  • "description": "El teléfono más potente de la serie Galaxy con cámara de 200MP.",
  • "supplier": "Samsung Electronics",
  • "brand": "Samsung",
  • "note": "Edición especial con cargador incluido",
  • "barcode": "7891234560001",
  • "cost": 950,
  • "maximumQuantity": 50,
  • "mainImage": "imagen_principal_samsung.jpg",
  • "featured": true,
  • "tags": [
    ],
  • "discountType": "amount",
  • "discountAmount": 50,
  • "discountEndsAt": "2026-12-31T23:59:59Z",
  • "images": [
    ],
  • "variants": [
    ]
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "Operación exitosa",
  • "data": {
    },
  • "errors": [ ],
  • "meta": { },
  • "traceId": "729bb1bf-882d-483b-89d3-5855dc5af3aa"
}

Obtener detalle de producto

Obtiene la información completa de un producto o servicio perteneciente a la empresa activa del usuario. La consulta incluye la categoría parcial asociada con su padre opcional, información económica persistida, cantidades, galería general y colección de variantes con sus imágenes específicas. La empresa se resuelve desde el token empresarial; no se admite enviar identificadores de empresa.

Comportamiento:

  • Disponible para los cuatro roles (owner, manager, vendor, assistant); operación exclusivamente de lectura.
  • El producto se localiza aplicando empresa e identificador simultáneamente; un registro inexistente o de otra empresa devuelve el mismo 404.
  • La respuesta incluye vigencia derivada del descuento, basándose en fechas configuradas, sin sobreescribir los valores directos del descuento o precio base.
  • Las imágenes asociadas solo devuelven nombres físicos internos o se resuelven como un objeto con name y url pública cuando existen. Si una imagen no existe o no se tiene principal, se retorna null.
  • Las colecciones vacías (etiquetas, variantes, galería) retornan [] y los campos opcionales sin valor retornan null.
Authorizations:
bearerAuth
path Parameters
productId
required
integer >= 1

Identificador del producto (entero mayor que cero).

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "Operación exitosa",
  • "data": {},
  • "errors": [ ],
  • "meta": { },
  • "traceId": "729bb1bf-882d-483b-89d3-5855dc5af3aa"
}

Actualizar producto o servicio

Actualiza parcial o totalmente un producto o servicio existente en el catálogo de la empresa activa del usuario.

Reglas de sincronización:

  • Campos omitidos: Conservan su valor actual.
  • Campos enviados como null: Limpian el contenido del campo (solo para opcionales).
  • Campos controlados: No pueden enviarse como nulos, vacíos ni con valores no autorizados (ej. state a suspended).
  • Imágenes: Si se envía el array images, sincroniza la galería completa. Array vacío elimina todas. Si se omite, se conserva.
  • Variantes: Mismo comportamiento. Si se envían, los IDs existentes se actualizan, sin ID se crean, y omitidos se eliminan junto con sus imágenes.

Restricciones:

  • Solo roles propietario, administrador y vendedor.
  • No se puede transicionar a estado suspended ni modificar un producto que esté suspended.
  • La solicitud debe incluir al menos un campo modificable.
Authorizations:
bearerAuth
path Parameters
productId
required
integer >= 1

ID del producto a actualizar.

Request Body schema: application/json
required
non-empty
category
integer

ID de la categoría perteneciente a la empresa activa.

code
string

Código único del producto en la empresa.

name
string

Nombre visible del producto o servicio.

description
string or null

Texto descriptivo del producto.

supplier
string or null

Proveedor del producto.

brand
string or null

Marca del producto.

note
string or null

Nota interna o administrativa.

barcode
string or null

Código de barras único en la empresa.

price
number <float>

Precio base de venta. Debe ser mayor a 0.

cost
number or null <float>

Costo de adquisición.

profitMargin
number or null <float>

Margen de ganancia manual. No se recalcula automáticamente.

unitOfMeasure
string
Enum: "unit" "kilogram" "liter" "box" "bag" "gram" "milliliter" "meter" "centimeter" "pack" "piece" "service"

Unidad de medida del producto o servicio.

quantityIncrement
number <float>

Incremento de cantidad permitido (ej. 0.5 o 1).

minimumQuantity
number <float>

Cantidad mínima permitida para venta.

maximumQuantity
number or null <float>

Cantidad máxima por venta (debe ser mayor o igual a la mínima resultante).

mainImage
string or null

Referencia del archivo de imagen principal, o null para remover.

tags
Array of strings or null

Etiquetas descriptivas (reemplaza las actuales, null limpia).

discountType
string or null
Enum: "percentage" "amount"

Tipo de descuento a aplicar (porcentaje o monto fijo).

discountAmount
number or null <float>

Valor del descuento. Porcentaje <= 100, Monto <= Precio.

discountEndsAt
string or null <date-time>

Fecha límite en la que el descuento finaliza.

visibility
string
Enum: "visible" "hidden"

Control de visibilidad del producto para la venta.

featured
boolean

Indica si el producto está destacado.

type
string
Enum: "product" "service"

Clasificación del registro (producto físico o servicio).

state
string
Enum: "enabled" "disabled"

Solo se permite habilitado/deshabilitado.

Array of objects or null

Galería general de imágenes. Reemplaza la colección actual si se envía.

Array of objects or null

Variantes del producto. Reemplaza la colección actual si se envía.

Responses

Request samples

Content type
application/json
{
  • "category": 1,
  • "code": "QA-355-FULL",
  • "name": "Producto Completo Actualizado",
  • "price": 500,
  • "unitOfMeasure": "unit",
  • "quantityIncrement": 1,
  • "minimumQuantity": 1,
  • "visibility": "visible",
  • "featured": true,
  • "type": "product",
  • "state": "enabled",
  • "description": "Descripción completa y detallada.",
  • "supplier": "Proveedor SA",
  • "brand": "Marca Premium",
  • "note": "Nota interna",
  • "barcode": "9876543210123",
  • "cost": 300,
  • "profitMargin": 200,
  • "maximumQuantity": 100,
  • "mainImage": "main_updated.jpg",
  • "tags": [
    ],
  • "discountType": "percentage",
  • "discountAmount": 15,
  • "discountEndsAt": "2026-12-31T23:59:59Z",
  • "images": [
    ],
  • "variants": [
    ]
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "Operación exitosa",
  • "data": {},
  • "errors": [ ],
  • "meta": { },
  • "traceId": "729bb1bf-882d-483b-89d3-5855dc5af3aa"
}

Clientes

Endpoints de gestión de clientes. Incluye el registro de clientes de tipo persona y empresa dentro del contexto de una empresa.

Registrar cliente

Registra un nuevo cliente (persona o empresa) dentro de la empresa activa del usuario. La empresa se resuelve desde el token empresarial; no se admite enviar identificadores de empresa.

Restricciones:

  • Solo los roles propietario (owner), administrador (manager) y vendedor (vendor) pueden registrar clientes. El auxiliar (assistant) recibe acceso denegado.
  • Admite un registro parcial (solo campos obligatorios) o completo (con campos opcionales).
  • Para tipo empresa, la razón social es obligatoria; nombre y apellido representan al contacto principal.
  • fullName lo genera el backend; no debe enviarse.
  • El código se normaliza y debe ser único dentro de la empresa.
  • documentType acepta el catálogo público en minúsculas (ci, cex, pas, od, nit).
  • El avatar solo admite una referencia de archivo ya procesada por el servicio de almacenamiento (sin binarios, Base64, rutas locales ni URLs).
Authorizations:
bearerAuth
Request Body schema: application/json
required
code
required
string <= 240 characters

Código único del cliente dentro de la empresa.

name
required
string <= 120 characters

Nombre del cliente (persona) o del contacto principal (empresa).

lastName
required
string <= 120 characters

Apellido del cliente o del contacto principal.

email
required
string <email> <= 240 characters

Correo del cliente. Se normaliza en minúsculas; no requiere unicidad.

type
required
string
Enum: "person" "business"

Tipo de cliente.

state
required
string
Enum: "enabled" "disabled"

Estado inicial del cliente (suspendido no está permitido al registrar).

businessName
string <= 255 characters

Razón social. Obligatoria cuando el tipo es empresa.

phone
string <= 16 characters ^\+[1-9]\d{1,14}$

Teléfono de contacto en formato E.164 (signo + código de país y hasta 15 dígitos, sin espacios ni guiones).

avatar
string <= 240 characters

Referencia final del avatar (nombre de archivo .jpg, .jpeg, .png).

note
string

Nota interna del cliente.

birthDate
string <date>

Fecha de nacimiento (solo para persona, no futura).

gender
string
Enum: "male" "female" "prefer_not_to_say"

Género (solo para persona).

country
string = 2 characters

Código de país ISO alfabético de dos letras.

city
string <= 120 characters

Ciudad del cliente.

address
string <= 255 characters

Dirección del cliente.

latitude
number [ -90 .. 90 ]

Latitud. Debe enviarse junto con la longitud.

longitude
number [ -180 .. 180 ]

Longitud. Debe enviarse junto con la latitud.

documentType
string
Enum: "ci" "cex" "pas" "od" "nit"

Tipo de documento (catálogo público en minúsculas).

documentNumber
string <= 30 characters

Número de documento. Obligatorio cuando se envía el tipo de documento.

documentComplement
string <= 10 characters

Complemento documental. Solo aplicable cuando el tipo de documento es CI.

Responses

Request samples

Content type
application/json
{
  • "code": "CLI-001",
  • "name": "Juan",
  • "lastName": "Pérez",
  • "email": "juan@cliente.com",
  • "type": "person",
  • "state": "enabled",
  • "businessName": "Tech Solutions S.R.L.",
  • "phone": "+59170000000",
  • "avatar": "cliente-12.png",
  • "note": "Cliente frecuente.",
  • "birthDate": "1990-05-20",
  • "gender": "male",
  • "country": "BO",
  • "city": "La Paz",
  • "address": "Av. Desconocida 123",
  • "latitude": -16.5,
  • "longitude": -68.15,
  • "documentType": "ci",
  • "documentNumber": "9876543",
  • "documentComplement": "1A"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "Operación exitosa",
  • "data": {
    },
  • "errors": [ ],
  • "meta": { },
  • "traceId": "729bb1bf-882d-483b-89d3-5855dc5af3aa"
}

Listar clientes

Obtiene un listado paginado y resumido de los clientes pertenecientes a la empresa activa del usuario. La empresa se resuelve desde el token empresarial; no se admite enviar identificadores de empresa.

Permite búsqueda configurable por campos, filtros por tipo de documento, modelo y estado, ordenamiento y paginación. Todas las operaciones se resuelven desde base de datos.

Roles permitidos: propietario, administrador, vendedor y auxiliar.

Authorizations:
bearerAuth
query Parameters
search
string <= 255 characters

Término de búsqueda (coincidencia parcial). Se recorta; un valor vacío se trata como ausencia de búsqueda.

searchIn
Array of strings <= 5 items
Items Enum: "code" "fullName" "email" "phone" "document"

Campos sobre los que aplicar la búsqueda. Si se omite y hay término, se usan los cinco campos. Con búsqueda activa debe contener entre 1 y 5 valores únicos y válidos. Se envía separado por comas (ej. searchIn=code,fullName) o como lista (searchIn[]=code&searchIn[]=fullName).

documentType
string
Enum: "ci" "cex" "pas" "od" "nit"

Filtra por tipo documental (catálogo público en minúsculas).

model
string
Enum: "person" "business"

Filtra por modelo de cliente. Se mapea a la columna interna de tipo.

state
string
Enum: "enabled" "disabled" "suspended"

Filtra por estado del cliente.

sortBy
string
Default: "fullName"
Enum: "code" "fullName" "email" "phone" "documentType" "document" "state" "updatedAt"

Campo por el cual ordenar los resultados.

sortDirection
string
Default: "asc"
Enum: "asc" "desc"

Dirección del ordenamiento.

page
integer >= 1
Default: 1

Número de página.

perPage
integer
Default: 10
Enum: 5 10 25 50 100

Cantidad de resultados por página.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "Operación exitosa",
  • "data": [
    ],
  • "errors": [ ],
  • "meta": {
    },
  • "traceId": "729bb1bf-882d-483b-89d3-5855dc5af3aa"
}

Obtener detalle de cliente

Obtiene la información completa de un cliente perteneciente a la empresa activa del usuario. La empresa se resuelve desde el token empresarial; no se admite enviar identificadores de empresa.

Comportamiento:

  • Disponible para los cuatro roles (owner, manager, vendor, assistant); operación exclusivamente de lectura.
  • El cliente se localiza aplicando empresa e identificador simultáneamente; un cliente inexistente o de otra empresa devuelve el mismo 404.
  • Los catálogos internos se exponen en su forma pública (documento en minúsculas) y el documento completo se devuelve además en una representación legible.
  • El avatar se devuelve como objeto con referencia y URL pública, o null.
Authorizations:
bearerAuth
path Parameters
customerId
required
integer >= 1

Identificador del cliente (entero mayor que cero).

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "Operación exitosa",
  • "data": {
    },
  • "errors": [ ],
  • "meta": { },
  • "traceId": "729bb1bf-882d-483b-89d3-5855dc5af3aa"
}

Actualizar cliente

Actualiza (parcial o totalmente) un cliente perteneciente a la empresa activa del usuario. La empresa se resuelve desde el token empresarial; no se admite enviar identificadores de empresa.

Semántica de actualización:

  • Roles permitidos: propietario, administrador y vendedor. El auxiliar recibe 403.
  • Campo omitido ⇒ conserva su valor actual. Campo enviado ⇒ se actualiza; un campo opcional enviado como null se limpia.
  • El cuerpo debe contener al menos un campo modificable.
  • Los campos controlados (code, name, lastName, email, type, state) no pueden quedar nulos ni vacíos. businessName es obligatoria cuando el tipo final es empresa.
  • fullName lo reconstruye el backend cuando cambia name o lastName; no debe enviarse.
  • El servicio valida la configuración final combinando los valores actuales con los recibidos (tipo, documentación, coordenadas, estado).
  • El estado solo admite transiciones entre enabled y disabled; suspended no puede enviarse como destino y un cliente suspendido no puede modificar su estado.
Authorizations:
bearerAuth
path Parameters
customerId
required
integer >= 1

Identificador del cliente (entero mayor que cero).

Request Body schema: application/json
required

Colección parcial de propiedades modificables. Los opcionales admiten null para limpiarse.

non-empty
code
string <= 240 characters

Código empresarial (controlado, único en la empresa).

name
string <= 120 characters

Nombre del cliente o contacto principal (controlado).

lastName
string <= 120 characters

Apellido del cliente o contacto principal (controlado).

email
string <email> <= 240 characters

Correo de contacto (controlado, se guarda en minúsculas).

type
string
Enum: "person" "business"

Modelo del cliente. Puede cambiar entre persona y empresa.

state
string
Enum: "enabled" "disabled"

Estado operativo. Solo transiciones entre habilitado y deshabilitado.

businessName
string or null <= 255 characters

Razón social. Obligatoria para empresa.

phone
string or null <= 16 characters ^\+[1-9]\d{1,14}$

Teléfono en formato E.164, o null para limpiar.

avatar
string or null <= 240 characters

Referencia final del avatar, o null para retirar.

note
string or null

Nota interna, o null para limpiar.

birthDate
string or null <date>

Fecha de nacimiento (solo persona; no futura).

gender
string or null
Enum: "male" "female" "prefer_not_to_say" null

Género (solo persona).

country
string or null = 2 characters

Código de país ISO de dos letras.

city
string or null <= 120 characters

Ciudad, o null para limpiar.

address
string or null

Dirección, o null para limpiar.

latitude
number or null [ -90 .. 90 ]

Latitud (-90 a 90). Debe ir junto con la longitud.

longitude
number or null [ -180 .. 180 ]

Longitud (-180 a 180). Debe ir junto con la latitud.

documentType
string or null
Enum: "ci" "cex" "pas" "od" "nit" null

Tipo de documento (catálogo público en minúsculas).

documentNumber
string or null <= 30 characters

Número de documento (requiere tipo).

documentComplement
string or null <= 10 characters

Complemento documental (solo para CI).

Responses

Request samples

Content type
application/json
{
  • "code": "CLI-001",
  • "name": "Carlos",
  • "lastName": "Pérez",
  • "email": "carlos@cliente.com",
  • "type": "person",
  • "state": "enabled",
  • "businessName": "Tech Solutions S.R.L.",
  • "phone": "+59170000000",
  • "avatar": "cliente-12.png",
  • "note": "Cliente frecuente.",
  • "birthDate": "1990-05-20",
  • "gender": "male",
  • "country": "BO",
  • "city": "La Paz",
  • "address": "Av. Siempre Viva 123",
  • "latitude": -16.5,
  • "longitude": -68.15,
  • "documentType": "ci",
  • "documentNumber": "9876543",
  • "documentComplement": "1A"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "Operación exitosa",
  • "data": {
    },
  • "errors": [ ],
  • "meta": { },
  • "traceId": "729bb1bf-882d-483b-89d3-5855dc5af3aa"
}

Eliminar cliente

Elimina un cliente perteneciente a la empresa activa del usuario. La empresa se resuelve desde el token empresarial; no se admite enviar identificadores de empresa.

Restricciones y comportamiento:

  • Solo el rol propietario (owner) puede eliminar. Administrador, vendedor y auxiliar reciben 403.
  • El cliente se localiza aplicando empresa e identificador simultáneamente; un cliente inexistente o de otra empresa devuelve el mismo 404.
  • La eliminación es física y transaccional, con verificación del cliente dentro de la transacción (concurrencia).
  • Se elimina la referencia del avatar junto al cliente, pero no se borra el archivo físico.
  • Una segunda eliminación sobre el mismo identificador devuelve 404.
Authorizations:
bearerAuth
path Parameters
customerId
required
integer >= 1

Identificador del cliente a eliminar (entero mayor que cero).

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "Operación exitosa",
  • "data": {
    },
  • "errors": [ ],
  • "meta": { },
  • "traceId": "729bb1bf-882d-483b-89d3-5855dc5af3aa"
}

Sistema de archivos

Endpoints de gestión y administración de archivos del sistema. Exclusivos para usuarios con tokens maestros o tokens empresariales.

Subir archivo imagen o documento (General)

Sube un archivo de imagen o documento segun el tipo especificado (logo - banner - avatar - documento - certificado). El acceso esta abierto a usuarios de sistema y usuarios empresariales. El contenido de la solicitud debe estar en multipart/form-data.

Authorizations:
bearerAuth
Request Body schema: multipart/form-data
required

Datos requeridos para subir un archivo de imagen a su respectivo entorno.

file
required
string <binary>

Archivo de imagen o documento para subida.

type
required
string
Enum: "logo" "banner" "avatar" "documentation" "certificate"

Destino del archivo asociado a la imagen.

Responses

Response samples

Content type
application/json
{}

Sistema

Endpoints de mantenimiento y estado general del sistema.

Verificación de estado del servicio

Verifica que la aplicación responda (healthcheck básico). Retorna 200 si la aplicación está viva, sin requerir base de datos.

Responses

Response samples

Content type
application/json
{
  • "status": "ok"
}

Verificación de disponibilidad completa

Verifica que la aplicación y todas sus dependencias críticas (como la base de datos) estén funcionando correctamente.

Responses

Response samples

Content type
application/json
{
  • "status": "ready"
}

Restablecer base de datos (Solo entornos de prueba)

Restablece la base de datos a su estado inicial. Este endpoint está estrictamente protegido y solo funciona en entornos locales y de QA.

Authorizations:
bearerAuth
Request Body schema: application/json
required
reason
required
string [ 10 .. 255 ] characters

Razón o justificación por la cual se está solicitando el restablecimiento de la base de datos.

Responses

Request samples

Content type
application/json
{
  • "reason": "Restablecimiento por pruebas de integración y QA."
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "Operación exitosa",
  • "data": null,
  • "errors": [ ],
  • "meta": { },
  • "traceId": "729bb1bf-882d-483b-89d3-5855dc5af3aa"
}