Talpy Aya – AI recruiter on WhatsApp

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

API da Talpy

Leia vagas e candidatos, cadastre candidaturas e envie mensagens no WhatsApp a partir do seu sistema. REST, autenticação por chave e resposta em JSON.

Cobre vagas, candidatos, entrevistas avaliadas, envio no WhatsApp, webhooks de eventos e o conector MCP.

Autenticação

Toda chamada leva a sua chave no cabeçalho Authorization, no formato Bearer. A chave já identifica a sua empresa — você não envia o id da organização.

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

Gere e revogue chaves no painel, em API e integrações. A chave aparece uma única vez: guarde num cofre de segredos, nunca no código do cliente nem no navegador.

Chave vazada é chave revogada. Se desconfiar, revogue e gere outra — a antiga para de funcionar na hora.

Ambientes

Existem dois ambientes com dados separados. O prefixo da chave diz em qual você está: sk_live_ é produção e sk_test_ é teste.

A chave de teste trabalha numa organização-espelho: mesmas rotas, mesmos formatos, dados de brinquedo. Integre à vontade e, quando estiver pronto, troque só a chave — o código continua igual.

	Produção	Teste (sandbox)
Prefixo da chave	sk_live_	sk_test_
Dados	Suas vagas e candidatos reais	Organização-espelho, isolada da sua
Cabeçalho X-Ambiente	live	sandbox
Envio no WhatsApp	Usa o número e a configuração da sua empresa	Usa a configuração da organização-espelho
Consumo do plano	Desconta das entrevistas do seu plano	Não toca na cota da sua empresa
Links públicos	Link de candidatura real da vaga	Link da vaga espelho, só para teste
Webhooks	Disparam com os seus dados reais	Disparam com os dados da organização-espelho

Nada criado em teste aparece em produção, e o contrário também não. Toda resposta traz o cabeçalho X-Ambiente dizendo onde ela foi produzida.

# 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​"

Permissões

Cada chave carrega só os escopos que você marcar. Peça o mínimo que a integração precisa: se um escopo não estiver na chave, a chamada volta 403.

Escopo	Permite	Endpoints
jobs:read	Ler as vagas da empresa e os detalhes de cada uma.	GET /api/v1/jobs
candidates:read	Ler os candidatos de uma vaga e a ficha de um candidato — e assinar webhooks pela API (quem pode ler o dado pode recebê-lo).	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	Cadastrar candidatos (inclusive com currículo em base64).	POST /api/v1/candidates
jobs:write	Criar vagas e alterar vagas existentes.	POST /api/v1/jobs PATCH /api/v1/jobs/{id}
whatsapp:send	Enviar mensagem para um candidato pelo WhatsApp.	POST /api/v1/candidates/{id}/whatsapp
mcp:read	Consultar a Talpy por um assistente de IA (MCP): vagas, candidatos, avaliações e plano. Sem dado de contato.	POST /api/mcp
mcp:write	Agir pelo assistente de IA (MCP): criar vaga e mandar candidato para a Aya entrevistar — envia WhatsApp/e-mail de verdade. Usado junto com mcp:read.	POST /api/mcp — criar_vaga, entrevistar_candidato
interviews:read	Ler a entrevista e a avaliação do candidato junto da ficha.	GET /api/v1/candidates/{id}

Limites de uso

Cada chave pode fazer até 120 chamadas por minuto. Passou disso, a resposta vira 429 e volta ao normal na janela seguinte.

Cabeçalho	O que traz
X-RateLimit-Limit	Teto de chamadas da janela (120).
X-RateLimit-Remaining	Quantas chamadas ainda restam nesta janela.
X-RateLimit-Reset	Quando a janela reinicia (timestamp em segundos).
X-Ambiente	Em qual ambiente a resposta foi produzida: live ou sandbox.
Retry-After	Só no 429: quantos segundos esperar antes de tentar de novo.

Respeite o Retry-After em vez de insistir: repetir na hora só consome a próxima janela.

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: *

A API é feita para chamada de servidor. Não exponha a chave no navegador — não há CORS liberado para uso direto no front.

Erros

Erro sempre volta em JSON, com o campo error em texto estável (pode comparar no código) e o HTTP correspondente.

