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

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

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 (General)

Sube un archivo de imagen segun el tipo especificado (logo - banner - avatar). 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 para subida.

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

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