DesarrolladoresDesde Pro
La API de VerifyCol, de la primera llamada a producción.
Todo lo que necesitas para integrar la verificación de contrapartes: autenticación, el camino recomendado, el sandbox, los webhooks, los límites y los errores.
URL base
https://api.verifycol.co/api/v1Autenticación
X-API-KEY: vf_test_tu_api_keyVersionado en la URL (/v1). Los retiros se avisan con las cabeceras Deprecation y Sunset.
Primera llamada
Crea un reporte en el sandbox.
# Crear el reporte (documento de prueba «sujeto limpio»)
curl -X POST "https://api.verifycol.co/api/v1/gateway/api/reports/" \
-H "X-API-KEY: vf_test_tu_api_key" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"tipo_documento":"CC","numero_documento":"900000003","data_authorization_declared":true}'
# Consultar hasta un estado final: completed | partial | failed
curl "https://api.verifycol.co/api/v1/gateway/api/reports/{id}" -H "X-API-KEY: vf_test_tu_api_key"// Respuesta de la consulta por fuente
{
"success": true,
"data": { … },
"request_id": "uuid",
"response_time_ms": 180,
"credits_charged": 1
}partial no es un error: parte de las fuentes no respondió y esos créditos se devuelven solos.
Camino recomendado
Tres llamadas para el reporte unificado.
- POST
/gateway/api/reports/estimateGratis: devuelve el costo y los campos que faltan.
- POST
/gateway/api/reports/Crea el reporte: 201, o 202 si falta el consentimiento del titular.
- GET
/gateway/api/reports/{id}Consulta hasta completed, partial o failed. Con …/pdf descargas el PDF.
Documentos: CC, CE, NIT y PA.
Consulta por fuente (avanzado): POST /api/v1/gateway/services/verifycol/{código}. Con una clave vf_live_ exige la cabecera X-Data-Authorization: true, la declaración de autorización del titular que pide la Ley 1581; sin ella responde 400. Cada una de las 28 fuentes tiene su página en la documentación de la API, con su cuerpo, costo, tiempo y plan.
Claves de API
Claves que puedes restringir y rotar.
Pro incluye 5 claves; Business, 20.
Dos tipos de clave
vf_live_ para producción y vf_test_ para el sandbox, creadas desde el panel.
Vencimiento
Máximo 365 días, con avisos a 30, 7 y 1 días.
Restricciones
Por IP o CIDR (hasta 50) y por origen.
Rotación sin cortes
Al rotar, la clave anterior sigue viva 24 horas.
Idempotencia y límites
Reintenta sin miedo a duplicar.
Idempotency-Key
- Hasta 128 caracteres, con una ventana de 24 horas.
- Misma clave y mismo cuerpo: el mismo reporte, con
Idempotent-Replayed: true. - Misma clave con otro cuerpo:
409.
Límites de uso
- Por clave: 120 por minuto y 2.000 por día por defecto (máximo 300 por minuto y 20.000 por día).
- Por organización: 600 por minuto y 50.000 por día, sumando todas sus claves.
- Cabeceras
X-RateLimit-Limit,X-RateLimit-RemainingyRetry-After.
Errores
Una sola forma de error, con códigos estables.
Lee error.code para decidir qué hacer y error.message para mostrarle el error a la persona.
{
"detail": "...",
"success": false,
"error": {
"code": "CODIGO_ESTABLE",
"message": "..."
}
}| Código | HTTP |
|---|---|
BAD_REQUESTFalta la declaración de autorización del titular. | 400 |
MISSING_API_KEY / INVALID_API_KEY | 401 |
INSUFFICIENT_CREDITS / PLAN_UPGRADE_REQUIRED | 402 |
FORBIDDEN | 403 |
NOT_FOUND | 404 |
CONFLICT | 409 |
VALIDATION_ERROR | 422 |
RATE_LIMIT_EXCEEDED | 429 |
INTERNAL_ERROR / SERVICE_UNAVAILABLE / UPSTREAM_ERROR | 5xx |
Sandbox
Prueba cada caso antes de salir a producción.
Mismas URLs con una clave vf_test_. Saldo de prueba de 1.000 créditos que se repone cada día, PDF marcado «PRUEBA — DATOS SINTÉTICOS» y cabecera X-VerifyCol-Environment: test | live.
| Documento de prueba | Qué produce |
|---|---|
| 900000001 | Coincidencia firme en OFAC y ONU |
| 900000002 | PEP en revisión |
| 900000003 | Sujeto limpio |
| 900000004 | Procuraduría caída (reporte parcial) |
| 900000005 | Timeout de Policía (parcial) |
| 900000006 | Flujo de consentimiento (202) |
| 900000007 | Parcial mixto |
| NIT 900000008 | Persona jurídica limpia |
| 900000009 | Saldo de prueba agotado (402) |
| 900000015 | Tarea que nunca cierra |
Webhooks
Te avisamos cuando el reporte termina.
Eventos
report.completedreport.partialreport.failedtask.completed
Firma
X-VerifyCol-Signature: sha256=HMAC(secret,
"{X-VerifyCol-Timestamp}." + cuerpo)Entrega
- Hasta 8 intentos a lo largo de unas 44 horas.
- Deduplica por
X-VerifyCol-Event-Id. - Responde 2xx en menos de 10 segundos.
- Pausa automática tras 20 fallos seguidos. Al reactivarlo, se recuperan los eventos de las últimas 72 horas.
Preguntas frecuentes
Preguntas sobre la API
¿Desde qué plan está disponible la API de VerifyCol?
Desde el plan Pro, que incluye 5 claves de API. Business incluye 20 y el plan a la medida, ilimitadas.
¿Hay un entorno de pruebas?
Sí. Con una clave vf_test_ usas las mismas URLs con un saldo de prueba de 1.000 créditos que se repone cada día, y documentos de prueba para cada caso: sujeto limpio, coincidencia en OFAC y ONU, fuente caída o consentimiento pendiente.
¿Cómo evito crear reportes duplicados al reintentar?
Envía la cabecera Idempotency-Key. Con la misma clave y el mismo cuerpo, en una ventana de 24 horas, recibes el mismo reporte; con otro cuerpo, la API responde 409.
¿Qué significa un reporte en estado partial?
Que parte de las fuentes no respondió. No es un error: esos créditos se devuelven solos.
¿Cómo verifico que un webhook viene de VerifyCol?
Con la cabecera X-VerifyCol-Signature, que es un HMAC SHA-256 del secreto sobre la marca de tiempo (X-VerifyCol-Timestamp), un punto y el cuerpo. Deduplica los eventos con X-VerifyCol-Event-Id.
Documentación pública
Crea tu clave de prueba.
Regístrate, crea una clave vf_test_ desde el panel y haz tu primera llamada al sandbox. La API está disponible desde el plan Pro.