El dolor de validar CURPs una por una
Si tu negocio trabaja con listas grandes de CURPs — nominas, padrones de clientes, expedientes de pacientes, registros escolares — ya conoces el patron: hacer una llamada, esperar la respuesta, hacer la siguiente, esperar, y asi cientos o miles de veces.
Hacerlo manualmente es impensable. Hacerlo en codigo tampoco es trivial: tienes que orquestar las llamadas, controlar la concurrencia para no saturar tu sistema, manejar reintentos cuando algo falla, llevar la cuenta de cuales ya respondieron y cuales no, y reanudar el trabajo si tu proceso se cae a la mitad.
En la practica, lo que parecia una tarea simple se convierte en un mini-sistema de colas que tu equipo tiene que construir, probar y mantener. Y mientras tanto, la base de datos con tus empleados o clientes sigue sin validarse.
Una sola solicitud, toda la lista
Por eso ahora ofrecemos un nuevo endpoint de procesamiento por lote para validacion de CURPs. La idea es directa: en lugar de hacer una llamada por cada CURP, mandas tu lista completa en una sola solicitud y recibes un identificador de lote. A partir de ahi puedes consultar el estado cuando quieras y, cuando todo termine, obtener los resultados.
Tu codigo se simplifica enormemente. No hay que orquestar nada: nuestro servicio se encarga de procesar cada CURP, manejar los reintentos internos cuando un dato tarda en responder, y mantener un registro de progreso que tu puedes consultar en cualquier momento.
Como se usa
El uso es directo. Mandas una sola solicitud con tu lista de CURPs (o de datos personales, segun el modo que elijas) y recibes un identificador de lote.
1. Envias el lote
Cada elemento de la lista es una CURP que quieres validar. Si lo prefieres, puedes agregarle una etiqueta personalizada — util para amarrar el resultado a un registro tuyo, como el ID de un empleado en tu sistema:
curl -X POST "https://api.tlaloc.sh/mx/v1/curp/batch" \
-H "Authorization: Bearer tlmx_TU_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"type": "curp",
"items": [
{"curp": "MAVR830713HDFRJC07", "ref": "emp-001"},
{"curp": "GOLA901225MDFNRS02", "ref": "emp-002"},
...
]
}'La respuesta te confirma que el lote fue aceptado y te entrega un identificador:
{
"id": 12345,
"status": "queued",
"items_total": 200,
"_links": {
"self": "/v1/curp/batch/12345",
"items": "/v1/curp/batch/12345/items"
}
}2. Consultas el estado cuando quieras
Mientras tu lote se procesa, puedes consultar el progreso. Veras cuantas CURPs ya estan listas, cuantas siguen pendientes, y cual es el costo acumulado de la operacion:
curl "https://api.tlaloc.sh/mx/v1/curp/batch/12345" \
-H "Authorization: Bearer tlmx_TU_API_KEY"El campo status te dice si el lote esta en cola, procesando o terminado. Cuando termina, sabes que es momento de descargar los resultados.
3. Recibes los resultados completos
Cuando el lote termina, descargas la lista de resultados de una sola vez. Cada elemento incluye la CURP que enviaste (con su etiqueta opcional), el estado del lookup, y los datos oficiales completos del registro:
curl "https://api.tlaloc.sh/mx/v1/curp/batch/12345/items" \
-H "Authorization: Bearer tlmx_TU_API_KEY"Dos modos: por CURP o por datos personales
El endpoint acepta dos tipos de entrada, segun lo que tengas a la mano:
- Tipo
curp: mandas las CURPs y obtienes los datos oficiales completos asociados (nombres, apellidos, fecha de nacimiento, entidad, datos del documento probatorio). - Tipo
search: mandas datos personales (nombres, apellidos, fecha de nacimiento, sexo, entidad de nacimiento) y obtienes la CURP correspondiente. Util cuando no la tienes registrada o cuando quieres confirmar que los datos coinciden con un registro oficial.
Cada lote es de un solo tipo, lo que mantiene la solicitud clara y predecible.
Ventajas frente al uno-por-uno
Mas alla de la comodidad, el procesamiento por lote ofrece beneficios concretos:
- Procesamiento mas rapido para volumen alto. Validar una lista por lote es significativamente mas rapido que enviar las consultas una por una, porque nuestro servicio paraleliza el trabajo internamente.
- Sin orquestacion de tu lado. No tienes que escribir codigo de colas, reintentos, control de concurrencia ni manejo de fallos parciales. Todo eso vive en nuestra infraestructura.
- Resiliencia automatica. Si algo falla a la mitad — un reinicio, un corte de red, un dato que tarda mas de lo normal — el lote retoma el trabajo donde se quedo y termina. No pierdes tu progreso.
- Detecta duplicados automaticamente. Si tu lista contiene la misma CURP repetida, se procesa una sola vez. Los duplicados reciben el mismo resultado sin cobrarse dos veces.
- Aprovecha el cache compartido. Si alguna de las CURPs ya fue consultada antes (por ti o por otra parte de tu sistema), se entrega desde cache instantaneamente y sin costo adicional.
- Cancelable. Si te diste cuenta de que mandaste el lote equivocado, puedes cancelarlo. Lo que ya se proceso se conserva y lo pendiente se libera.
- Etiquetas para correlacionar. Cada elemento puede llevar tu propia etiqueta (el ID interno del empleado, del cliente, del expediente). Cuando lees los resultados, sabes inmediatamente a que registro de tu base de datos corresponde cada respuesta.
- Pagas solo por validaciones reales. Los cache hits no se cobran, las validaciones que no encuentran resultado (CURP inexistente) tampoco. Solo pagas las validaciones que de verdad consultaron los registros oficiales.
Casos de uso reales
El procesamiento por lote se vuelve util en muchos escenarios donde antes la unica opcion era construir tu propia orquestacion:
- Onboarding de empleados. Cuando tu empresa contrata un grupo grande — un cambio de turno, un proyecto temporal, una temporada alta — validas todas las CURPs de la nomina nueva en una sola solicitud.
- Limpieza de bases de datos. Si heredaste una base de datos de clientes con calidad dudosa, puedes validar todas las CURPs registradas para detectar errores tipograficos o datos desactualizados.
- Compliance y KYC. Procesos de "Know Your Customer" en servicios financieros, fintech, aseguradoras y plataformas reguladas: valida lotes completos de nuevos clientes contra los registros oficiales.
- Servicios de salud y educacion. Centros medicos, hospitales, escuelas y universidades pueden validar expedientes completos de pacientes o estudiantes en una sola operacion.
- Servicios de gobierno y dependencias. Dependencias publicas que reciben padrones de beneficiarios pueden validarlos en lote antes de procesar pagos o entregas.
- Recobranza y verificacion de cartera. Empresas de cobranza pueden validar lotes de deudores para confirmar identidades y actualizar datos antes de iniciar gestiones.
- Migracion de sistemas. Cuando estas migrando datos entre dos sistemas, valida toda la cartera en un solo lote para detectar inconsistencias antes de hacer el corte.
Lo que ya tenias sigue funcionando
Si tu sistema actual usa el endpoint de validacion individual /v1/curp, no tienes que cambiar nada. Ese endpoint sigue disponible tal cual, con el mismo contrato y la misma latencia. El endpoint por lote es una opcion adicional para los casos en los que tu necesidad es de volumen.
Incluso puedes combinar los dos: usa el endpoint individual para validaciones interactivas (un formulario web donde un usuario captura una CURP y espera la respuesta inmediata) y el endpoint por lote para procesos masivos en segundo plano (procesos nocturnos, importacion de archivos, validacion de listas).
Siguientes pasos
El endpoint de procesamiento por lote ya esta disponible para todos los usuarios de la API. Si todavia no tienes una API key, puedes registrarte y obtener una en minutos. La primera prueba la puedes hacer con tu propia CURP — la documentacion completa te guia paso a paso.