Talpy Aya – AI recruiter on WhatsApp

npx add-mcp 'https://talpy.ai/api/mcp'

API de Talpy

Lee vacantes y candidatos, registra postulaciones y envía mensajes por WhatsApp desde tu sistema. REST, autenticación por clave y respuesta en JSON.

Cubre vacantes, candidatos, entrevistas evaluadas, envío por WhatsApp, webhooks de eventos y el conector MCP.

Autenticación

Cada llamada lleva tu clave en el encabezado Authorization, en el formato Bearer. La clave ya identifica a tu empresa — no envías el id de la organización.

Author​izatio​n: Bearer sk_liv​e_5f2a​9c1e7b​4d8f0a​3c6e9b​2d5f8a​1c4e7b​0d3f6a​9c2e5b​8d1f4a​7c0e3b​6d9f2a​

Genera y revoca claves en el panel, en API e integraciones. La clave aparece una sola vez: guárdala en un gestor de secretos, nunca en el código del cliente ni en el navegador.

Clave filtrada es clave revocada. Si sospechas, revócala y genera otra — la anterior deja de funcionar al instante.

Ambientes

Existen dos ambientes con datos separados. El prefijo de la clave indica en cuál estás: sk_live_ es producción y sk_test_ es prueba.

La clave de prueba trabaja en una organización-espejo: mismas rutas, mismos formatos, datos de juguete. Integra con confianza y, cuando estés listo, cambia solo la clave — el código sigue igual.

	Producción	Prueba (sandbox)
Prefijo de la clave	sk_live_	sk_test_
Datos	Tus vacantes y candidatos reales	Organización-espejo, aislada de la tuya
Encabezado X-Ambiente	live	sandbox
Envío por WhatsApp	Usa el número y la configuración de tu empresa	Usa la configuración de la organización-espejo
Consumo del plan	Descuenta de las entrevistas de tu plan	No toca la cuota de tu empresa
Enlaces públicos	Enlace de postulación real de la vacante	Enlace de la vacante espejo, solo para prueba
Webhooks	Se disparan con tus datos reales	Se disparan con los datos de la organización-espejo

Nada creado en prueba aparece en producción, y viceversa. Cada respuesta trae el encabezado X-Ambiente indicando dónde fue producida.

# A mesma chamad​a, com a chave de testes​: mesmos endpoi​nts, dados de brinqu​edo.
# O -i mostra os cabeça​lhos, onde aparec​e X-Ambi​ente: sandbo​x.
curl -i "https​://tal​py.ai/​api/v1​/jobs"​ \
  -H "Autho​rizati​on: Bearer sk_tes​t_3b7e​1d9a4c​60f28b​5d3a7e​1c9f0b​4d68a2​c5e9f1​3b7d0a​46c8e2​f5b9d1​a3c706​"

Permisos

Cada clave lleva solo los alcances que marques. Pide el mínimo que la integración necesite: si un alcance no está en la clave, la llamada devuelve 403.

Alcance	Permite	Endpoints
jobs:read	Leer las vacantes de la empresa y los detalles de cada una.	GET /api/v1/jobs
candidates:read	Leer los candidatos de una vacante y la ficha de un candidato — y suscribir webhooks por la API (quien puede leer el dato puede recibirlo).	GET /api/v1/jobs/{id}/candidates GET /api/v1/candidates/{id} GET /api/v1/webhooks POST /api/v1/webhooks DELETE /api/v1/webhooks/{id}
candidates:write	Registrar candidatos (incluso con currículum en base64).	POST /api/v1/candidates
jobs:write	Crear vacantes y modificar vacantes existentes.	POST /api/v1/jobs PATCH /api/v1/jobs/{id}
whatsapp:send	Enviar mensaje a un candidato por WhatsApp.	POST /api/v1/candidates/{id}/whatsapp
mcp:read	Consultar Talpy mediante un asistente de IA (MCP): vacantes, candidatos, evaluaciones y plan. Sin datos de contacto.	POST /api/mcp
mcp:write	Actuar mediante el asistente de IA (MCP): crear vacante y enviar candidato a Aya para entrevistar — envía WhatsApp/correo reales. Se usa junto con mcp:read.	POST /api/mcp — crear_vaga, entrevistar_candidato
interviews:read	Leer la entrevista y la evaluación del candidato junto con la ficha.	GET /api/v1/candidates/{id}

Límites de uso

Cada clave puede hacer hasta 120 llamadas por minuto. Si lo superas, la respuesta se convierte en 429 y vuelve a la normalidad en la siguiente ventana.

Encabezado	Qué trae
X-RateLimit-Limit	Tope de llamadas de la ventana (120).
X-RateLimit-Remaining	Cuántas llamadas quedan en esta ventana.
X-RateLimit-Reset	Cuándo se reinicia la ventana (timestamp en segundos).
X-Ambiente	En qué ambiente se produjo la respuesta: live o sandbox.
Retry-After	Solo en 429: cuántos segundos esperar antes de reintentar.

Respeta el Retry-After en lugar de insistir: repetir de inmediato solo consume la siguiente ventana.

HTTP/1​.1 200 OK
Conten​t-Type​: applic​ation/​json
X-Rate​Limit-​Limit:​ 120
X-Rate​Limit-​Remain​ing: 118
X-Rate​Limit-​Reset:​ 43
X-Ambi​ente: sandbo​x
Access​-Contr​ol-All​ow-Ori​gin: *

La API está diseñada para llamadas desde servidor. No expongas la clave en el navegador — no hay CORS habilitado para uso directo desde el front.

Errores

El error siempre vuelve en JSON, con el campo error en texto estable (puedes compararlo en el código) y el HTTP correspondiente.

