API de evaluaciones Talentix

Tu sistema guarda el id del candidato y el de la evaluación. Talentix devuelve un enlace. El candidato abre ese enlace y responde en Talentix. Cuando termina, lees el JSON y el PDF y los muestras en el expediente, junto con el texto «Evaluación provista por Talentix».

Talentix te entrega, por un canal privado:

• Una clave de empresa. Empieza por tix_live_. Se muestra una sola vez. Si se pierde, se revoca y se crea otra.
• El valor del header apikey.

Tu empresa en Talentix necesita un administrador, saldo de tokens y el módulo API encendido. Si el módulo está apagado, la API responde 403.

Base: https://syurfkekgacsujheoaxq.supabase.co/functions/v1/partner-api

En todas las llamadas:

Authorization: Bearer tix_live_...
apikey: <valor entregado por Talentix>
Content-Type: application/json

La empresa se identifica con la clave. No envíes un id de empresa en el cuerpo.

Devuelve las pruebas que puedes asignar y las baterías.

{ "tokens_disponibles": 120 }

Baterías

Puedes asignar de una sola forma:

• prueba_id: una prueba
• bateria_id: una batería de la tabla
• prueba_ids: dos o más pruebas del catálogo, sin repetir

Pruebas disponibles

• disc
• bfi44
• neoffi
• ipipneo120
• neopir
• sixteenpf
• lazarus
• bis11
• dass21
• mbi
• srq
• gordon
• kostick
• ipv
• cleaver
• zavic
• bateria_psicosocial
• test_acrofobia_altura_v2
• test_claustrofobia_espacios_confinados_v1
• raven_spm
• cfit3a
• cfit2a
• terman
• figuras
• clima_corta
• clima_completa

external_id es el id del candidato en tu sistema. nombre es obligatorio. Si envías el mismo external_id, Talentix actualiza la ficha.

{
  "nombre": "Ana Pérez",
  "email": "ana@empresa.com",
  "telefono": "3000000000",
  "documento": "1234567890",
  "tipo_documento": "CC"
}

{
  "id": "uuid",
  "external_id": "cand-8841",
  "provider": {
    "name": "Talentix",
    "statement": "Evaluación provista por Talentix",
    "logo_url": "https://talentix.app/favicon.ico"
  }
}

Crea el candidato antes de asignar la prueba.

external_assignment_id y client_reference son opcionales. expires_in_hours también: el valor por defecto es 72 y el máximo es 720.

{
  "external_candidate_id": "cand-8841",
  "external_assignment_id": "eval-2026-19",
  "bateria_id": "seleccion_basica",
  "expires_in_hours": 72,
  "client_reference": { "expediente": "EXP-19" }
}

{
  "provider": {
    "name": "Talentix",
    "statement": "Evaluación provista por Talentix",
    "logo_url": "https://talentix.app/favicon.ico"
  },
  "id": "uuid-de-talentix",
  "external_id": "eval-2026-19",
  "status": "pending",
  "assessment_url": "https://....talentix.app/evaluacion-api/...",
  "tokens_charged": 2,
  "battery": { "id": "seleccion_basica" },
  "items": [
    {
      "prueba_id": "disc",
      "prueba_nombre": "BehaviorScan",
      "status": "pending",
      "tokens": 1
    }
  ]
}

El saldo se descuenta al asignar, por el total de la prueba o de la batería. Si no alcanza para todo, no se crea ninguna prueba y no se descuenta nada. Repetir la misma llamada con el mismo external_assignment_id devuelve la asignación ya creada y no cobra de nuevo. Otro external_assignment_id es una evaluación nueva y sí cobra.

Guarda id. Muestra assessment_url en el expediente. El candidato abre ese enlace y responde en Talentix. En una batería, al terminar cada prueba regresa a la misma página para continuar con la siguiente.

status puede ser pending, in_progress o completed. El grupo queda completed cuando todas sus pruebas terminaron.

Devuelve el mismo tipo de resumen que la asignación, con el estado actual. El id es el que devolvió Talentix al crear la asignación.

Esta respuesta es el dato que debes guardar.

{
  "provider": {
    "name": "Talentix",
    "statement": "Evaluación provista por Talentix",
    "logo_url": "https://talentix.app/favicon.ico"
  },
  "assignment_id": "uuid-de-talentix",
  "status": "completed",
  "battery": { "id": "seleccion_basica" },
  "results": [
    {
      "prueba_id": "disc",
      "prueba_nombre": "BehaviorScan",
      "status": "completed",
      "tokens": 1,
      "pdf_status": "ready",
      "completed_at": "2026-09-28T20:00:00.000Z",
      "puntaje_total": 0,
      "puntaje_por_dimension": {},
      "interpretacion": {},
      "recomendaciones": "Texto de recomendaciones"
    }
  ]
}

