API Documentation

Psicometrías Platform — REST API Reference

v1.0 JSON Bearer Auth

Base URL: https://psicometricas.alobri.com/api

¿Primera vez? Así obtienes tu API key

Regístrate o inicia sesión en alobri.com.
Elige un plan API: Starter (gratis, 100 tokens/mes), Growth o Enterprise.
Entra a /mi-api y haz clic en «Generar mi token».
Cópialo (sólo se muestra una vez) y úsalo abajo para probar los endpoints.

Cada llamada consume tokens del cap mensual de tu plan. Excedente se cobra a la tarifa USD/token de tu plan (Growth y Enterprise).

Autenticación

API Token (Bearer) — API v1

Bearer

Se usará automáticamente en las solicitudes de prueba.

Internal Secret — API Interna

X-Internal-Secret

Para endpoints /api/internal/*

Formato de Respuesta Estándar

Exitosa (2xx)

{
  "success": true,
  "message": "...",
  "data": { ... }
}

Error (4xx/5xx)

{
  "success": false,
  "message": "...",
  "data": null
}

Paginada

{
  "success": true,
  "data": [ ... ],
  "meta": {
    "current_page": 1,
    "per_page": 25,
    "total": 112
  }
}

Rate Limit: Los headers X-RateLimit-Limit y X-RateLimit-Remaining se incluyen en cada respuesta. Al exceder el límite se retorna 429 con Retry-After.

Catálogo de Tests

GET /api/v1/tests Listar todos los tests disponibles

Bearer Auth Rate Limit

Retorna el catálogo completo de pruebas psicométricas disponibles para el cliente.

Parámetros

Ninguno

Respuesta 200

{
  "success": true,
  "message": "Test catalog retrieved.",
  "data": [
    {
      "id": 1,
      "title": "Terman-Merrill",
      "type": "Inteligencia",
      "type_id": 3,
      "time": "45:00",
      "instructions": "Lea cada pregunta...",
      "token_cost": 2,
      "sections_count": 4,
      "questions_count": 80
    }
  ]
}

Probar Endpoint

GET /api/v1/tests/{id} Obtener un test por ID

Bearer Auth Rate Limit

Parámetros de Ruta

Parámetro	Tipo	Descripción
id	integer requerido	ID interno del test

Respuesta 200

{
  "success": true,
  "data": {
    "id": 1,
    "title": "Terman-Merrill",
    "type": "Inteligencia",
    // ... misma estructura que el listado
  }
}

Respuesta 404

{ "success": false, "message": "Test not found." }

Probar Endpoint

id:

Candidatos

POST /api/v1/candidates Crear un candidato

Bearer Auth Rate Limit

Crea un nuevo candidato y lo vincula al cliente API mediante un external_candidate_id.

Body (JSON)

Campo	Tipo	Descripción
external_candidate_id	string requerido	ID externo único del candidato (max 255)
firstname	string requerido	Nombre
lastname	string requerido	Apellido
email	string requerido	Correo electrónico válido
phone	string opcional	Teléfono (max 50)
date_of_birth	date opcional	Fecha de nacimiento
gender	string opcional	Género
postal_code	string opcional	Código postal (max 10)
country	string opcional	País (max 100)

Ejemplo de Request

{
  "external_candidate_id": "EXT-001",
  "firstname": "Juan",
  "lastname": "Pérez",
  "email": "juan@ejemplo.com",
  "phone": "+52-555-0100"
}

Respuesta 201

{
  "success": true,
  "message": "Candidate created.",
  "data": {
    "external_id": "EXT-001",
    "id": 123,
    "name": "Juan Pérez",
    "email": "juan@ejemplo.com",
    "phone": "+52-555-0100",
    "created_at": "2026-02-26T10:00:00+00:00"
  }
}

Probar Endpoint

GET /api/v1/candidates Listar candidatos del cliente

Bearer Auth Rate Limit

Retorna todos los candidatos vinculados al cliente autenticado.

Parámetros

Ninguno

Respuesta 200

{
  "success": true,
  "data": [
    {
      "external_id": "EXT-001",
      "id": 123,
      "name": "Juan Pérez",
      "email": "juan@ejemplo.com"
    }
  ]
}

Probar Endpoint

GET /api/v1/candidates/{external_id} Obtener candidato por ID externo

Bearer Auth Rate Limit

Parámetros de Ruta

Parámetro	Tipo	Descripción
external_id	string requerido	ID externo asignado al crear el candidato

Respuesta 404

{ "success": false, "message": "Candidate not found." }

Probar Endpoint

external_id:

Evaluaciones

POST /api/v1/evaluations Asignar evaluaciones a candidato

Bearer Auth Rate Limit Test Access Billing Quota

Asigna uno o más tests a un candidato. Consume cuota (tokens o suscripción). Retorna un código de acceso para que el candidato inicie sesión.

Body (JSON)

Campo	Tipo	Descripción
external_candidate_id	string requerido	ID externo del candidato existente o nuevo
test_ids	array[int] requerido	IDs de tests a asignar (mínimo 1)
candidate	object condicional	Datos del candidato si no existe aún
candidate.firstname	string	Nombre (requerido si se envía candidate)
candidate.lastname	string	Apellido (requerido si se envía candidate)
candidate.email	string	Email (requerido si se envía candidate)

Ejemplo de Request

{
  "external_candidate_id": "EXT-001",
  "test_ids": [1, 3],
  "candidate": {
    "firstname": "María",
    "lastname": "López",
    "email": "maria@ejemplo.com"
  }
}

Respuesta 201

{
  "success": true,
  "message": "Evaluations assigned successfully.",
  "data": {
    "access_code": "ABC123",
    "evaluation_url": "https://app.example.com/login#tab-candidate",
    "evaluations": [
      {
        "id": 55,
        "test": { "id": 1, "title": "Terman-Merrill" },
        "status": "pending",
        "progress": { "sections_completed": 0, "sections_total": 4 }
      }
    ]
  }
}

Errores Posibles

Código	Caso
`402`	Saldo de tokens insuficiente o límite de suscripción alcanzado
`422`	Tests no disponibles vía API o candidato no encontrado sin bloque `candidate`

Probar Endpoint

GET /api/v1/evaluations Listar evaluaciones (paginado)

Bearer Auth Rate Limit

Query Params

Parámetro	Tipo	Descripción
per_page	integer opcional	Items por página (default: 25)

Respuesta 200

{
  "success": true,
  "data": [ /* evaluaciones */ ],
  "meta": { "current_page": 1, "per_page": 25, "total": 50 }
}