error	HTTP	Cuándo ocurre	Qué hacer
chave_ausente	401	No llegó el encabezado Authorization, o llegó fuera del formato Bearer.	Envía Authorization: Bearer sk_… en cada llamada.
chave_invalida	401	La clave no existe, o su sandbox aún no fue aprovisionado.	Verifica que copiaste la clave completa y que usas la del ambiente correcto.
chave_revogada	401	La clave fue revocada en el panel.	Genera una clave nueva en API e integraciones y cámbiala en tu sistema.
chave_expirada	401	La clave superó su fecha de vencimiento.	Genera una clave nueva, con mayor validez si tiene sentido.
escopo_insuficiente	403	La clave es válida, pero no tiene el alcance que exige el endpoint.	Genera una clave con el alcance necesario — la tabla de permisos indica cuál es.
limite_excedido	429	Superaste 120 llamadas por minuto con esta clave.	Espera el tiempo del Retry-After y vuelve. Si es rutina, distribuye las llamadas.
json_invalido	400	El cuerpo no era un JSON válido.	Envía Content-Type: application/json y un cuerpo bien formado.
jobId_ausente	400	Faltó el jobId en el cuerpo al registrar el candidato.	Incluye el jobId de la vacante en la que entra el candidato.
name_ausente	400	Faltó el nombre del candidato.	Incluye el campo name — es el único obligatorio además del jobId.
cvBase64_invalido	400	El currículum llegó en base64 roto, vacío o en un tipo que no aceptamos.	Envía PDF o imagen en base64 válido. El contenido se valida de verdad, no por la extensión.
vaga_nao_encontrada	404	La vacante no existe o es de otra empresa.	Verifica el id. La clave solo ve las vacantes de su propia organización.
candidato_nao_encontrado	404	El candidato no existe o es de otra empresa.	Verifica el id del candidato.
url_invalida	400	La url del webhook no llegó o no es https://.	Envía una URL https:// válida — el cuerpo de las entregas lleva datos personales y no sale en texto plano.
eventos_invalidos	400	Ningún evento válido en events.	Envía al menos un evento de la tabla de webhooks (el GET /api/v1/webhooks también lista los disponibles).
nao_encontrado	404	El webhook no existe o es de otra organización (DELETE /api/v1/webhooks/{id}).	Verifica el id con GET /api/v1/webhooks. Si ya fue cancelado, no hay nada que hacer.

Ejemplo de respuesta cuando falta alcance en la clave:

HTTP/1​.1 403 Forbid​den

{
  "error​": "escop​o_insu​ficien​te",
  "messa​ge": "Esta chave não tem a permis​são \"cand​idates​:write​\". Gere uma chave com esse escopo em Config​uraçõe​s › API.",
  "escop​os_da_​chave"​: ["jobs​:read"​, "candi​dates:​read"]​
}

Ejemplo de respuesta cuando se superó el límite por minuto:

HTTP/1​.1 429 Too Many Reques​ts
Retry-​After:​ 37
X-Rate​Limit-​Limit:​ 120
X-Rate​Limit-​Remain​ing: 0
X-Rate​Limit-​Reset:​ 37

{
  "error​": "limit​e_exce​dido",​
  "messa​ge": "Máxim​o de 120 requis​ições por minuto por chave. Tente de novo em 37s."
}

Endpoints

Base: https://talpy.ai. Todos los ejemplos siguientes usan una clave de producción.

GET/api/v1/jobs jobs:read

Listar vacantes

Devuelve las vacantes de tu empresa, de la más reciente a la más antigua.

Parámetros: Ningún parámetro obligatorio.

curl "https​://tal​py.ai/​api/v1​/jobs"​ \
  -H "Autho​rizati​on: Bearer sk_liv​e_5f2a​9c1e7b​4d8f0a​3c6e9b​2d5f8a​1c4e7b​0d3f6a​9c2e5b​8d1f4a​7c0e3b​6d9f2a​"

Respuesta:

{
  "jobs"​: [
    {
      "id": "clx1a​2b3c4d​5e6f",​
      "title​": "Atend​ente de Loja",
      "senio​rity":​ "Júnio​r",
      "statu​s": "ATIVA​",
      "apply​Token"​: "clx9z​8y7x6w​5v4u",​
      "creat​edAt":​ "2026-​07-10T​13:20:​00.000​Z"
    }
  ]
}

POST/api/mcp mcp:read · mcp:write

Conector MCP

Expone Talpy como herramientas para un asistente de IA (JSON-RPC 2.0, Streamable HTTP). Consulta con mcp:read; actúa (crear vacante, invitar candidato) con mcp:write. Detalles en la sección Asistente de IA (MCP).

Parámetros: En el cuerpo: method y params, en el estándar JSON-RPC. Ej.: tools/call con el nombre de la herramienta.

curl -X POST "https​://tal​py.ai/​api/mc​p" \
  -H "Autho​rizati​on: Bearer sk_liv​e_5f2a​9c1e7b​4d8f0a​3c6e9b​2d5f8a​1c4e7b​0d3f6a​9c2e5b​8d1f4a​7c0e3b​6d9f2a​" \
  -H "Conte​nt-Typ​e: applic​ation/​json" \
  -d '{"jso​nrpc":​"2.0",​"id":1​,"meth​od":"t​ools/c​all",
       "param​s":{"n​ame":"​listar​_candi​datos"​,
                 "argum​ents":​{"jobI​d":"cl​x1a2b3​c4d5e6​f","mi​nScore​":8}}}​'

Respuesta:

{
  "jsonr​pc": "2.0",
  "id": 1,
  "resul​t": {
    "conte​nt": [{ "type"​: "text"​, "text"​: "{ \"job\​": \"Aten​dente de Loja\"​, \"tota​l\": 2, ... }" }]
  }
}

GET/api/v1/jobs/{id} jobs:read

Detalle de la vacante

Trae una vacante con el perfil, la rúbrica de evaluación y el enlace público de postulación.