error	HTTP	Quando acontece	O que fazer
chave_ausente	401	Não veio o cabeçalho Authorization, ou veio fora do formato Bearer.	Mande Authorization: Bearer sk_… em toda chamada.
chave_invalida	401	A chave não existe, ou o sandbox dela ainda não foi provisionado.	Confira se copiou a chave inteira e se está usando a do ambiente certo.
chave_revogada	401	A chave foi revogada no painel.	Gere uma chave nova em API e integrações e troque no seu sistema.
chave_expirada	401	A chave passou da data de validade.	Gere uma chave nova, com validade maior se fizer sentido.
escopo_insuficiente	403	A chave é válida, mas não tem o escopo que o endpoint exige.	Gere uma chave com o escopo necessário — a tabela de permissões diz qual é.
limite_excedido	429	Passou de 120 chamadas por minuto nesta chave.	Espere o tempo do Retry-After e volte. Se for rotina, distribua as chamadas.
json_invalido	400	O corpo não era um JSON válido.	Mande Content-Type: application/json e um corpo bem formado.
jobId_ausente	400	Faltou o jobId no corpo ao cadastrar o candidato.	Inclua o jobId da vaga em que o candidato entra.
name_ausente	400	Faltou o nome do candidato.	Inclua o campo name — é o único obrigatório além do jobId.
cvBase64_invalido	400	O currículo veio em base64 quebrado, vazio ou num tipo que não aceitamos.	Mande PDF ou imagem em base64 válido. O conteúdo é validado de verdade, não pela extensão.
vaga_nao_encontrada	404	A vaga não existe ou é de outra empresa.	Confira o id. A chave só enxerga as vagas da própria organização.
candidato_nao_encontrado	404	O candidato não existe ou é de outra empresa.	Confira o id do candidato.
url_invalida	400	A url do webhook não veio ou não é https://.	Mande uma URL https:// válida — o corpo das entregas leva dado pessoal e não sai em texto claro.
eventos_invalidos	400	Nenhum evento válido em events.	Mande ao menos um evento da tabela de webhooks (o GET /api/v1/webhooks também lista os disponíveis).
nao_encontrado	404	O webhook não existe ou é de outra organização (DELETE /api/v1/webhooks/{id}).	Confira o id com GET /api/v1/webhooks. Se já foi cancelado, não há nada a fazer.

Exemplo de resposta quando falta escopo na chave:

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"]​
}

Exemplo de resposta quando estourou o limite 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 os exemplos abaixo usam uma chave de produção.

GET/api/v1/jobs jobs:read

Listar vagas

Devolve as vagas da sua empresa, da mais recente para a mais antiga.

Parâmetros: Nenhum parâmetro obrigatório.

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​"

Resposta:

{
  "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

Expõe a Talpy como ferramentas para um assistente de IA (JSON-RPC 2.0, Streamable HTTP). Consulta com mcp:read; age (criar vaga, convidar candidato) com mcp:write. Detalhes na seção Assistente de IA (MCP).

Parâmetros: No corpo: method e params, no padrão JSON-RPC. Ex.: tools/call com o nome da ferramenta.

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}}}​'

Resposta:

{
  "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

Detalhe da vaga

Traz uma vaga com o perfil, a rubrica de avaliação e o link público de candidatura.

Parâmetros: {id} — id da vaga, no caminho.

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​"

Resposta:

{
  "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

Criar vaga

Abre uma vaga nova já pronta para receber candidatura.

Parâmetros: Corpo JSON com os dados da vaga: título, senioridade e descrição.

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​"
  }'

Resposta:

{
  "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

Alterar vaga

Muda campos de uma vaga existente — inclusive pausar ou reativar.

Parâmetros: {id} no caminho e, no corpo, só os campos que mudam.

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"}'​

Resposta:

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

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

Enviar WhatsApp ao candidato

Dispara uma mensagem para o candidato pelo número da sua empresa.

Parâmetros: {id} — id do candidato — e, no corpo, o texto da mensagem.

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"}'

Resposta:

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

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

Candidatos da vaga

Lista quem se candidatou, com a nota da triagem e o estágio de cada um.

Parâmetros: {id} — id da vaga.

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​"

Resposta:

{
  "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 do candidato

Traz o candidato com os dados de contato e, se houver, a entrevista avaliada pela Aya.

Parâmetros: {id} — id do candidato. A avaliação só vem se a chave tiver 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​"

Resposta:

{
  "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

Cadastrar candidato

Coloca alguém numa vaga. Se mandar o currículo, a Talpy lê e preenche os dados sozinha.

A entrevista não é criada na hora: o candidato segue a regra de avanço automático da vaga (modo e nota mínima configurados no painel). Com o avanço desligado, convide por POST /api/v1/candidates/{id}/whatsapp.

Parâmetros: No corpo: jobId e name obrigatórios; cvBase64, email e phone opcionais.

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..."
  }'

Resposta:

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

GET/api/v1/webhooks candidates:read

Listar webhooks

Os webhooks assinados nesta organização, pela tela ou pela API, e a lista de eventos disponíveis. O secret nunca volta aqui.

Parâmetros: nenhum.

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​"

Resposta:

{
  "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

Assinar um webhook

Assina uma URL para receber eventos — é o REST Hooks que Zapier, Make e n8n usam quando o usuário liga o fluxo. Assinar a mesma URL de novo atualiza a assinatura em vez de duplicar. O secret (para conferir o HMAC de cada entrega) é devolvido UMA vez, nesta resposta.

Parâmetros: url (obrigatório, https://) e events (array com ao menos um evento válido — veja a tabela 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"]}​'

Resposta:

{
  "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 um webhook

Cancela a assinatura e a entrega para na hora — é o que a plataforma de automação chama quando o usuário desliga o fluxo. Apaga de verdade, não só desativa.

Parâmetros: {id} — id devolvido na assinatura.

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​"

Resposta:

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

Webhooks

Em vez de ficar perguntando, deixe a Talpy avisar. Cadastre a URL no painel e a gente manda um POST a cada evento.

Responda 2xx rápido e processe depois. Se a sua URL falhar, tentamos de novo — então trate o mesmo evento chegando duas vezes sem duplicar nada.

Assinar por API (REST Hooks — usado pelo Zapier): além da tela do painel, dá para assinar e cancelar webhooks com POST /api/v1/webhooks, GET /api/v1/webhooks e DELETE /api/v1/webhooks/{id}, com uma chave de escopo candidates:read. Veja os detalhes em Endpoints.

Eventos disponíveis

Evento	Quando dispara
candidato.criado	Alguém se candidatou ou foi cadastrado pela API.
candidato.triado	A Talpy leu o currículo e calculou a aderência à vaga.
entrevista.iniciada	O candidato começou a entrevista com a Aya.
candidato.avaliado	A Aya terminou a entrevista e a nota por competência saiu.
candidato.decidido	Alguém da sua equipe aprovou ou reprovou o candidato.

Formato do envio

O corpo traz o tipo do evento, o momento e o objeto que mudou.

{
  "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":​ "..." }
    ]
  }
}

Como conferir que veio da Talpy

Cada envio vai assinado com o segredo do seu webhook. Confira a assinatura antes de confiar no conteúdo e descarte o que não bater.

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​);
});

Webhook de sandbox só dispara com dados da organização-espelho — dá para testar sem sujar produção.

Assistente de IA (MCP)

Conecte o Claude, o ChatGPT, o Cursor ou qualquer cliente MCP em https://talpy.ai/api/mcp com a chave no cabeçalho Authorization: Bearer sk_live_…. Antes, o admin da conta precisa autorizar o acesso por assistente de IA em Configurações › API e integrações — nasce desligado. Também estamos no registro oficial do MCP (ai.talpy/aya), na Smithery e no Glama.

Duas permissões, de propósito separadas: mcp:read conecta e consulta; mcp:write, somada a ela, libera as ferramentas que agem. Uma chave só de leitura que chama uma ferramenta de ação recebe erro JSON-RPC -32001 em HTTP 200, com o mesmo id do pedido. As respostas saem no idioma da conta (o de quem criou a chave) ou no language que a chamada pedir.