Probar Endpoint

GET /api/v1/evaluations/{id} Obtener evaluación por ID

Bearer Auth Rate Limit

Parámetros de Ruta

Parámetro	Tipo	Descripción
id	integer requerido	ID interno de la evaluación (UserAssignedTest)

Probar Endpoint

id:

Resultados

GET /api/v1/evaluations/{id}/results Obtener resultados de evaluación

Bearer Auth Rate Limit

Retorna los resultados calculados (scores) de una evaluación completada. Registra un evento result_queried.

Respuesta 200

{
  "success": true,
  "data": {
    "user_id": 123,
    "user_name": "Juan Pérez",
    "token": "eval-token-string",
    "application": {
      "id": 10,
      "vacancy": "Software Engineer",
      "code": "APP-2026-001"
    },
    "responses_count": 80,
    "scores": { /* estructura varía por tipo de test */ }
  }
}

Probar Endpoint

id:

GET /api/v1/evaluations/{id}/pdf Descargar reporte PDF

Bearer Auth Rate Limit

Genera y descarga un reporte PDF con los resultados. Retorna Content-Type: application/pdf.

Respuesta 200

Content-Type: application/pdf
Content-Disposition: attachment; filename="results_{id}.pdf"

[Binary PDF stream]

Probar Endpoint

id:

POST /api/v1/evaluations/{id}/pdf/webhook Enviar PDF por webhook

Bearer Auth Rate Limit

Encola el envío asíncrono del PDF al webhook configurado del cliente. Requiere tener un webhook_url configurado.

