Referencia de la API · Documentación técnica

Construye sobre DataCred.

API REST con consentimiento obligatorio, auditoría inmutable y cinco modelos de score calibrados para el riesgo crediticio venezolano. Obtén tu API key de sandbox en segundos.

Obtener API key de sandbox Términos de la API

01 · Primeros pasos

Del registro a tu primer pull en 5 minutos.

1Registra tu empresa

Haz un POST a /v1/public/partner-signup con los datos de tu empresa, tu documento fiscal (RIF / NIT) y una contraseña para el portal. Recibes una API key de sandbox (dc_test_…) de inmediato; guárdala, solo se muestra una vez. El mismo correo y contraseña te sirven para entrar al portal de socios.

curl -X POST https://api.datacred.org/v1/public/partner-signup \
  -H "Content-Type: application/json" \
  -d '{
    "company_name": "Mi Fintech CA",
    "legal_name": "Mi Fintech, C.A.",
    "tax_id": "J-12345678-9",
    "industry": "LENDING",
    "contact_email": "dev@mifintech.com",
    "contact_full_name": "Nombre Ejemplo",
    "password": "TuClaveSegura123"
  }'

2Haz un pull de reporte (sandbox)

Usa tu key dc_test_… para hacer un pull de score. En modo sandbox puedes usar cualquier userId de prueba; no se accede a datos reales de personas.

curl -X POST https://api.datacred.org/v1/partner/pull \
  -H "X-API-Key: dc_test_TU_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "00000000-0000-0000-0000-000000000001",
    "pullType": "SOFT",
    "purpose": "CREDIT_APPLICATION",
    "scoreModelId": "datacred_consumer"
  }'

3Pasa a producción

Cuando aprobemos tu cuenta (1 a 2 días hábiles), nuestro equipo eleva tu key a dc_live_… y configura tu plan para hacer pulls de producción.

02 · Autenticación

Autenticación

Todos los endpoints de socios usan autenticación por API key. Envía tu key de una de estas dos formas:

X-API-Key: dc_test_… (recomendada para servidor a servidor)
Authorization: Bearer dc_test_…

Entorno	Prefijo de la key	¿Datos reales?	¿Cobro?
Sandbox	`dc_test_…`	No	No
Producción	`dc_live_…`	Sí	Sí (por consulta)

03 · Referencia de la API

Referencia de la API

URL base: https://api.datacred.org · Todas las respuestas siguen el formato: { success, data, error?, meta? }

Score pull (para socios)

POST/v1/partner/pull

Hace un pull del reporte de crédito de un usuario. Exige consentimiento, registra una inquiry en los pulls HARD y descuenta una consulta de tu plan.

Auth: X-API-Key o Bearer dc_live_*Body: { userId, pullType, purpose, scoreModelId?, includeTradelines?, includeInquiries?, includeDisputes? }Devuelve: score, scoreBand, reasonCodes, modelId, modelName, inquiryId, billing

Pre-screen (para socios)

POST/v1/partner/prescreen/campaigns

Crea una campaña de pre-screen para ofertas de marketing dirigidas.

Auth: X-API-Key o Bearer dc_live_*Body: { name, criteria, purpose, offerDetails }Devuelve: campaignId

Tradelines (para socios)

POST/v1/partner/tradelines

Reporta un nuevo tradeline (endpoint de furnisher).

Auth: X-API-KeyBody: { userId, accountType, currentBalance, creditLimit, currentStatus, … }Devuelve: tradelineId, status

PATCH/v1/partner/tradelines/:id

Actualiza el saldo o el estado de un tradeline existente.

Auth: X-API-KeyBody: { currentBalance?, currentStatus?, daysPastDue?, pastDueAmount? }Devuelve: updatedTradeline

Uso y consumo (para socios)

GET/v1/partners/usage

Consulta tu consumo de consultas del periodo. Es de solo lectura y no gasta una consulta, ideal para verificar que tu API key autentica.

Auth: X-API-Key o Bearer dc_live_*Devuelve: usage

Webhooks (para socios)

GET/v1/partners/webhooks

Lista los webhook endpoints de tu cuenta.

Auth: Bearer dc_live_*Devuelve: endpoints[]

POST/v1/partners/webhooks

Registra un nuevo webhook endpoint.

Auth: Bearer dc_live_*Body: { url, events[], description? }Devuelve: endpointId, signingSecret

DELETE/v1/partners/webhooks/:id

Revoca un webhook endpoint.

Auth: Bearer dc_live_*Devuelve: ok

Facturación (para socios)

GET/v1/partners/billing/balance

Consulta tu saldo de créditos disponible. De solo lectura, no gasta una consulta.

Auth: X-API-Key o Bearer dc_live_*Devuelve: balance

Acciones adversas (para socios)

POST/v1/partner/adverse-action

Registra una notificación de acción adversa (obligatoria dentro de los 30 días de una negación).

Auth: X-API-KeyBody: { userId, reason, reasonCodes[], action }Devuelve: noticeId

Registros públicos e ítems negativos (para socios)

POST/v1/partner/public-records

Reporta un registro público (sentencia, quiebra, gravamen).

Auth: X-API-KeyBody: { userId, recordType, amount?, courtName?, filedAt }Devuelve: recordId

POST/v1/partner/negative-items

Reporta un ítem negativo (cobranza, charge-off).

Auth: X-API-KeyBody: { userId, itemType, amount, status, originalCreditor? }Devuelve: itemId

Registro autoservicio (público, sin auth)

POST/v1/public/partner-signup

Registra una nueva cuenta de socio y su acceso al portal. Devuelve una API key de sandbox (se muestra una sola vez).

