🇨🇴 API v1.0

API de Prevención de Fraude

Valida la identidad de compradores colombianos en tiempo real. Consulta cédulas, teléfonos, direcciones y genera un score de riesgo antes de aprobar cada transacción.

Base URL

# Producción

https://api.pekkasoft.co/v1

# Sandbox (pruebas)

https://sandbox.pekkasoft.co/v1

Respuesta Rápida

Latencia promedio <200ms

99.9% Uptime

SLA garantizado

+50M Registros

Base de datos Colombia

Quick Start

Sigue estos 3 pasos para empezar a validar transacciones en menos de 5 minutos:

1

Obtén tu API Key

Regístrate en nuestro portal y obtén tu API Key de sandbox. Tendrás 100 consultas gratis durante 14 días para probar la integración.

Solicitar API Key

2

Instala el SDK

composer require pekkasoft/fraude-co

pip install pekkasoft-fraude-co

npm install @pekkasoft/fraude-co

3

Haz tu primera verificación

$client = new PekkaSoft\FraudeCO('tu_api_key');

$resultado = $client->verify([
    'cedula'    => '1020304050',
    'telefono'  => '+573156789012',
    'email'     => 'cliente@correo.co',
    'ciudad'    => 'Bogotá',
    'monto'     => 350000 // COP
]);

if ($resultado->riesgo === 'bajo') {
    aprobarPedido();
} elseif ($resultado->riesgo === 'alto') {
    rechazarPedido();
} else {
    revisionManual();
}

Autenticación

Todas las peticiones a la API requieren autenticación mediante un API Key. Incluye tu key en el header X-API-Key.

curl -X POST https://api.pekkasoft.co/v1/verify \
  -H "X-API-Key: tu_api_key_aqui" \
  -H "Content-Type: application/json" \
  -d '{"cedula": "1020304050"}'

Importante

• Nunca expongas tu API Key en código frontend (JavaScript del navegador)
• Las API Keys de producción y sandbox son diferentes
• Puedes rotar tus keys desde el panel de administración

POST

/verify

Endpoint principal para verificar una transacción completa. Valida cédula, teléfono, email y dirección, y devuelve un score de riesgo con recomendación.

Parámetros

Parámetro	Tipo	Requerido	Descripción
cedula	string	Sí	Número de cédula (8-10 dígitos)
telefono	string	No	Celular con código país (+57...)
email	string	No	Correo electrónico del comprador
direccion	string	No	Dirección de envío
ciudad	string	No	Ciudad de entrega
monto	integer	No	Monto de la transacción en COP

Ejemplo de Request

curl -X POST https://api.pekkasoft.co/v1/verify \
  -H "X-API-Key: sk_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "cedula": "1020304050",
    "telefono": "+573156789012",
    "email": "juan.perez@gmail.com",
    "direccion": "Calle 85 #15-30 Apto 501",
    "ciudad": "Bogotá",
    "monto": 450000
  }'

Ejemplo de Response

{
  "success": true,
  "transaction_id": "txn_7f8a9b2c3d4e",
  "risk_score": 15,
  "risk_level": "bajo",
  "recommendation": "aprobar",
  "cedula": {
    "valid": true,
    "nombre": "JUAN CARLOS PEREZ MARTINEZ",
    "estado": "vigente",
    "lugar_expedicion": "Bogotá D.C."
  },
  "telefono": {
    "valid": true,
    "operador": "Claro",
    "tipo": "pospago",
    "antiguedad_meses": 36,
    "match_titular": true
  },
  "email": {
    "valid": true,
    "domain_age_days": 8500,
    "disposable": false
  },
  "direccion": {
    "valid": true,
    "estandarizada": "CL 85 15 30 AP 501",
    "estrato": 5,
    "zona_riesgo": "bajo"
  },
  "risk_factors": [],
  "created_at": "2024-12-01T14:30:00-05:00"
}

GET

/cedula/{numero}

Consulta únicamente los datos de una cédula de ciudadanía colombiana.

Ejemplo

curl https://api.pekkasoft.co/v1/cedula/1020304050 \
  -H "X-API-Key: sk_live_abc123..."

Response

{
  "cedula": "1020304050",
  "valid": true,
  "nombre_completo": "JUAN CARLOS PEREZ MARTINEZ",
  "primer_nombre": "JUAN",
  "segundo_nombre": "CARLOS",
  "primer_apellido": "PEREZ",
  "segundo_apellido": "MARTINEZ",
  "estado": "vigente",
  "fecha_expedicion": "2010-05-15",
  "lugar_expedicion": "Bogotá D.C."
}

Códigos de Error

Código	Mensaje	Descripción
400	bad_request	Parámetros inválidos o faltantes
401	unauthorized	API Key inválida o no proporcionada
403	forbidden	Sin permisos para este endpoint
404	not_found	Recurso no encontrado (cédula inválida, etc.)
429	rate_limit_exceeded	Has superado el límite de consultas
500	internal_error	Error interno del servidor

Sandbox (Pruebas)

Usa el ambiente de sandbox para probar tu integración sin afectar datos reales. Incluimos cédulas y teléfonos de prueba con diferentes escenarios.

Datos de Prueba

Cédula	Escenario	Risk Score
1000000001	Transacción aprobada (riesgo bajo)	10
1000000002	Revisión manual (riesgo medio)	55
1000000003	Rechazada (riesgo alto)	90
1000000004	Cédula no encontrada	N/A
1000000005	En listas restrictivas (SARLAFT)	100

Nota

El sandbox no consulta fuentes de datos reales. Los datos de prueba son ficticios y se reinician cada 24 horas. Las API Keys de sandbox empiezan con sk_test_.

Límites de Uso

Plan	Consultas/mes	Rate Limit	Timeout
Emprendedor	1,000	10 req/seg	30s
Negocio	10,000	50 req/seg	30s
Corporativo	100,000	200 req/seg	30s