Body

Ninguno

Respuesta 200

{ "success": true, "message": "PDF webhook delivery queued." }

Respuesta 422

{ "success": false, "message": "No webhook URL configured for this client." }

Probar Endpoint

id:

Facturación

GET /api/v1/billing/usage Estado actual de facturación

Bearer Auth Rate Limit

Retorna el estado de facturación actual. La estructura varía según el tipo de cliente.

Respuesta por Tipo de Cliente

{
  "data": {
    "client_type": "token",
    "token_balance": 150,
    "tokens_consumed_total": 42
  }
}

{
  "data": {
    "client_type": "subscription",
    "subscription_plan": "default",
    "subscription_eval_limit": 100,
    "subscription_evals_used": 38,
    "subscription_evals_remaining": 62,
    "subscription_ends_at": "2026-03-31T23:59:59+00:00"
  }
}

{
  "data": {
    "client_type": "government",
    "access": "unlimited",
    "evaluations_assigned_total": 1540
  }
}

Probar Endpoint

GET /api/v1/billing/history Historial de uso (paginado)

Bearer Auth Rate Limit

Log paginado de todos los eventos de uso de la API.

Query Params

Parámetro	Tipo	Descripción
per_page	integer opcional	Items por página (default: 25)

Acciones Registradas

evaluation_assigned result_queried pdf_downloaded pdf_webhook_sent

Probar Endpoint

Configuración de Webhook

Verifica que el webhook viene de Alobri

Cada request POST a tu webhook_url incluye los headers:

X-Webhook-Event — tipo de evento (ej. evaluation.completed)
X-Webhook-Delivery — ID único de este intento
X-Webhook-Timestamp — epoch segundos del envío
X-Webhook-Signature — t=<timestamp>,v1=<hex>

El cliente debe:

Extraer t y v1 del header.
Rechazar si |now - t| > 300s (anti-replay).
Calcular HMAC_SHA256(webhook_secret, "<t>." + raw_body).
Comparar con v1 en tiempo constante (hash_equals).
Solo entónces procesar el JSON.

Ejemplo Node.js

// Express + body-parser raw
const crypto = require('crypto');
app.post('/webhook', express.raw({type: 'application/json'}), (req, res) => {
  const sigHeader = req.headers['x-webhook-signature'] || '';
  const [tPart, sigPart] = sigHeader.split(',');
  const ts = tPart?.split('=')[1];
  const sig = sigPart?.split('=')[1];
  if (Math.abs(Date.now()/1000 - ts) > 300) return res.sendStatus(401);
  const expected = crypto.createHmac('sha256', process.env.WEBHOOK_SECRET)
    .update(ts + '.' + req.body.toString()).digest('hex');
  if (!crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected))) return res.sendStatus(401);
  const payload = JSON.parse(req.body);
  // ...procesa el evento
  res.sendStatus(200);
});

Ejemplo PHP

$body = file_get_contents('php://input');
$header = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? '';
parse_str(str_replace(',', '&', $header), $parts);
if (abs(time() - (int) $parts['t']) > 300) http_response_code(401);
$expected = hash_hmac('sha256', $parts['t'] . '.' . $body, $_ENV['WEBHOOK_SECRET']);
if (! hash_equals($expected, $parts['v1'])) http_response_code(401);

Si haces tu primer PUT /api/v1/webhook sin pasar webhook_secret, generamos uno por ti y te lo devolvemos en el campo webhook_secret del response (sólo esa única vez). Para rotar, manda un nuevo valor en otro PUT.

GET /api/v1/webhook Ver configuración de webhook

Bearer Auth Rate Limit

Respuesta 200

{
  "data": {
    "webhook_url": "https://partner.example.com/hooks/psico",
    "has_secret": true
  }
}

Probar Endpoint

PUT /api/v1/webhook Actualizar configuración de webhook

Bearer Auth Rate Limit

Body (JSON)

Campo	Tipo	Descripción
webhook_url	string requerido	URL válida del webhook (max 2048)
webhook_secret	string opcional	Nuevo secreto HMAC-SHA256 (max 255). Si se omite, se conserva el actual.