Auth: NingunaBody: { company_name, legal_name, tax_id, industry, contact_email, contact_full_name, password, country?, website_url?, contact_phone? }Devuelve: partnerId, sandboxApiKey, status

POST/v1/public/partner-signup/:id/verify-email

Verifica el correo de contacto del socio con el token enviado por email.

Auth: NingunaBody: { token }Devuelve: verified: true

04 · Modelos de score

Modelos de score

Pasa scoreModelId en tu pull para elegir el modelo de scoring. Todos los modelos devuelven un score entre 300 y 850. El precio por consulta es el mismo para cualquier modelo, sin recargo.

ID del modelo	Nombre	Caso de uso	Factores principales	Ventana de consultas	Precio
`datacred_consumer`	DataCred Consumer	Score de historial de crédito para consumidores (UI, resumen general)	Historial de pagos (30%), utilización (20%), antigüedad (15%)	365 días	Sin recargo por modelo
`datacred_risk_auto`	DataCred Risk: Auto	Suscripción para crédito automotriz	Historial de pagos (40%), antigüedad (20%), utilización (10%)	365 días	Sin recargo por modelo
`datacred_risk_mortgage`	DataCred Risk: Hipotecario	Suscripción hipotecaria (ventana de consultas de 2 años)	Utilización (25%), registros públicos (15%), historial (30%)	730 días	Sin recargo por modelo
`datacred_risk_bankcard`	DataCred Risk: Tarjeta	Suscripción para tarjetas de crédito	Utilización (30%), mezcla de cuentas (15%), historial (25%)	365 días	Sin recargo por modelo
`datacred_risk_personal`	DataCred Risk: Préstamo Personal	Préstamos personales sin garantía colateral	Historial (28%), ítems negativos (15%), utilización (18%)	365 días	Sin recargo por modelo

05 · Webhooks

Webhooks

Registra webhook endpoints para recibir eventos en tiempo real. Los payloads se firman con HMAC-SHA256. Verifica el header X-DataCred-Signature antes de procesarlos.

// Verificación de firma (Node.js)
const crypto = require("crypto");

function verifyWebhook(rawBody, signature, signingSecret) {
  const expected = crypto
    .createHmac("sha256", signingSecret)
    .update(rawBody)
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(expected, "hex"),
    Buffer.from(signature, "hex")
  );
}

Evento	Cuándo se dispara
`score.updated`	El score DataCred del usuario cambió tras un recálculo.
`consent.granted`	El usuario otorgó consentimiento a un socio para acceder al buró.
`consent.revoked`	El usuario revocó un consentimiento otorgado antes.
`inquiry.hard_pull`	Se creó una inquiry de tipo hard pull en el archivo de un usuario.
`adverse_action.filed`	Se registró una notificación de acción adversa para un usuario.
`tradeline.reported`	Un socio furnisher reportó un nuevo tradeline.
`tradeline.updated`	Se actualizó un tradeline existente.
`negative_item.added`	Se agregó un ítem negativo al archivo de un usuario.
`dispute.opened`	Un consumidor abrió una disputa de crédito.
`dispute.resolved`	Se resolvió una disputa de crédito.

06 · Errores

Códigos de error

Todos los errores siguen el formato: { success: false, error: { code, message, requestId } }

Código	HTTP	Significado
`INVALID_API_KEY`	401	API key ausente, revocada o expirada.
`API_KEY_EXPIRED`	401	La API key pasó su fecha de expiración.
`PARTNER_INACTIVE`	403	La cuenta de socio está suspendida o pendiente de aprobación.
`DENIED_NO_CONSENT`	403	No hay una base de consentimiento válida para este pull.
`USER_NOT_FOUND`	404	El userId solicitado no existe en DataCred.
`QUOTA_EXCEEDED`	429	Alcanzaste el límite de consultas de tu plan mensual. Escríbenos para ampliarlo.
`INSUFFICIENT_DATA`	422	No hay datos suficientes para calcular un score de este usuario.
`VALIDATION_ERROR`	400	Al body le faltan campos obligatorios o tiene valores inválidos.
`RATE_LIMIT_EXCEEDED`	429	Demasiadas solicitudes. Espera y reintenta luego de los segundos indicados en Retry-After.

07 · Precios y límites

Precios y límites

El precio por consulta baja según cuántas hagas al mes. El sandbox es gratis y solo se cobran los pulls servidos con éxito, los negados o con error no consumen tu plan.

Volumen mensual	Precio por consulta
Sandbox (pruebas)	Gratis	Datos sintéticos, sin cobro
0 a 50 / mes	$1.00	por consulta
51 a 200 / mes	$0.85	por consulta
201 a 1,000 / mes	$0.65	por consulta
1,001 o más / mes	$0.40	por consulta

Límite de velocidad: hasta 120 consultas por minuto. Si lo superas recibes un 429 con el header Retry-After.

Cada respuesta incluye los headers X-RateLimit-Limit, X-RateLimit-Remaining y Retry-After. ¿Volúmenes mayores? Escríbenos.

08 · Sandbox

Sandbox

El entorno de sandbox refleja producción casi por completo, con estas diferencias:

No se accede a datos reales de personas; se usan perfiles sintéticos.
No se cobra ninguna consulta, ni siquiera los pulls HARD.
Los webhooks se disparan a tus endpoints con payloads sintéticos.
Las keys empiezan con dc_test_ en vez de dc_live_.
Aplica el mismo límite de 120 consultas por minuto.

¿Listo para producción? Registra tu empresa y nuestro equipo revisa y activa tu key de producción en 1 a 2 días hábiles.