Gestión de Clientes y Proveedores

Descripción General

El módulo de Gestión de Clientes y Proveedores permite crear, consultar, actualizar y auditar la ficha técnica integral de todas las personas naturales y jurídicas que interactúan comercialmente con la empresa. Cumple rigurosamente con los lineamientos del Anexo Técnico de Factura Electrónica de la DIAN para Colombia, garantizando la consistencia fiscal, la asignación de cupos de crédito y la georreferenciación logística.

---

Flujo Operativo: Creación de Nuevo Tercero

Para registrar un nuevo tercero en el sistema, sigue este procedimiento paso a paso a través de la ventana modal interactiva:

1. Apertura de la Ventana Modal:

   • Dirígete al módulo de Terceros (/third-parties) desde la barra de navegación lateral.
   • Pulsa el botón principal + Nuevo Tercero ubicado en la esquina superior derecha del encabezado.
   • El sistema desplegará el modal interactivo titulado ”+ Nuevo Tercero | Registro de terceros”.

2. Sección: Identificación Oficial:

   • Tipo Documento (* Obligatorio): Despliega el selector y elige el documento de identidad fiscal correspondiente:
     • NIT: Número de Identificación Tributaria (empresas y personas jurídicas o naturales con RUT).
     • CC: Cédula de Ciudadanía.
     • CE: Cédula de Extranjería.
     • TI: Tarjeta de Identidad.
     • PASSPORT: Pasaporte internacional.
     • DIE: Documento de Identificación Extranjero.
   • Número Documento (* Obligatorio): Digita el número de identificación sin puntos, comas ni espacios (ej: 900123456).
     • Validación en Tiempo Real: El sistema consulta asíncronamente la base de datos para verificar unicidad mostrando los estados Validando..., Documento válido (verde) o El documento ya existe (rojo).
   • Dígito Verificación (DV): Campo protegido calculado en tiempo real mediante el algoritmo Módulo 11 de la DIAN cuando el tipo seleccionado es NIT. En cualquier otro tipo de documento se mantiene inactivo.
   • Código del Tercero (Opcional): Campo alfanumérico para el código interno. Si se deja en blanco, el sistema genera automáticamente un identificador secuencial con el prefijo TP (ej: TP0001).

3. Sección: Clasificación Comercial y Jurídica:

   • Tipo de Persona (* Obligatorio): Marca la naturaleza jurídica mediante los botones de opción:
     • Natural: Personas físicas (autónomos, profesionales independientes, personas con cédula).
     • Jurídica: Sociedades comerciales, corporaciones, fundaciones (S.A.S., S.A., Ltda.).
   • Tipos de Tercero (* Obligatorio): Selector multiselección con etiquetas (chips). Puedes asignar uno o varios roles simultáneos:
     • Cliente: Habilita facturación electrónica, remisiones y cotizaciones.
     • Proveedor: Habilita órdenes de compra, gastos y causaciones contables.
     • Empleado: Habilita causaciones de nómina y anticipos.
     • Cobrador: Habilita asignación de recibos de caja y rutas de recaudo.

4. Sección: Nombres e Identificación Legal: La estructura de este bloque se adapta automáticamente de acuerdo con el Tipo de Persona seleccionado:

   Persona Jurídica
   • Razón Social (* Obligatorio): Nombre jurídico completo tal como figura registrado en el certificado de Cámara de Comercio y RUT (ej: Empresa ABC S.A.S.).
   • Nombre Comercial: Nombre comercial del establecimiento, enseña o marca comercial para identificación en facturas de venta (ej: ABC Store).
   Persona Natural
   • Primer Nombre (* Obligatorio): Primer nombre del tercero (ej: Juan).
   • Segundo Nombre: Segundo nombre opcional (ej: Carlos).
   • Primer Apellido (* Obligatorio): Primer apellido (ej: Pérez).
   • Segundo Apellido: Segundo apellido opcional (ej: González).

   Al salir de cualquiera de estos campos (evento blur), el sistema ejecuta la función normalizeLegalNames para limpiar dobles espacios y normalizar la capitalización tipográfica.

5. Sección: Información Tributaria (Fiscal):

   • Régimen Tributario: Selecciona el régimen tributario aplicable ante la DIAN:
     • Régimen Ordinario / Común
     • Régimen Simple de Tributación (RST)
     • No Responsable de IVA
   • Responsabilidades Fiscales: Selecciona las responsabilidades tributarias que apliquen para el cálculo de retenciones y la emisión de documentos electrónicos:
     • O-13 Gran Contribuyente
     • O-15 Autorretenedor
     • O-23 Agente de Retención IVA
     • R-99-PN No Responsable