Probar Endpoint

POST /api/v1/webhook/test Enviar webhook de prueba

Bearer Auth Rate Limit

Envía un evento de prueba al webhook configurado y retorna el resultado de la entrega.

Respuesta 200 (entrega exitosa)

{
  "data": {
    "success": true,
    "delivery_id": 7,
    "http_status": 200,
    "message": "Webhook delivered successfully."
  }
}

Detalles de Entrega

Método: POST al webhook_url
Timeout: 30 segundos
Headers: X-Webhook-Event, X-Webhook-Delivery
Si hay secret: X-Webhook-Signature: hmac-sha256(payload, secret)
Reintentos en caso de falla: 30s, 2m, 10m, 1h, 2h (máx 5 intentos)

Probar Endpoint

API Interna (Aprovisionamiento de Clientes)

Autenticación: Header X-Internal-Secret verificado contra la tabla ApiInternalConsumer. Uso exclusivo para comunicación máquina a máquina.

GET /api/internal/clients Listar clientes API

Query Params

Parámetro	Tipo	Descripción
employer_id	integer opcional	Filtrar por employer_id en el campo notes

Respuesta 200

{
  "data": [
    {
      "client_id": 1,
      "slug": "acme-corp",
      "name": "ACME Corp",
      "client_type": "government",
      "is_active": true,
      "company_id": 10
    }
  ]
}

Probar Endpoint

POST /api/internal/clients Crear/reactivar cliente API

Crea un nuevo cliente API y emite su primer token Sanctum. Si un cliente con el mismo slug fue eliminado, lo restaura y emite un token nuevo.

Body (JSON)

Campo	Tipo	Descripción
name	string requerido	Nombre del cliente (se genera slug automáticamente)
email	string requerido	Email de contacto
company_id	integer opcional	ID de compañía interna
client_type	string opcional	`token` \| `government` \| `subscription` (default: government)
employer_id	integer opcional	Almacenado en notes
token_balance	integer opcional	Balance inicial (solo tipo token, default: 0)
subscription_days	integer opcional	Duración en días (solo tipo subscription, default: 30)
subscription_eval_limit	integer opcional	Límite de evaluaciones (solo tipo subscription, default: 100)

Respuesta 201

{
  "data": {
    "client_id": 5,
    "slug": "acme-corp",
    "client_type": "token",
    "is_active": true,
    "api_token": "1|plaintexttoken..."
  }
}
// IMPORTANTE: El api_token solo se muestra una vez.

Probar Endpoint

GET /api/internal/clients/{slug} Detalle de cliente por slug

Parámetros de Ruta

Parámetro	Tipo	Descripción
slug	string requerido	Slug del cliente (generado del nombre)

Respuesta 200

{
  "data": {
    "client_id": 5,
    "slug": "acme-corp",
    "name": "ACME Corp",
    "client_type": "token",
    "is_active": true,
    "has_token": true,
    "billing": {
      "token_balance": 150,
      "subscription_plan": null
    }
  }
}

Probar Endpoint

slug:

PATCH /api/internal/clients/{slug}/toggle Activar/desactivar cliente

Alterna el estado activo/inactivo del cliente. Si se reactiva sin tokens existentes, genera uno nuevo.

Body (JSON)

Campo	Tipo	Descripción
enable	boolean opcional	Forzar estado. Si se omite, alterna el actual.

Respuesta 200

{
  "data": {
    "client_id": 5,
    "slug": "acme-corp",
    "is_active": true,
    "api_token": "3|newtoken..." // solo si se generó nuevo
  }
}

Probar Endpoint

slug:

Tipos de Cliente

Tipo	Modelo de Facturación	Cuota	Unidad de Costo
`government`	Sin facturación	Ilimitada	N/A
`token`	Balance de tokens	Pre-verificado por request	`token_cost` por test (tabla ApiTestTokenCost)
`subscription`	Límite de evals + fecha de expiración	Pre-verificado por request	1 eval por test asignado