Ferramenta	Escopo	O que faz
listar_vagas	mcp:read	Vagas da empresa, com situação e número de candidatos.
detalhar_vaga	mcp:read	Uma vaga com as competências que a Aya avalia e o peso de cada uma.
listar_candidatos	mcp:read	Candidatos de uma vaga com nota, aderência e etapa, do maior para o menor.
detalhar_candidato	mcp:read	A avaliação completa: nota por competência, evidência, pontos de atenção e decisão humana.
resumo_do_recrutamento	mcp:read	Números gerais: vagas, candidatos, entrevistas, nota média e uso do plano.
planos_e_assinatura	mcp:read	Plano atual, consumo do ciclo, planos disponíveis com preço e o link para contratar no painel. Não cobra.
criar_vaga	mcp:write	Cria a vaga com o perfil de avaliação da Aya. Nasce em rascunho, a não ser que peça publish=true. Conta na cota de vagas do plano.
entrevistar_candidato	mcp:write	Cadastra o candidato e a Aya o convida: WhatsApp de verdade com telefone; sem telefone, e-mail com o link da entrevista na web. Respeita o saldo de entrevistas.

O que o MCP não faz: aprovar ou reprovar candidato (decisão humana, na ficha), cobrar ou mudar a assinatura (planos_e_assinatura só devolve o link da página de planos) e devolver telefone, e-mail ou currículo. Toda chamada entra na trilha de auditoria da empresa.

Workable em 3 passos

Se a sua empresa usa o Workable, não precisa programar nada: um administrador gera um token, você cola no Talpy e escolhe a etapa do funil. Daí em diante, todo candidato movido para essa etapa é entrevistado pela Aya no WhatsApp e a nota volta para a ficha dele no Workable.

Os 3 passos

1. Gere o token no Workable Com um usuário administrador, abra Settings → Integrations → Access Tokens e crie um token com as permissões r_jobs, r_candidates, w_candidates e w_comments. Escolha a validade (30 dias a 2 anos) e copie o token — ele só aparece uma vez.
2. Cole no Talpy Em API e integrações → Workable, informe o subdomínio (o que vem antes de.workable.com), cole o token e clique em Testar conexão. O Talpy lê suas vagas e etapas para confirmar que o token funciona. O token fica cifrado e não aparece de novo.
3. Escolha a etapa e ative Selecione a etapa que dispara a entrevista (ex.: "Entrevista com a Aya" ou "Triagem"), decida se a nota volta ao Workable e se o aprovado muda de etapa sozinho, e clique em Ativar. O Talpy cadastra o webhook no seu Workable automaticamente.

O que acontece depois

1. Alguém do seu time move o candidato para a etapa escolhida no Workable.
2. O Talpy importa nome, e-mail, telefone e currículo, faz a triagem e a Aya convida o candidato pelo WhatsApp. Se a vaga ainda não existe no Talpy, ela é criada a partir da vaga do Workable.
3. Terminada a entrevista, a nota volta para a ficha no Workable: um comentário com nota geral, aderência, competências com evidência, pontos fortes e de atenção, mais uma avaliação positiva ou negativa (nota mínima configurável).
4. Se você ligou "mover ao aprovar", o candidato com nota igual ou acima da mínima vai para a etapa de destino. A decisão final continua sendo de uma pessoa.

Requisitos e limites

• Telefone é obrigatório. A entrevista acontece no WhatsApp; candidato sem telefone no Workable é importado, mas não convidado — o Talpy deixa um comentário na ficha avisando.
• O Workable limita a API a 10 requisições a cada 10 segundos. O Talpy respeita esse ritmo sozinho; em volume alto, o retorno da nota pode levar alguns segundos a mais.
• O Workable não assina os webhooks. Por isso o endereço de recepção carrega um segredo exclusivo da sua conta — não o compartilhe. Eventos repetidos são ignorados (um candidato, uma entrevista).

Perguntas frequentes

O token expirou. E agora?

O Workable devolve 401 e a tela da integração mostra o erro em "Último erro". Gere um token novo no Workable, cole no passo 1 e clique em Testar conexão — a etapa e as preferências ficam como estavam.

O candidato não recebeu o convite.