6. Sección: Contacto:

   • Email: Correo electrónico formal del tercero. Valida sintaxis RFC 5322 y se utiliza como buzón de entrega de facturas electrónicas (XML y PDF).
   • Teléfono: Número de teléfono fijo corporativo con indicativo (ej: +57 1 234 5678).
   • Móvil (* Obligatorio para Clientes y Proveedores): Línea celular de contacto operativo o compras (ej: +57 300 123 4567).
   • Sitio Web: Portal web de la compañía (ej: https://www.empresa.com).

7. Sección: Dirección Física:

   • Dirección (* Obligatorio para Clientes y Proveedores): Domicilio principal o fiscal del tercero (ej: Calle 123 # 45-67).
   • Departamento: Menú desplegable con los 32 departamentos de Colombia con buscador integrado.
   • Municipio: Menú desplegable en cascada que se habilita inmediatamente tras seleccionar el departamento.
   • País: Preconfigurado por defecto como Colombia.

8. Sección: Asignación Geográfica (Rutas y Logística): (Esta sección se omite si el rol es exclusivamente Cobrador)

   • Zona: Sector geográfico asignado para la distribución y control de despachos.
   • Barrio: Barrio específico dependiente de la zona seleccionada.
   • Latitud y Longitud: Coordenadas decimales (ej: Latitud: 4.6097, Longitud: -74.0817) utilizadas por la app móvil y el planificador de rutas de reparto.

9. Sección: Información Financiera (Crédito y Plazos): (Esta sección se omite si el rol es exclusivamente Empleado)

   • Límite de Crédito: Cupo máximo permitido en pesos colombianos (COP) para facturación a crédito (ej: $ 5.000.000).
   • Días de Crédito: Número de días de plazo comercial otorgados para el vencimiento de facturas (ej: 30 días).

10. Sección: Notas y Guardado Final:

    • Notas: Cuadro de texto multilínea para registrar condiciones comerciales especiales, horarios de recepción de mercancía o directrices de pago.
    • Acciones del Formulario:
      • Cancelar: Cierra la ventana modal descartando cualquier cambio no guardado.
      • Guardar / Crear: Ejecuta la validación síncrona en cliente y despacha la petición POST /api/v1/third-parties. Tras una respuesta exitosa, el sistema notifica "Tercero guardado exitosamente", cierra el modal y recarga el directorio.

---

Validaciones y Reglas de Negocio

Cálculo del Dígito de Verificación (Módulo 11 DIAN)

Para documentos de tipo NIT, el sistema calcula el DV multiplicando cada dígito de derecha a izquierda por la serie fija de factores primos:
[3, 7, 13, 17, 19, 23, 29, 37, 41, 43, 47, 53, 59, 67, 71].
Se obtiene la sumatoria y se calcula el residuo mediante suma % 11:

• Si el residuo es 0 o 1, el DV es exactamente igual al residuo (0 o 1).
• Si el residuo es mayor que 1, el DV se obtiene mediante la resta: 11 - residuo. Este cálculo previene rechazos por inconsistencia ante los servidores de validación previa de la DIAN.

Obligatoriedad Condicional por Rol

• Clientes y Proveedores: Los campos Móvil y Dirección son estrictamente obligatorios cuando se marca el rol Cliente o Proveedor.
• Identificación Única: No se permite duplicar la combinación de Tipo de Documento + Número de Documento dentro del mismo inquilino (Tenant).

---

Tabla de Estados del Tercero

Estado	Indicador Visual	Condiciones Operativas
Activo	Chip Verde (is_active = true)	Tercero habilitado plenamente para facturación, compras, cotizaciones y cobros.
Inactivo	Chip Gris (is_active = false)	Tercero suspendido temporalmente. No figura en selectores de nuevos comprobantes comerciales.
Bloqueado por Cartera	Alerta Naranja / Roja	El saldo actual en facturas pendientes supera el credit_limit o presenta mora superior a credit_days. Requiere autorización de supervisor para facturar.

---

Endpoints de la API (Backend Go)

Método	Endpoint	Descripción
POST	/api/v1/third-parties	Registra un nuevo tercero con roles y asignación geográfica.
GET	/api/v1/third-parties/check-document?type={type}&number={number}	Verificación en tiempo real de existencia de documento.
PUT	/api/v1/third-parties/{id}	Actualiza la información fiscal, comercial o financiera del tercero.
GET	/api/v1/third-parties/{id}	Retorna el detalle completo de la ficha maestra del tercero.