Validación de identidad

La validación de identidad permite consultar automáticamente los registros tributarios oficiales de cada país al ingresar un número de documento (RUC, DNI, RUT, CUIT) en cualquier formulario del CRM.

¿Para qué sirve?

• Autocompletar datos de empresa (razón social, industria, dirección) al ingresar un RUC
• Verificar que un documento existe y está activo antes de guardar un contacto o cuenta
• Mantener un historial de consultas por tenant
• Controlar el gasto de API con un límite diario configurable

Países soportados

País	Documento	Fuente	Estado
🇵🇪 Perú	RUC (11 dígitos) / DNI (8 dígitos)	SUNAT · apis.net.pe	✅ Disponible
🇨🇱 Chile	RUT (ej: 90749000-9)	SII vía BaseAPI.cl	✅ Disponible
🇨🇴 Colombia	NIT / CC	RUES	🔜 Próximamente
🇪🇨 Ecuador	RUC (13 dígitos) / Cédula (10 dígitos)	SRI	🔜 Próximamente
🇦🇷 Argentina	CUIT / CUIL	AFIP · ARCA	🔜 Próximamente

Países próximamente

Ecuador y Argentina requieren despliegue en servidores de la misma región para evitar bloqueos por IP de los registros oficiales.

Configuración

Accede desde Admin → CRM → Configuración → Validación de identidad.

Límite diario de consultas

Controla cuántas consultas a APIs externas se realizan por día. El contador se reinicia a medianoche (hora del servidor).

• El límite por defecto es 500 consultas/día
• Los resultados servidos desde caché no consumen cuota
• Cuando se alcanza el límite, las consultas nuevas retornan error 429

Comportamientos

Switch	Descripción
Auto-completar al pegar	Al pegar un RUC o DNI en un formulario, los datos se completan automáticamente desde el registro oficial
Validar al guardar	Bloquea el guardado si el documento no existe o está inactivo
Cachear resultados	Almacena las respuestas 24 horas para evitar consultas repetidas
Webhook al actualizar	Envía una notificación cuando el estado de un documento cambia

Caché de resultados

Cuando Cachear resultados está activado:

1. La primera consulta llama a la API externa y guarda el resultado por 24 horas
2. Las consultas siguientes con el mismo documento responden desde caché
3. La fuente del resultado mostrará (caché) al final (ej: SUNAT · apis.net.pe (caché))
4. Las consultas en caché no incrementan el contador diario

Auto-completar al pegar

Al activar Auto-completar al pegar, los formularios de edición de Cuentas y Contactos detectan cuando pegas un número de documento y consultan automáticamente el registro tributario.

Cuentas: El campo RUC / NIT / RUT activa la consulta. Si el documento es válido, se rellenan los campos Nombre e Industria.

Contactos: El campo DNI / RUC activa la consulta:

• DNI (8 dígitos): se rellenan Nombre y Apellido desde RENIEC
• RUC (11 dígitos): se rellena Nombre desde SUNAT

Consulta manual

Desde la pantalla de configuración puedes realizar consultas individuales usando el botón Probar consulta.

Ingresa el país y número de documento. El resultado muestra:

• Razón social / nombre
• Estado (Activo, Inactivo, Cancelado)
• Industria / actividad económica
• Dirección registrada
• Fuente de datos

Historial de consultas

La tabla Historial reciente muestra las últimas 20 consultas del tenant con:

• Fecha y hora
• Tipo de documento y número consultado
• Resultado (success, cached, not_found, failed, invalid)
• Fuente de datos

Exporta el historial completo en formato CSV desde el botón Exportar CSV.

Validación por lotes

La sección Validación por lotes permite verificar de forma masiva los documentos de tus contactos o cuentas que aún no han sido validados.

1. Selecciona la entidad (Contactos o Cuentas)
2. Define el rango de días a considerar
3. El sistema muestra cuántos registros sin validar encontró
4. Haz clic en Iniciar validación — el proceso corre en segundo plano

Cuota

La validación por lotes consume cuota de API. Verifica que el límite diario sea suficiente antes de iniciar un lote grande.

Variables de entorno requeridas

Para activar cada proveedor, configura las siguientes variables en tu servidor:

# Perú — apis.net.pe
APISPERU_TOKEN=sk_xxxxx

# Chile — BaseAPI.cl
BASEAPI_CL_TOKEN=sk_xxxxx

# Colombia — RUES (próximamente)
RUES_USER=usuario
RUES_PASS=contraseña

Si una variable no está configurada, el proveedor correspondiente no estará disponible y las consultas para ese país retornarán error 501 Not Implemented.

Referencia de errores

Código	Significado
invalid_format	El número de documento no tiene el formato correcto
not_found	El documento no existe en el registro oficial
not_configured	No hay proveedor configurado para ese país
provider_unavailable	El servicio externo no está disponible temporalmente
429	Se alcanzó el límite diario de consultas