Confira se ele tem telefone no Workable, com DDD (o Talpy normaliza números brasileiros e aceita internacionais com +). Adicione o telefone e mova o candidato de novo para a etapa.

Como desativo?

Em API e integrações → Workable, clique em Desativar: o Talpy remove o webhook do seu Workable e para de processar eventos. Remover apaga também o token; candidatos e vagas já importados continuam no Talpy.

A ativação automática falhou.

Alguns tokens não têm permissão para cadastrar webhooks. Copie o endereço de recepção mostrado na tela e cole em Settings → Integrations → Webhooks no Workable, evento candidate_moved (ou candidate_created se escolheu "toda candidatura"), e depois clique em "Ativar com o endereço cadastrado à mão".

Teamtailor em 3 passos

Se a sua empresa usa o Teamtailor, não precisa programar: um administrador cria uma chave de API e um webhook, você cola os dois na Talpy e escolhe a etapa do funil. Daí em diante, toda candidatura que entra nessa etapa é entrevistada pela Aya no WhatsApp e a nota volta para a ficha no Teamtailor.

Os 3 passos

1. Crie a chave de API Com um usuário administrador, abra Settings → Integrations → API keys e crie uma chave com escopo Admin e permissão de leitura e escrita (as chaves Public e Internal não leem candidatos nem escrevem notas). Em API e integrações → Teamtailor, cole a chave e clique em Testar conexão — a Talpy descobre sozinha se a sua conta está na pilha europeia ou norte-americana.
2. Escolha a etapa e o retorno Selecione a etapa que dispara a entrevista pelo nome — no Teamtailor cada vaga tem as suas etapas, e a Talpy reconhece a etapa com esse nome em qualquer vaga. Decida se a nota volta ao Teamtailor e se o aprovado muda de etapa sozinho.
3. Cadastre o webhook e ative Em Settings → Integrations → Webhooks (o add-on Webhooks precisa estar ligado), crie um webhook com o endereço de recepção mostrado na Talpy e o evento job_application.update (ou job_application.create, se escolheu "toda candidatura"). Copie a signature key que o Teamtailor gerar, cole na Talpy e clique em Ativar.

O que acontece depois

1. Alguém do seu time move a candidatura para a etapa escolhida no Teamtailor.
2. A Talpy confere a assinatura do evento, importa nome, e-mail, telefone e currículo, faz a triagem e a Aya convida o candidato pelo WhatsApp — sem telefone, ela convida por e-mail com o link da entrevista na web. Se a vaga ainda não existe na Talpy, ela é criada a partir da vaga do Teamtailor.
3. Terminada a entrevista, uma nota volta para a ficha: nota geral, aderência e, por competência, a nota com a fala do candidato que a sustenta, entre aspas — mais uma avaliação de 4 estrelas (acima da mínima) ou 2 (abaixo) ligada à candidatura.
4. Se você ligou "mover ao aprovar", a candidatura com nota igual ou acima da mínima vai para a etapa de destino. Quando alguém aprova ou reprova na Talpy, isso também vira uma nota no Teamtailor. A decisão final continua sendo de uma pessoa.

Requisitos e limites

• Assinatura obrigatória. Todo evento é conferido com a signature key (HMAC-SHA256, versões v2 e v1 do Teamtailor). Evento sem assinatura válida é recusado com 401 e aparece em "Último erro".
• O endereço de recepção também carrega um segredo exclusivo da sua conta — não o compartilhe. Eventos repetidos são ignorados (uma candidatura, uma entrevista).
• O Teamtailor limita a API a 50 requisições a cada 10 segundos; a Talpy respeita esse ritmo sozinha. O Teamtailor não reenvia webhook que falhou — se a Talpy estiver fora no instante do movimento, mova a candidatura de novo.

Perguntas frequentes

Os eventos chegam com "assinatura inválida".

A signature key colada na Talpy não é a do webhook atual (ela muda se o webhook for recriado). Copie de novo em Settings → Integrations → Webhooks, desative a integração na Talpy, cole a chave e ative.

O candidato não recebeu o convite.