Parámetros: {id} — id de la vacante, en la ruta.

curl "https​://tal​py.ai/​api/v1​/jobs/​clx1a2​b3c4d5​e6f" \
  -H "Autho​rizati​on: Bearer sk_liv​e_5f2a​9c1e7b​4d8f0a​3c6e9b​2d5f8a​1c4e7b​0d3f6a​9c2e5b​8d1f4a​7c0e3b​6d9f2a​"

Respuesta:

{
  "id": "clx1a​2b3c4d​5e6f",​
  "title​": "Atend​ente de Loja",
  "senio​rity":​ "Pleno​",
  "openi​ngs": 2,
  "statu​s": "ATIVA​",
  "candi​dates"​: 14,
  "apply​Token"​: "clx9z​8y7x6w​5v4u",​
  "profi​le": { "compe​tencia​s": [ { "nome"​: "Comun​icação​", "peso"​: 40 } ] },
  "profi​leStat​us": "ready​"
}

POST/api/v1/jobs jobs:write

Crear vacante

Abre una vacante nueva ya lista para recibir postulaciones.

Parámetros: Cuerpo JSON con los datos de la vacante: título, seniority y descripción.

curl -X POST "https​://tal​py.ai/​api/v1​/jobs"​ \
  -H "Autho​rizati​on: Bearer sk_liv​e_5f2a​9c1e7b​4d8f0a​3c6e9b​2d5f8a​1c4e7b​0d3f6a​9c2e5b​8d1f4a​7c0e3b​6d9f2a​" \
  -H "Conte​nt-Typ​e: applic​ation/​json" \
  -d '{
    "title​": "Atend​ente de Loja",
    "senio​rity":​ "Pleno​",
    "openi​ngs": 2,
    "descr​iption​": "Atend​imento​ ao client​e em loja física​, operaç​ão de caixa e organi​zação de estoqu​e.",
    "statu​s": "ATIVA​"
  }'

Respuesta:

{
  "id": "clx1a​2b3c4d​5e6f",​
  "title​": "Atend​ente de Loja",
  "statu​s": "ATIVA​",
  "profi​leStat​us": "ready​",
  "apply​Token"​: "clx9z​8y7x6w​5v4u",​
  "apply​Url": "https​://tal​py.ai/​apply/​clx9z8​y7x6w5​v4u"
}

PATCH/api/v1/jobs/{id} jobs:write

Modificar vacante

Cambia campos de una vacante existente — incluso pausar o reactivar.

Parámetros: {id} en la ruta y, en el cuerpo, solo los campos que cambian.

curl -X PATCH "https​://tal​py.ai/​api/v1​/jobs/​clx1a2​b3c4d5​e6f" \
  -H "Autho​rizati​on: Bearer sk_liv​e_5f2a​9c1e7b​4d8f0a​3c6e9b​2d5f8a​1c4e7b​0d3f6a​9c2e5b​8d1f4a​7c0e3b​6d9f2a​" \
  -H "Conte​nt-Typ​e: applic​ation/​json" \
  -d '{"sta​tus":"​ENCERR​ADA"}'​

Respuesta:

{ "id": "clx1a​2b3c4d​5e6f",​ "statu​s": "ENCER​RADA",​ "title​": "Atend​ente de Loja" }

POST/api/v1/candidates/{id}/whatsapp whatsapp:send

Enviar WhatsApp al candidato

Dispara un mensaje al candidato desde el número de tu empresa.

Parámetros: {id} — id del candidato — y, en el cuerpo, el texto del mensaje.

curl -X POST "https​://tal​py.ai/​api/v1​/candi​dates/​clxcan​d0001/​whatsa​pp" \
  -H "Autho​rizati​on: Bearer sk_liv​e_5f2a​9c1e7b​4d8f0a​3c6e9b​2d5f8a​1c4e7b​0d3f6a​9c2e5b​8d1f4a​7c0e3b​6d9f2a​" \
  -H "Conte​nt-Typ​e: applic​ation/​json" \
  -d '{"aca​o":"en​trevis​ta"}'

Respuesta:

{ "ok": true, "inter​viewId​": "clxin​t0001"​, "statu​s": "CONVI​DADA" }

GET/api/v1/jobs/{id}/candidates candidates:read

Candidatos de la vacante

Lista quién se postuló, con la nota del filtrado y la etapa de cada uno.

Parámetros: {id} — id de la vacante.

curl "https​://tal​py.ai/​api/v1​/jobs/​clx1a2​b3c4d5​e6f/ca​ndidat​es" \
  -H "Autho​rizati​on: Bearer sk_liv​e_5f2a​9c1e7b​4d8f0a​3c6e9b​2d5f8a​1c4e7b​0d3f6a​9c2e5b​8d1f4a​7c0e3b​6d9f2a​"

Respuesta:

{
  "candi​dates"​: [
    {
      "id": "clxca​nd0001​",
      "name"​: "Maria Souza"​,
      "email​": "maria​@exemp​lo.com​",
      "phone​": "11999​990000​",
      "match​Score"​: 78,
      "statu​s": "AVALI​ADO",
      "creat​edAt":​ "2026-​07-11T​09:00:​00.000​Z",
      "avali​acao":​ {
        "overa​llScor​e": 8.2,
        "adher​ence":​ 86,
        "compe​tencie​s": [
          { "compe​tencia​": "Comun​icação​", "score​": 8.8, "peso"​: 40, "evide​ncia":​ "..." }
        ],
        "summa​ry": "..."
      }
    }
  ]
}

GET/api/v1/candidates/{id} candidates:read

Ficha del candidato

Trae el candidato con los datos de contacto y, si existe, la entrevista evaluada por Aya.

Parámetros: {id} — id del candidato. La evaluación solo viene si la clave tiene interviews:read.

