Referencia de la API · Documentación técnica

Construye sobre DataCred.

API REST con auditoría inmutable de cada consulta y cinco modelos de score calibrados para el riesgo crediticio venezolano. Registra tu empresa y, al aprobarla, crea tus API keys.

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), una contraseña y las cuatro confirmaciones legales explícitas. No envíes esos booleanos en true si el representante no ha visto y aceptado realmente los documentos enlazados en el registro web. Revisamos tu empresa en 1 a 2 días hábiles; al aprobarla recibes por correo el contrato de afiliación y 10 consultas de cortesía.

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",
    "authorized_representative_attested": true,
    "affiliation_contract_accepted": true,
    "privacy_policy_acknowledged": true,
    "data_processing_authorized": true
  }'
2Crea tu API key en el portal

Con la empresa aprobada, entra al portal de socios y crea tu API key (dc_live_…). Se muestra una sola vez. DataCred tiene una sola clase de llave: toda key es real, consulta datos reales y sus consultas se cobran (las 10 primeras las pagan tus créditos de cortesía).

3Busca a la persona y consulta su reporte

Busca por cédula (gratis) para obtener su userId y luego haz la consulta de evaluación. A la persona le llega un aviso de la consulta.

curl -X POST https://api.datacred.org/v1/partner/search \
  -H "X-API-Key: dc_live_TU_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "identity": { "documentNumber": "V-12345678", "fullName": "Ana Pérez" },
    "purpose": "CREDIT_APPLICATION",
    "legalBasisAttested": true,
    "relationshipReference": "SOL-2026-000123"
  }'

curl -X POST https://api.datacred.org/v1/partner/pull \
  -H "X-API-Key: dc_live_TU_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "<userId>",
    "pullType": "SOFT",
    "purpose": "CREDIT_APPLICATION",
    "scoreModelId": "datacred_consumer"
  }'
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_live_… (recomendada para servidor a servidor)
  • Authorization: Bearer dc_live_…

DataCred tiene una sola clase de API key: dc_live_…. Toda key consulta y reporta datos reales y sus consultas se cobran. Las keys dc_test_… emitidas antes siguen funcionando exactamente igual (también son reales); al regenerarlas salen como dc_live_.

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 por un propósito legítimo. 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? } — purpose permitido: CREDIT_APPLICATION, EXISTING_CREDIT_REVIEW o COLLECTIONSDevuelve: 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 empresa y su acceso al portal. No devuelve API keys: se crean en el portal cuando DataCred aprueba la empresa.

Auth: NingunaBody: { company_name, legal_name, tax_id, industry, contact_email, contact_full_name, password, authorized_representative_attested: true, affiliation_contract_accepted: true, privacy_policy_acknowledged: true, data_processing_authorized: true, country?, website_url?, contact_phone? }Devuelve: partnerId, 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 modeloNombreCaso de usoFactores principalesVentana de consultasPrecio
datacred_consumerDataCred ConsumerScore de historial de crédito para consumidores (UI, resumen general)Historial de pagos (30%), utilización (20%), antigüedad (15%)365 díasSin recargo por modelo
datacred_risk_autoDataCred Risk: AutoSuscripción para crédito automotrizHistorial de pagos (40%), antigüedad (20%), utilización (10%)365 díasSin recargo por modelo
datacred_risk_mortgageDataCred Risk: HipotecarioSuscripción hipotecaria (ventana de consultas de 2 años)Utilización (25%), registros públicos (15%), historial (30%)730 díasSin recargo por modelo
datacred_risk_bankcardDataCred Risk: TarjetaSuscripción para tarjetas de créditoUtilización (30%), mezcla de cuentas (15%), historial (25%)365 díasSin recargo por modelo
datacred_risk_personalDataCred Risk: Préstamo PersonalPréstamos personales sin garantía colateralHistorial (28%), ítems negativos (15%), utilización (18%)365 díasSin 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")
  );
}
EventoCuándo se dispara
score.updatedEl score DataCred del usuario cambió tras un recálculo.
consent.grantedEl usuario otorgó consentimiento a un socio para acceder al buró.
consent.revokedEl usuario revocó un consentimiento otorgado antes.
inquiry.hard_pullSe creó una inquiry de tipo hard pull en el archivo de un usuario.
adverse_action.filedSe registró una notificación de acción adversa para un usuario.
tradeline.reportedUn socio furnisher reportó un nuevo tradeline.
tradeline.updatedSe actualizó un tradeline existente.
negative_item.addedSe agregó un ítem negativo al archivo de un usuario.
dispute.openedUn consumidor abrió una disputa de crédito.
dispute.resolvedSe 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ódigoHTTPSignificado
INVALID_API_KEY401API key ausente, revocada o expirada.
API_KEY_EXPIRED401La API key pasó su fecha de expiración.
PARTNER_INACTIVE403La cuenta de socio está suspendida o pendiente de aprobación.
DENIED_NO_CONSENT403No hay una base de consentimiento válida para este pull.
USER_NOT_FOUND404El userId solicitado no existe en DataCred.
QUOTA_EXCEEDED429Alcanzaste el límite de consultas de tu plan mensual. Escríbenos para ampliarlo.
INSUFFICIENT_DATA422No hay datos suficientes para calcular un score de este usuario.
VALIDATION_ERROR400Al body le faltan campos obligatorios o tiene valores inválidos.
RATE_LIMIT_EXCEEDED429Demasiadas 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. Reportar clientes es gratis y solo se cobran las consultas de evaluación servidas con éxito; los negados o con error no consumen tu plan.

Volumen mensualPrecio por consulta
Cortesía al aprobar10 gratiscréditos de consulta
1 a 50 / mes$1.00por consulta
51 a 200 / mes$0.85por consulta
201 a 1,000 / mes$0.65por consulta
1,001 o más / mes$0.40por 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 · Llaves y cobros

Llaves y cobros

  • DataCred no tiene un entorno de pruebas: toda API key es real (dc_live_) y consulta y reporta datos reales de personas.
  • Las keys se crean en el portal de socios cuando DataCred aprueba tu empresa.
  • Al aprobarte te regalamos 10 créditos: cada uno paga una consulta de evaluación.
  • Después, cada consulta de evaluación se suma a tu cuenta del mes y se factura a fin de mes. Registrar que otorgaste el crédito no se cobra otra vez.
  • Aplica el límite de 120 consultas por minuto.

¿Listo para empezar? Registra tu empresa y la revisamos en 1 a 2 días hábiles.