Confira o telefone na ficha do Teamtailor, com DDD (a Talpy normaliza números brasileiros e aceita internacionais com +). Sem telefone, o convite vai por e-mail. Corrija e mova a candidatura de novo para a etapa.

Como desativo?

Em API e integrações → Teamtailor, clique em Desativar e apague o webhook no Teamtailor. Remover apaga também a chave; candidatos e vagas já importados continuam na Talpy.

Lever em 3 passos

Se a sua empresa usa o Lever, não precisa programar: um Super Admin gera uma chave de API, você cola na Talpy, escolhe a etapa do funil e a Talpy cria o webhook. Daí em diante, toda opportunity que muda para essa etapa é entrevistada pela Aya no WhatsApp e a nota volta para o Lever.

Os 3 passos

1. Gere a chave de API Com um Super Admin, abra Settings → Integrations and API → API Credentials e crie uma chave com leitura de opportunities, postings, stages, users e resumes, escrita de notes e stage, e webhooks:write:admin. Em API e integrações → Lever, cole a chave e clique em Testar conexão.
2. Escolha a etapa e o retorno Selecione a etapa que dispara a entrevista, decida se a nota volta ao Lever e se o aprovado muda de etapa sozinho.
3. Ative e ligue o evento Clique em Ativar: a Talpy cria o webhook candidateStageChange (ou applicationCreated, se escolheu "toda candidatura") e guarda a chave de assinatura. Por regra do Lever, um Super Admin ainda precisa ligar o evento em Settings → Integrations and API → Webhooks.

O que acontece depois

1. Alguém do seu time muda a opportunity para a etapa escolhida no Lever.
2. A Talpy confere a assinatura, lê a opportunity (nome, e-mail, phones, currículo e vaga), faz a triagem e a Aya convida pelo WhatsApp — sem telefone, por e-mail com o link da entrevista na web. Se a vaga ainda não existe na Talpy, ela é criada a partir da posting.
3. Terminada a entrevista, uma nota volta para a opportunity: nota geral, aderência e, por competência, a nota com a fala do candidato que a sustenta, entre aspas — com score Yes (acima da mínima) ou No (abaixo).
4. Se você ligou "mover ao aprovar", a opportunity com nota igual ou acima da mínima vai para a etapa de destino. A aprovação ou reprovação feita na Talpy também vira nota no Lever. A decisão final continua sendo de uma pessoa.

Requisitos e limites

• Assinatura obrigatória. Todo evento é conferido com o signature token do webhook (HMAC-SHA256 de token + triggeredAt). Evento sem assinatura válida é recusado com 401.
• A assinatura do Lever não cobre o conteúdo do evento; por isso o endereço carrega também um segredo exclusivo da sua conta e a Talpy sempre relê a opportunity na API do Lever antes de agir.
• O Lever limita a API a cerca de 10 requisições por segundo; a Talpy respeita esse ritmo. Eventos repetidos (o Lever reenvia até cinco vezes) são ignorados.

Perguntas frequentes

A ativação automática falhou.

A chave não tem webhooks:write:admin. Cadastre o endereço de recepção à mão em Settings → Integrations and API → Webhooks, gere o signature token, cole na Talpy e clique em "Ativar com o webhook cadastrado à mão".

Ativei, mas nenhum evento chega.

Falta ligar o grupo do evento (Candidate Stage Change ou Application Created) na tela de webhooks do Lever — só um Super Admin vê esse botão. Na mesma tela, o histórico de entregas mostra a resposta da Talpy.

Como desativo?

Em API e integrações → Lever, clique em Desativar: a Talpy apaga o webhook que criou. Remover apaga também a chave; candidatos e vagas já importados continuam na Talpy.

Greenhouse (Assessment API)

Aqui a direção se inverte: a Greenhouse é a cliente e a Talpy é a fornecedora de teste. Ela chama estes quatro endereços quando o recrutador manda o candidato para a etapa de avaliação. Cada vaga ativa aparece na Greenhouse como um teste — é assim que o recrutador escolhe qual entrevista a Aya vai conduzir, porque a rubrica é por vaga.

Os quatro endereços

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​

Autenticação