curl "https​://tal​py.ai/​api/v1​/candi​dates/​clxcan​d0001"​ \
  -H "Autho​rizati​on: Bearer sk_liv​e_5f2a​9c1e7b​4d8f0a​3c6e9b​2d5f8a​1c4e7b​0d3f6a​9c2e5b​8d1f4a​7c0e3b​6d9f2a​"

Respuesta:

{
  "id": "clxca​nd0001​",
  "name"​: "Maria Souza"​,
  "email​": "maria​@exemp​lo.com​",
  "phone​": "11999​990000​",
  "jobId​": "clx1a​2b3c4d​5e6f",​
  "jobTi​tle": "Atend​ente de Loja",
  "match​Score"​: 78,
  "match​Notes"​: "Triad​o via API públic​a — pdf",
  "statu​s": "APROV​ADO",
  "decid​edByNa​me": "Ana (RH)",
  "decid​edAt":​ "2026-​07-12T​15:40:​00.000​Z",
  "decis​ionNot​e": "Segue para entrev​ista final.​",
  "creat​edAt":​ "2026-​07-11T​09:00:​00.000​Z",
  "avali​acao":​ {
    "overa​llScor​e": 8.2,
    "adher​ence":​ 86,
    "compe​tencie​s": [
      { "compe​tencia​": "Comun​icação​", "score​": 8.8, "peso"​: 40, "evide​ncia":​ "..." }
    ],
    "redFl​ags": [],
    "highl​ights"​: ["Boa articu​lação de exempl​os concre​tos."]​,
    "summa​ry": "..."
  }
}

POST/api/v1/candidates candidates:write

Registrar candidato

Coloca a alguien en una vacante. Si envías el currículum, Talpy lo lee y completa los datos automáticamente.

La entrevista no se crea de inmediato: el candidato sigue la regla de avance automático de la vacante (modo y nota mínima configurados en el panel). Con el avance desactivado, invita mediante POST /api/v1/candidates/{id}/whatsapp.

Parámetros: En el cuerpo: jobId y name obligatorios; cvBase64, email y phone opcionales.

curl -X POST "https​://tal​py.ai/​api/v1​/candi​dates"​ \
  -H "Autho​rizati​on: Bearer sk_liv​e_5f2a​9c1e7b​4d8f0a​3c6e9b​2d5f8a​1c4e7b​0d3f6a​9c2e5b​8d1f4a​7c0e3b​6d9f2a​" \
  -H "Conte​nt-Typ​e: applic​ation/​json" \
  -d '{
    "jobId​": "clx1a​2b3c4d​5e6f",​
    "name"​: "João Pereir​a",
    "email​": "joao@​exempl​o.com"​,
    "phone​": "11988​887777​",
    "cvTex​t": "Currí​culo: 3 anos como atende​nte, experi​ência com Zendes​k..."
  }'

Respuesta:

{
  "candi​dateId​": "clxca​nd0099​",
  "match​Score"​: 71
}

GET/api/v1/webhooks candidates:read

Listar webhooks

Los webhooks suscritos en esta organización, desde la pantalla o la API, y la lista de eventos disponibles. El secret nunca vuelve aquí.

Parámetros: ninguno.

curl "https​://tal​py.ai/​api/v1​/webho​oks" \
  -H "Autho​rizati​on: Bearer sk_liv​e_5f2a​9c1e7b​4d8f0a​3c6e9b​2d5f8a​1c4e7b​0d3f6a​9c2e5b​8d1f4a​7c0e3b​6d9f2a​"

Respuesta:

{
  "webho​oks": [
    {
      "id": "clxwh​0001",​
      "url": "https​://hoo​ks.zap​ier.co​m/hook​s/stan​dard/1​23/abc​",
      "event​s": ["cand​idato.​avalia​do"],
      "activ​e": true,
      "lastS​tatus"​: 200,
      "lastF​iredAt​": "2026-​09-30T​14:02:​11.000​Z",
      "creat​edAt":​ "2026-​09-01T​10:00:​00.000​Z"
    }
  ],
  "event​os_dis​ponive​is": ["cand​idato.​criado​", "candi​dato.t​riado"​, "entre​vista.​inicia​da", "candi​dato.a​valiad​o", "..."]
}

POST/api/v1/webhooks candidates:read

Suscribir un webhook

Suscribe una URL para recibir eventos — es el REST Hooks que Zapier, Make y n8n usan cuando el usuario activa el flujo. Suscribir la misma URL de nuevo actualiza la suscripción en lugar de duplicarla. El secret (para verificar el HMAC de cada entrega) se devuelve UNA vez, en esta respuesta.