Hasta que una prueba esté completed, sus puntajes llegan en null.

En el expediente muestra:

• provider.statement
• puntaje_total
• puntaje_por_dimension
• interpretacion
• recomendaciones
• el PDF de cada prueba

Cuando pdf_status es ready, la respuesta es el archivo application/pdf.

Si aún no está listo, la respuesta es 409 y el cuerpo contiene pdf_pending. Vuelve a consultar más tarde. Si el candidato cerró la página antes de tiempo, el PDF se genera cuando abre de nuevo la misma assessment_url. El JSON del resultado se conserva aunque el PDF siga pendiente.

Opcional. Una dirección HTTPS por empresa:

{ "url": "https://tu-dominio.com/talentix/webhook" }

La primera respuesta incluye secret. Guárdalo en ese momento. Si después cambias la URL, el secreto no se vuelve a mostrar.

Cuando todas las pruebas del grupo terminaron, Talentix envía:

Content-Type: application/json
X-Talentix-Signature: sha256=<hmac en hexadecimal>

{
  "event": "assignment.completed",
  "provider": {
    "name": "Talentix",
    "statement": "Evaluación provista por Talentix",
    "logo_url": "https://talentix.app/favicon.ico"
  },
  "assignment_id": "uuid-de-talentix",
  "status": "completed",
  "battery": { "id": "seleccion_basica" },
  "results": []
}

La firma es el HMAC-SHA256 del cuerpo tal como llegó, con el secreto del webhook. El resultado va en hexadecimal, en minúsculas, después de sha256=.

import { createHmac, timingSafeEqual } from "node:crypto";

function firmaValida(rawBody, signatureHeader, secret) {
  const expected =
    "sha256=" + createHmac("sha256", secret).update(rawBody).digest("hex");
  const a = Buffer.from(signatureHeader);
  const b = Buffer.from(expected);
  if (a.length !== b.length) return false;
  return timingSafeEqual(a, b);
}

Responde con un código 2xx. El mismo assignment_id puede llegar más de una vez: regístralo una sola vez. El aviso puede tardar unos minutos. Si no llega, usa GET /v1/assignments/{id}/results.

1. GET /v1/balance y GET /v1/catalog
2. PUT /v1/candidates/{external_id}
3. POST /v1/assignments y guardar id y assessment_url
4. Mostrar el enlace en el expediente
5. Cuando el candidato termine, leer GET /v1/assignments/{id}/results
6. Descargar cada PDF con pdf_status en ready
7. Mostrar los puntajes, el texto «Evaluación provista por Talentix» y el PDF

BASE="https://syurfkekgacsujheoaxq.supabase.co/functions/v1/partner-api"

curl -s "$BASE/v1/balance" \
  -H "Authorization: Bearer tix_live_..." \
  -H "apikey: <valor entregado por Talentix>" \
  -H "Content-Type: application/json"

curl -s "$BASE/v1/catalog" \
  -H "Authorization: Bearer tix_live_..." \
  -H "apikey: <valor entregado por Talentix>" \
  -H "Content-Type: application/json"

curl -s -X PUT "$BASE/v1/candidates/cand-8841" \
  -H "Authorization: Bearer tix_live_..." \
  -H "apikey: <valor entregado por Talentix>" \
  -H "Content-Type: application/json" \
  -d '{"nombre":"Ana Pérez","email":"ana@empresa.com","telefono":"3000000000","documento":"1234567890","tipo_documento":"CC"}'

curl -s -X POST "$BASE/v1/assignments" \
  -H "Authorization: Bearer tix_live_..." \
  -H "apikey: <valor entregado por Talentix>" \
  -H "Content-Type: application/json" \
  -d '{"external_candidate_id":"cand-8841","external_assignment_id":"eval-2026-19","bateria_id":"seleccion_basica","expires_in_hours":72,"client_reference":{"expediente":"EXP-19"}}'

curl -s "$BASE/v1/assignments/uuid-de-talentix/results" \
  -H "Authorization: Bearer tix_live_..." \
  -H "apikey: <valor entregado por Talentix>" \
  -H "Content-Type: application/json"

curl -s -o disc.pdf "$BASE/v1/assignments/uuid-de-talentix/items/disc/pdf" \
  -H "Authorization: Bearer tix_live_..." \
  -H "apikey: <valor entregado por Talentix>" \
  -H "Content-Type: application/json"