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": "superadmin@valora.com",
  • "password": "password123"
}

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"
}