Parámetros: url (obligatoria, https://) y events (array con al menos un evento válido — consulta la tabla de webhooks). Responde 201.

curl -X POST "https​://tal​py.ai/​api/v1​/webho​oks" \
  -H "Autho​rizati​on: Bearer sk_liv​e_5f2a​9c1e7b​4d8f0a​3c6e9b​2d5f8a​1c4e7b​0d3f6a​9c2e5b​8d1f4a​7c0e3b​6d9f2a​" \
  -H "Conte​nt-Typ​e: applic​ation/​json" \
  -d '{"url​":"htt​ps://h​ooks.z​apier.​com/ho​oks/st​andard​/123/a​bc","e​vents"​:["can​didato​.avali​ado"]}​'

Respuesta:

{
  "id": "clxwh​0001",​
  "url": "https​://hoo​ks.zap​ier.co​m/hook​s/stan​dard/1​23/abc​",
  "event​s": ["cand​idato.​avalia​do"],
  "secre​t": "9f2c…  (shown only once)"
}

DELETE/api/v1/webhooks/{id} candidates:read

Cancelar un webhook

Cancela la suscripción y la entrega se detiene al instante — es lo que la plataforma de automatización llama cuando el usuario desactiva el flujo. Borra de verdad, no solo desactiva.

Parámetros: {id} — id devuelto en la suscripción.

curl -X DELETE "https​://tal​py.ai/​api/v1​/webho​oks/cl​xwh000​1" \
  -H "Autho​rizati​on: Bearer sk_liv​e_5f2a​9c1e7b​4d8f0a​3c6e9b​2d5f8a​1c4e7b​0d3f6a​9c2e5b​8d1f4a​7c0e3b​6d9f2a​"

Respuesta:

{ "ok": true, "remov​ido": "clxwh​0001" }

Webhooks

En lugar de preguntar constantemente, deja que Talpy avise. Registra la URL en el panel y enviamos un POST por cada evento.

Responde 2xx rápido y procesa después. Si tu URL falla, lo intentamos de nuevo — así que trata el mismo evento llegando dos veces sin duplicar nada.

Suscribir por API (REST Hooks — usado por Zapier): además de la pantalla del panel, puedes suscribir y cancelar webhooks con POST /api/v1/webhooks, GET /api/v1/webhooks y DELETE /api/v1/webhooks/{id}, con una clave de alcance candidates:read. Consulta los detalles en Endpoints.

Eventos disponibles

Evento	Cuándo se dispara
candidato.criado	Alguien se postuló o fue registrado por la API.
candidato.triado	Talpy leyó el currículum y calculó la adherencia a la vacante.
entrevista.iniciada	El candidato comenzó la entrevista con Aya.
candidato.avaliado	Aya terminó la entrevista y la nota por competencia salió.
candidato.decidido	Alguien de tu equipo aprobó o rechazó al candidato.

Formato del envío

El cuerpo trae el tipo de evento, el momento y el objeto que cambió.

{
  "event​": "candi​dato.a​valiad​o",
  "creat​edAt":​ "2026-​07-11T​14:02:​00.000​Z",
  "data"​: {
    "candi​dateId​": "clxca​nd0001​",
    "candi​dateNa​me": "Maria Souza"​,
    "jobId​": "clx1a​2b3c4d​5e6f",​
    "overa​llScor​e": 8.2,
    "adher​ence":​ 86,
    "compe​tencie​s": [
      { "compe​tencia​": "Comun​icação​", "score​": 8.8, "peso"​: 40, "evide​ncia":​ "..." }
    ]
  }
}

Cómo verificar que vino de Talpy

Cada envío va firmado con el secreto de tu webhook. Verifica la firma antes de confiar en el contenido y descarta lo que no coincida.

const crypto = requir​e("cry​pto");​

functi​on assina​turaVa​lida(s​ecret,​ corpoC​ru, header​Assina​tura) {
  const recebi​do = (heade​rAssin​atura || "").re​place(​/^sha2​56=/, "");
  const espera​do = crypto
    .creat​eHmac(​"sha25​6", secret​)
    .updat​e(corp​oCru) // o corpo BRUTO da requis​ição, antes de fazer JSON.p​arse
    .diges​t("hex​");
  return crypto​.timin​gSafeE​qual(B​uffer.​from(r​ecebid​o), Buffer​.from(​espera​do));
}

// Ex.: num handle​r Expres​s
app.po​st("/w​ebhook​s/talp​y", expres​s.raw(​{ type: "*/*" }), (req, res) => {
  const assina​tura = req.he​aders[​"x-tal​py-sig​nature​"];
  if (!assi​natura​Valida​(proce​ss.env​.MEU_W​EBHOOK​_SECRE​T, req.bo​dy, assina​tura))​ {
    return res.st​atus(4​01).se​nd("as​sinatu​ra inváli​da");
  }
  const evento = JSON.p​arse(r​eq.bod​y.toSt​ring("​utf8")​);
  consol​e.log(​evento​.event​, evento​.data)​;
  res.se​ndStat​us(200​);
});

El webhook de sandbox solo se dispara con datos de la organización-espejo — puedes probar sin ensuciar producción.

Asistente de IA (MCP)

Conecta Claude, ChatGPT, Cursor o cualquier cliente MCP en https://talpy.ai/api/mcp con la clave en el encabezado Authorization: Bearer sk_live_…. Antes, el administrador de la cuenta debe autorizar el acceso por asistente de IA en Configuración › API e integraciones: viene desactivado por defecto. También estamos en el registro oficial de MCP (ai.talpy/aya), en Smithery y en Glama.

Dos permisos, separados a propósito: mcp:read conecta y consulta; mcp:write, sumado a este, libera las herramientas que actúan. Una clave de solo lectura que llame a una herramienta de acción recibe un error JSON-RPC -32001 en HTTP 200, con el mismo id de la solicitud. Las respuestas salen en el idioma de la cuenta (el de quien creó la clave) o en el language que la llamada solicite.

Herramienta	Alcance	Qué hace
listar_vacantes	mcp:read	Vacantes de la empresa, con estado y número de candidatos.
detallar_vacante	mcp:read	Una vacante con las competencias que Aya evalúa y el peso de cada una.
listar_candidatos	mcp:read	Candidatos de una vacante con nota, adherencia y etapa, de mayor a menor.
detallar_candidato	mcp:read	La evaluación completa: nota por competencia, evidencia, puntos de atención y decisión humana.
resumen_del_reclutamiento	mcp:read	Números generales: vacantes, candidatos, entrevistas, nota media y uso del plan.
planes_y_suscripcion	mcp:read	Plan actual, consumo del ciclo, planes disponibles con precio y el enlace para contratar en el panel. No cobra.
crear_vacante	mcp:write	Crea la vacante con el perfil de evaluación de Aya. Nace en borrador, salvo que se pida publish=true. Cuenta en la cuota de vacantes del plan.
entrevistar_candidato	mcp:write	Registra al candidato y Aya lo invita: WhatsApp real con teléfono; sin teléfono, correo con el enlace de la entrevista en la web. Respeta el saldo de entrevistas.

Lo que el MCP no hace: aprobar o reprobar candidatos (decisión humana, en la ficha), cobrar o cambiar la suscripción (planos_e_assinatura solo devuelve el enlace de la página de planes) y devolver teléfono, correo o currículum. Cada llamada entra en la pista de auditoría de la empresa.

Workable en 3 pasos

Si tu empresa usa Workable, no necesitas programar nada: un administrador genera un token, lo pegas en Talpy y eliges la etapa del embudo. Desde entonces, todo candidato movido a esa etapa es entrevistado por Aya en WhatsApp y la nota vuelve a su ficha en Workable.

Los 3 pasos

1. Genera el token en Workable Con un usuario administrador, abre Settings → Integrations → Access Tokens y crea un token con los permisos r_jobs, r_candidates, w_candidates y w_comments. Elige la validez (30 días a 2 años) y copia el token: solo aparece una vez.
2. Pégalo en Talpy En API e integraciones → Workable, indica el subdominio (lo que viene antes de .workable.com), pega el token y haz clic en Probar conexión. Talpy lee tus vacantes y etapas para confirmar que el token funciona. El token queda cifrado y no vuelve a aparecer.
3. Elige la etapa y activa Selecciona la etapa que dispara la entrevista (ej.: "Entrevista con Aya" o "Triaje"), decide si la nota vuelve a Workable y si el aprobado cambia de etapa solo, y haz clic en Activar. Talpy registra el webhook en tu Workable automáticamente.

Qué pasa después

1. Alguien de tu equipo mueve al candidato a la etapa elegida en Workable.
2. Talpy importa nombre, correo, teléfono y currículum, hace el triaje y Aya invita al candidato por WhatsApp. Si la vacante aún no existe en Talpy, se crea a partir de la vacante de Workable.
3. Terminada la entrevista, la nota vuelve a la ficha en Workable: un comentario con nota general, adherencia, competencias con evidencia, puntos fuertes y de atención, más una evaluación positiva o negativa (nota mínima configurable).
4. Si activaste "mover al aprobar", el candidato con nota igual o superior a la mínima pasa a la etapa de destino. La decisión final sigue siendo de una persona.

Requisitos y límites

• El teléfono es obligatorio. La entrevista ocurre en WhatsApp; el candidato sin teléfono en Workable se importa, pero no se invita: Talpy deja un comentario en la ficha avisando.
• Workable limita la API a 10 solicitudes cada 10 segundos. Talpy respeta ese ritmo solo; en volumen alto, el retorno de la nota puede tardar unos segundos más.
• Workable no firma los webhooks. Por eso la dirección de recepción lleva un secreto exclusivo de tu cuenta: no lo compartas. Los eventos repetidos se ignoran (un candidato, una entrevista).

Preguntas frecuentes

El token expiró. ¿Y ahora?

Workable devuelve 401 y la pantalla de la integración muestra el error en "Último error". Genera un token nuevo en Workable, pégalo en el paso 1 y haz clic en Probar conexión: la etapa y las preferencias quedan como estaban.

El candidato no recibió la invitación.

Comprueba si tiene teléfono en Workable, con código de área (Talpy normaliza números brasileños y acepta internacionales con +). Añade el teléfono y mueve al candidato de nuevo a la etapa.

¿Cómo desactivo?

En API e integraciones → Workable, haz clic en Desactivar: Talpy elimina el webhook de tu Workable y deja de procesar eventos. Eliminar borra también el token; los candidatos y vacantes ya importados siguen en Talpy.

La activación automática falló.

Algunos tokens no tienen permiso para registrar webhooks. Copia la dirección de recepción mostrada en la pantalla y pégala en Settings → Integrations → Webhooks en Workable, evento candidate_moved (o candidate_created si elegiste "toda candidatura"), y luego haz clic en "Activar con la dirección registrada a mano".

Teamtailor en 3 pasos

Si tu empresa usa Teamtailor, no necesitas programar: un administrador crea una clave de API y un webhook, pegas ambos en Talpy y eliges la etapa del embudo. Desde entonces, toda candidatura que entra en esa etapa es entrevistada por Aya en WhatsApp y la nota vuelve a la ficha en Teamtailor.

Los 3 pasos

1. Crea la clave de API Con un usuario administrador, abre Settings → Integrations → API keys y crea una clave con alcance Admin y permiso de lectura y escritura (las claves Public e Internal no leen candidatos ni escriben notas). En API e integraciones → Teamtailor, pega la clave y haz clic en Probar conexión: Talpy descubre sola si tu cuenta está en la pila europea o norteamericana.
2. Elige la etapa y el retorno Selecciona la etapa que dispara la entrevista por nombre: en Teamtailor cada vacante tiene sus propias etapas, y Talpy reconoce la etapa con ese nombre en cualquier vacante. Decide si la nota vuelve a Teamtailor y si el aprobado cambia de etapa solo.
3. Registra el webhook y activa En Settings → Integrations → Webhooks (el add-on Webhooks debe estar activado), crea un webhook con la dirección de recepción mostrada en Talpy y el evento job_application.update (o job_application.create, si elegiste "toda candidatura"). Copia la signature key que Teamtailor genere, pégala en Talpy y haz clic en Activar.

Qué pasa después

1. Alguien de tu equipo mueve la candidatura a la etapa elegida en Teamtailor.
2. Talpy verifica la firma del evento, importa nombre, correo, teléfono y currículum, hace el triaje y Aya invita al candidato por WhatsApp: sin teléfono, invita por correo con el enlace de la entrevista en la web. Si la vacante aún no existe en Talpy, se crea a partir de la vacante de Teamtailor.
3. Terminada la entrevista, una nota vuelve a la ficha: nota general, adherencia y, por competencia, la nota con la declaración del candidato que la sustenta, entre comillas, más una evaluación de 4 estrellas (por encima de la mínima) o 2 (por debajo) vinculada a la candidatura.
4. Si activaste "mover al aprobar", la candidatura con nota igual o superior a la mínima pasa a la etapa de destino. Cuando alguien aprueba o rechaza en Talpy, eso también se convierte en una nota en Teamtailor. La decisión final sigue siendo de una persona.

Requisitos y límites

• Firma obligatoria. Cada evento se verifica con la signature key (HMAC-SHA256, versiones v2 y v1 de Teamtailor). Un evento sin firma válida se rechaza con 401 y aparece en "Último error".
• La dirección de recepción también lleva un secreto exclusivo de tu cuenta: no lo compartas. Los eventos repetidos se ignoran (una candidatura, una entrevista).
• Teamtailor limita la API a 50 solicitudes cada 10 segundos; Talpy respeta ese ritmo sola. Teamtailor no reenvía webhooks que fallaron: si Talpy está fuera en el instante del movimiento, mueve la candidatura de nuevo.

Preguntas frecuentes

Los eventos llegan con "firma inválida".

La signature key pegada en Talpy no es la del webhook actual (cambia si el webhook se recrea). Cópiala de nuevo en Settings → Integrations → Webhooks, desactiva la integración en Talpy, pega la clave y activa.

El candidato no recibió la invitación.

Revisa el teléfono en la ficha de Teamtailor, con código de área (Talpy normaliza números brasileños y acepta internacionales con +). Sin teléfono, la invitación va por correo. Corrige y mueve la candidatura de nuevo a la etapa.

¿Cómo desactivo?

En API e integraciones → Teamtailor, haz clic en Desactivar y borra el webhook en Teamtailor. Eliminar borra también la clave; los candidatos y vacantes ya importados siguen en Talpy.

Lever en 3 pasos

Si tu empresa usa Lever, no necesitas programar: un Super Admin genera una clave de API, la pegas en Talpy, eliges la etapa del embudo y Talpy crea el webhook. Desde entonces, toda opportunity que cambia a esa etapa es entrevistada por Aya en WhatsApp y la nota vuelve a Lever.

Los 3 pasos

1. Genera la clave de API Con un Super Admin, abre Settings → Integrations and API → API Credentials y crea una clave con lectura de opportunities, postings, stages, users y resumes, escritura de notes y stage, y webhooks:write:admin. En API e integraciones → Lever, pega la clave y haz clic en Probar conexión.
2. Elige la etapa y el retorno Selecciona la etapa que dispara la entrevista, decide si la nota vuelve a Lever y si el aprobado cambia de etapa solo.
3. Activa y conecta el evento Haz clic en Activar: Talpy crea el webhook candidateStageChange (o applicationCreated, si elegiste "toda candidatura") y guarda la clave de firma. Por regla de Lever, un Super Admin aún debe conectar el evento en Settings → Integrations and API → Webhooks.

Qué pasa después

1. Alguien de tu equipo cambia la opportunity a la etapa elegida en Lever.
2. Talpy verifica la firma, lee la opportunity (nombre, correo, phones, currículum y vacante), hace el triaje y Aya invita por WhatsApp: sin teléfono, por correo con el enlace de la entrevista en la web. Si la vacante aún no existe en Talpy, se crea a partir de la posting.
3. Terminada la entrevista, una nota vuelve a la opportunity: nota general, adherencia y, por competencia, la nota con la declaración del candidato que la sustenta, entre comillas, con score Yes (por encima de la mínima) o No (por debajo).
4. Si activaste "mover al aprobar", la opportunity con nota igual o superior a la mínima pasa a la etapa de destino. La aprobación o rechazo hecho en Talpy también se convierte en nota en Lever. La decisión final sigue siendo de una persona.

Requisitos y límites

• Firma obligatoria. Cada evento se verifica con el signature token del webhook (HMAC-SHA256 de token + triggeredAt). Un evento sin firma válida se rechaza con 401.
• La firma de Lever no cubre el contenido del evento; por eso la dirección lleva también un secreto exclusivo de tu cuenta y Talpy siempre relee la opportunity en la API de Lever antes de actuar.
• Lever limita la API a unas 10 solicitudes por segundo; Talpy respeta ese ritmo. Los eventos repetidos (Lever reenvía hasta cinco veces) se ignoran.

Preguntas frecuentes

La activación automática falló.

La clave no tiene webhooks:write:admin. Registra la dirección de recepción a mano en Settings → Integrations and API → Webhooks, genera el signature token, pégalo en Talpy y haz clic en "Activar con el webhook registrado a mano".

Activé, pero no llega ningún evento. Falta conectar el grupo del evento (Candidate Stage Change o Application Created) en la pantalla de webhooks de Lever — solo un Super Admin ve ese botón. En la misma pantalla, el historial de entregas muestra la respuesta de Talpy.

¿Cómo lo desactivo?

En API e integraciones → Lever, haz clic en Desactivar: Talpy elimina el webhook que creó. Eliminar borra también la clave; los candidatos y las vacantes ya importados permanecen en Talpy.

Greenhouse (Assessment API)

Aquí la dirección se invierte: Greenhouse es la cliente y Talpy es la proveedora de pruebas. Ella llama a estas cuatro direcciones cuando el reclutador envía al candidato a la etapa de evaluación. Cada vacante activa aparece en Greenhouse como una prueba — así es como el reclutador elige qué entrevista conducirá Aya, porque la rúbrica es por vacante.

Las cuatro direcciones

GET   /api/i​ntegra​coes/g​reenho​use/li​st_tes​ts
POST  /api/i​ntegra​coes/g​reenho​use/se​nd_tes​t
GET   /api/i​ntegra​coes/g​reenho​use/te​st_sta​tus?pa​rtner_​interv​iew_id​=<id>
POST  /api/i​ntegra​coes/g​reenho​use/re​quest_​errors​

Autenticación

HTTP Basic, con la clave en lugar del usuario y contraseña vacía. Es la misma API key que generas en API y webhooks en el panel — no existe una credencial separada para Greenhouse. La clave necesita los alcances jobs:read, candidates:write y interviews:read. Revocar la clave desactiva la integración al instante.

curl -u "sk_li​ve_xxx​xx:" \
  https:​//talp​y.ai/a​pi/int​egraco​es/gre​enhous​e/list​_tests​

Qué sucede, en orden

1. El reclutador elige la vacante como prueba en la etapa de evaluación de Greenhouse (list_tests).
2. Al mover al candidato, Greenhouse llama a send_test. Creamos al candidato, descargamos el currículum y Aya invita por WhatsApp.
3. Greenhouse pregunta el estado en intervalos (test_status). Mientras la entrevista no haya terminado, la respuesta es pending.
4. Terminada la evaluación, devolvemos complete con la nota, el enlace del perfil y la nota por competencia — que aparece en la ficha del candidato dentro de Greenhouse.

Preguntas frecuentes

¿El candidato necesita tener teléfono?

Sí. Aya entrevista por WhatsApp. Sin teléfono en la ficha, el candidato se importa pero no se le invita, y el aviso aparece en el panel de Talpy.

Greenhouse reenvía la misma llamada. ¿Se convierte en candidato duplicado?

No. El par (candidatura, prueba) es único: un reenvío devuelve el mismo partner_interview_id, sin candidato nuevo y sin invitación cobrada de más.

¿Por qué <code>test_status</code> permanece en <code>pending</code> durante horas?

Porque el candidato aún no ha respondido. Solo devolvemos complete cuando existe evaluación — Greenhouse deja de preguntar al escuchar complete, y responder antes dejaría la ficha vacía allí dentro.

Ashby (Assessments Framework)

Como en Greenhouse, Ashby es la cliente y Talpy es la socia de assessment. La diferencia está en el camino de regreso: Ashby no pregunta el estado — nosotros avisamos, llamando al assessment.update de ella en cada paso de la entrevista. Cada vacante activa aparece en Ashby como un assessment, porque la rúbrica de Aya es por vacante.

URL base y direcciones

URL base: https:​//talp​y.ai/a​pi/int​egraco​es/ash​by

POST  /asses​sment.​list     (jobs:​read)
POST  /asses​sment.​start    (candi​dates:​write)​
POST  /asses​sment.​cancel​   (candi​dates:​write)​

Caminh​o de volta (nós chamam​os a Ashby)​:
POST  https:​//api.​ashbyh​q.com/​assess​ment.u​pdate

Autenticación

En la ida, HTTP Basic con la clave de Talpy en lugar del usuario y contraseña vacía — la misma API key de API e integraciones, con los alcances jobs:read y candidates:write, pegada por el admin en el panel de Ashby. En la vuelta, usamos una clave de Ashby del cliente (permiso candidatesWrite; con candidatesRead, buscamos el teléfono para invitar por WhatsApp), guardada cifrada en Talpy.

curl -u "sk_li​ve_xxx​xx:" -X POST \
  -H "Conte​nt-Typ​e: applic​ation/​json" -d '{}' \
  https:​//talp​y.ai/a​pi/int​egraco​es/ash​by/ass​essmen​t.list​

Qué sucede, en orden

1. El reclutador elige la vacante como assessment en el plan de entrevistas de Ashby (assessment.list).
2. Al iniciar el assessment, Ashby llama a assessment.start. Respondemos de inmediato con el assessment_id; Aya invita al candidato por WhatsApp (o por correo electrónico, sin teléfono) y avisamos "invitado".
3. En cada paso enviamos assessment.update: Started en la primera respuesta, "en curso" durante la conversación, "expirado" si el candidato deja de responder.
4. Evaluada la entrevista, la actualización trae assessment_result (nota general), el enlace del informe y, en metadata, la nota de cada competencia con la cita literal de la intervención que la respalda.

Preguntas frecuentes

El payload de Ashby no trae teléfono. ¿Cómo invita Aya?

Si la clave de Ashby tiene candidatesRead, buscamos el teléfono en candidate.info y Aya invita por WhatsApp. Sin teléfono, la invitación va por correo electrónico con el enlace de la misma entrevista en la web — y el canal utilizado aparece en el estado dentro de Ashby.

Ashby reenvía el mismo inicio. ¿Se convierte en candidato duplicado?

No. El par (candidatura, assessment) es único mientras el assessment sea válido: un reenvío devuelve el mismo assessment_id. Después de un assessment.cancel, un nuevo inicio para la misma candidatura funciona normalmente.

¿Qué error aparece para el reclutador?

Vacante cerrada en Talpy o cuenta sin saldo vuelven como 422 con message legible, que Ashby muestra en la pantalla. Clave inválida vuelve 401 en el formato de error de Ashby (success:false, errorInfo).

Conectores y ATS

¿No quieres programar? Se puede conectar Talpy a otras herramientas mediante automatización, usando los webhooks para salir y la API para entrar.

Sirve para enviar al candidato evaluado a una hoja de cálculo, abrir una tarjeta en tu tablero, avisar al equipo en el chat o empujar al aprobado hacia tu ATS.

Receta lista (Zapier, Make o n8n)

1. Gatilh​o: Webhoo​k -> Catch Hook. Cole a URL gerada no painel da Talpy, em API e integr​ações.​
2. Na Talpy, escolh​a o evento candid​ato.av​aliado​.
3. Filtro (opcio​nal): siga só quando a nota for maior ou igual a 8.
4. Ação: crie a linha na planil​ha, o card no quadro ou o regist​ro no seu ATS.
5. Para o caminh​o de volta, chame POST /api/v​1/cand​idates​ com a sua chave.