HTTP Basic, com a chave no lugar do usuário e senha vazia. É a mesma API key que você gera em API e webhooks no painel — não existe credencial separada para a Greenhouse. A chave precisa dos escopos jobs:read, candidates:write e interviews:read. Revogar a chave desliga a integração na hora.

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

O que acontece, na ordem

1. O recrutador escolhe a vaga como teste na etapa de avaliação da Greenhouse (list_tests).
2. Ao mover o candidato, a Greenhouse chama send_test. Criamos o candidato, baixamos o currículo e a Aya convida pelo WhatsApp.
3. A Greenhouse pergunta o status em intervalos (test_status). Enquanto a entrevista não terminou, a resposta é pending.
4. Terminada a avaliação, devolvemos complete com a nota, o link do perfil e a nota por competência — que aparece na ficha do candidato dentro da Greenhouse.

Perguntas frequentes

O candidato precisa ter telefone?

Sim. A Aya entrevista pelo WhatsApp. Sem telefone na ficha, o candidato é importado mas não convidado, e o aviso aparece no painel da Talpy.

A Greenhouse reenvia a mesma chamada. Vira candidato duplicado?

Não. O par (candidatura, teste) é único: um reenvio devolve o mesmo partner_interview_id, sem candidato novo e sem convite cobrado a mais.

Por que <code>test_status</code> fica em <code>pending</code> por horas?

Porque o candidato ainda não respondeu. Só devolvemos complete quando existe avaliação — a Greenhouse para de perguntar ao ouvir complete, e responder antes deixaria a ficha vazia lá dentro.

Ashby (Assessments Framework)

Como na Greenhouse, a Ashby é a cliente e a Talpy é a parceira de assessment. A diferença está no caminho de volta: a Ashby não pergunta o status — nós avisamos, chamando o assessment.update dela a cada passo da entrevista. Cada vaga ativa aparece na Ashby como um assessment, porque a rubrica da Aya é por vaga.

URL base e endereços

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

Autenticação

Na ida, HTTP Basic com a chave da Talpy no lugar do usuário e senha vazia — a mesma API key de API e integrações, com os escopos jobs:read e candidates:write, colada pelo admin no painel da Ashby. Na volta, usamos uma chave da Ashby do cliente (permissão candidatesWrite; com candidatesRead, buscamos o telefone para convidar pelo WhatsApp), guardada cifrada na 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​

O que acontece, na ordem

1. O recrutador escolhe a vaga como assessment no plano de entrevistas da Ashby (assessment.list).
2. Ao iniciar o assessment, a Ashby chama assessment.start. Respondemos na hora com o assessment_id; a Aya convida o candidato pelo WhatsApp (ou por e-mail, sem telefone) e avisamos “convidado”.
3. A cada passo mandamos assessment.update: Started na primeira resposta, “em andamento” durante a conversa, “expirado” se o candidato parar de responder.
4. Avaliada a entrevista, o update traz assessment_result (nota geral), o link do relatório e, em metadata, a nota de cada competência com a citação literal da fala que a sustenta.

Perguntas frequentes

O payload da Ashby não traz telefone. Como a Aya convida?

Se a chave da Ashby tiver candidatesRead, buscamos o telefone em candidate.info e a Aya convida pelo WhatsApp. Sem telefone, o convite vai por e-mail com o link da mesma entrevista na web — e o canal usado aparece no status dentro da Ashby.

A Ashby reenvia o mesmo start. Vira candidato duplicado?

Não. O par (candidatura, assessment) é único enquanto o assessment vale: um reenvio devolve o mesmo assessment_id. Depois de um assessment.cancel, um novo start para a mesma candidatura funciona normalmente.

O que aparece de erro para o recrutador?

Vaga fechada na Talpy ou conta sem saldo voltam como 422 com message legível, que a Ashby mostra na tela. Chave inválida volta 401 no formato de erro da Ashby (success:false, errorInfo).

Conectores e ATS

Não quer programar? Dá para ligar a Talpy a outras ferramentas por automação, usando os webhooks para sair e a API para entrar.

Serve para jogar candidato avaliado numa planilha, abrir card no seu quadro, avisar o time no chat ou empurrar o aprovado para o seu ATS.

Receita pronta (Zapier, Make ou 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.