docs.api.hero.badge

docs.api.hero.h1

docs.api.hero.lede

docs.api.hero.cobertura

docs.api.auth.h2

docs.api.auth.p1

http

Authorization: Bearer sk_live_5f2a9c1e7b4d8f0a3c6e9b2d5f8a1c4e7b0d3f6a9c2e5b8d1f4a7c0e3b6d9f2a

docs.api.auth.p2

docs.api.auth.nota

docs.api.amb.h2

docs.api.amb.p1

docs.api.amb.p2

	docs.api.amb.thProducao	docs.api.amb.thTestes
docs.api.amb.linha.prefixo.o	sk_live_	sk_test_
docs.api.amb.linha.dados.o	docs.api.amb.linha.dados.live	docs.api.amb.linha.dados.test
docs.api.amb.linha.header.o	live	sandbox
docs.api.amb.linha.whatsapp.o	docs.api.amb.linha.whatsapp.live	docs.api.amb.linha.whatsapp.test
docs.api.amb.linha.cota.o	docs.api.amb.linha.cota.live	docs.api.amb.linha.cota.test
docs.api.amb.linha.publica.o	docs.api.amb.linha.publica.live	docs.api.amb.linha.publica.test
docs.api.amb.linha.webhooks.o	docs.api.amb.linha.webhooks.live	docs.api.amb.linha.webhooks.test

docs.api.amb.nota

curl

# A mesma chamada, com a chave de testes: mesmos endpoints, dados de brinquedo.
# O -i mostra os cabeçalhos, onde aparece X-Ambiente: sandbox.
curl -i "https://talpy.ai/api/v1/jobs" \
  -H "Authorization: Bearer sk_test_3b7e1d9a4c60f28b5d3a7e1c9f0b4d68a2c5e9f13b7d0a46c8e2f5b9d1a3c706"

docs.api.escopos.h2

docs.api.escopos.p

docs.api.escopos.thEscopo	docs.api.escopos.thPermite	docs.api.escopos.thEndpoints
jobs:read	docs.api.escopo.jobs:read	GET /api/v1/jobs
candidates:read	docs.api.escopo.candidates:read	GET /api/v1/jobs/{id}/candidatesGET /api/v1/candidates/{id}
candidates:write	docs.api.escopo.candidates:write	POST /api/v1/candidates
jobs:write	docs.api.escopo.jobs:write	POST /api/v1/jobsPATCH /api/v1/jobs/{id}
whatsapp:send	docs.api.escopo.whatsapp:send	POST /api/v1/candidates/{id}/whatsapp
mcp:read	docs.api.escopo.mcp:read	POST /api/mcp
interviews:read	docs.api.escopo.interviews:read	GET /api/v1/candidates/{id}

docs.api.limites.h2

docs.api.limites.p1

docs.api.limites.thCabecalho	docs.api.limites.thTraz
X-RateLimit-Limit	docs.api.limites.rl.limit
X-RateLimit-Remaining	docs.api.limites.rl.remaining
X-RateLimit-Reset	docs.api.limites.rl.reset
X-Ambiente	docs.api.limites.rl.ambiente
Retry-After	docs.api.limites.rl.retry

docs.api.limites.dim

http

HTTP/1.1 200 OK
Content-Type: application/json
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 118
X-RateLimit-Reset: 43
X-Ambiente: sandbox
Access-Control-Allow-Origin: *

docs.api.limites.cors

docs.api.erros.h2

docs.api.erros.p

error	HTTP	docs.api.erros.thQuando	docs.api.erros.thFaca
chave_ausente	401	docs.api.erro.chave_ausente.quando	docs.api.erro.chave_ausente.faca
chave_invalida	401	docs.api.erro.chave_invalida.quando	docs.api.erro.chave_invalida.faca
chave_revogada	401	docs.api.erro.chave_revogada.quando	docs.api.erro.chave_revogada.faca
chave_expirada	401	docs.api.erro.chave_expirada.quando	docs.api.erro.chave_expirada.faca
escopo_insuficiente	403	docs.api.erro.escopo_insuficiente.quando	docs.api.erro.escopo_insuficiente.faca
limite_excedido	429	docs.api.erro.limite_excedido.quando	docs.api.erro.limite_excedido.faca
json_invalido	400	docs.api.erro.json_invalido.quando	docs.api.erro.json_invalido.faca
jobId_ausente	400	docs.api.erro.jobId_ausente.quando	docs.api.erro.jobId_ausente.faca
name_ausente	400	docs.api.erro.name_ausente.quando	docs.api.erro.name_ausente.faca
cvBase64_invalido	400	docs.api.erro.cvBase64_invalido.quando	docs.api.erro.cvBase64_invalido.faca
vaga_nao_encontrada	404	docs.api.erro.vaga_nao_encontrada.quando	docs.api.erro.vaga_nao_encontrada.faca
candidato_nao_encontrado	404	docs.api.erro.candidato_nao_encontrado.quando	docs.api.erro.candidato_nao_encontrado.faca

docs.api.erros.exEscopo

http

HTTP/1.1 403 Forbidden

{
  "error": "escopo_insuficiente",
  "message": "Esta chave não tem a permissão \"candidates:write\". Gere uma chave com esse escopo em Configurações › API.",
  "escopos_da_chave": ["jobs:read", "candidates:read"]
}

docs.api.erros.exLimite

http

HTTP/1.1 429 Too Many Requests
Retry-After: 37
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 37

{
  "error": "limite_excedido",
  "message": "Máximo de 120 requisições por minuto por chave. Tente de novo em 37s."
}

docs.api.endpoints.h2

docs.api.endpoints.p

GET/api/v1/jobsjobs:read

docs.api.ep.jobsList.titulo

docs.api.ep.jobsList.desc

docs.api.endpoints.paramsLabel docs.api.ep.jobsList.params

curl

curl "https://talpy.ai/api/v1/jobs" \
  -H "Authorization: Bearer sk_live_5f2a9c1e7b4d8f0a3c6e9b2d5f8a1c4e7b0d3f6a9c2e5b8d1f4a7c0e3b6d9f2a"

docs.api.endpoints.respostaLabel

json

{
  "jobs": [
    {
      "id": "clx1a2b3c4d5e6f",
      "title": "Atendente de Loja",
      "seniority": "Júnior",
      "status": "ATIVA",
      "applyToken": "clx9z8y7x6w5v4u",
      "createdAt": "2026-07-10T13:20:00.000Z"
    }
  ]
}

POST/api/mcpmcp:read

docs.api.ep.mcp.titulo

docs.api.ep.mcp.desc

docs.api.endpoints.paramsLabel docs.api.ep.mcp.params

curl

curl -X POST "https://talpy.ai/api/mcp" \
  -H "Authorization: Bearer sk_live_5f2a9c1e7b4d8f0a3c6e9b2d5f8a1c4e7b0d3f6a9c2e5b8d1f4a7c0e3b6d9f2a" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call",
       "params":{"name":"listar_candidatos",
                 "arguments":{"vaga_id":"clx1a2b3c4d5e6f","nota_minima":8}}}'

docs.api.endpoints.respostaLabel

json

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [{ "type": "text", "text": "{ \"vaga\": \"Atendente de Loja\", \"total\": 2, ... }" }]
  }
}

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

docs.api.ep.jobDetail.titulo

docs.api.ep.jobDetail.desc

docs.api.endpoints.paramsLabel docs.api.ep.jobDetail.params

curl

curl "https://talpy.ai/api/v1/jobs/clx1a2b3c4d5e6f" \
  -H "Authorization: Bearer sk_live_5f2a9c1e7b4d8f0a3c6e9b2d5f8a1c4e7b0d3f6a9c2e5b8d1f4a7c0e3b6d9f2a"

docs.api.endpoints.respostaLabel

json

{
  "id": "clx1a2b3c4d5e6f",
  "title": "Atendente de Loja",
  "seniority": "Pleno",
  "openings": 2,
  "status": "ATIVA",
  "candidates": 14,
  "applyToken": "clx9z8y7x6w5v4u",
  "profile": { "competencias": [ { "nome": "Comunicação", "peso": 40 } ] }
}

POST/api/v1/jobsjobs:write

docs.api.ep.jobCreate.titulo

docs.api.ep.jobCreate.desc

docs.api.endpoints.paramsLabel docs.api.ep.jobCreate.params

curl

curl -X POST "https://talpy.ai/api/v1/jobs" \
  -H "Authorization: Bearer sk_live_5f2a9c1e7b4d8f0a3c6e9b2d5f8a1c4e7b0d3f6a9c2e5b8d1f4a7c0e3b6d9f2a" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Atendente de Loja",
    "seniority": "Pleno",
    "openings": 2,
    "description": "Atendimento ao cliente em loja física, operação de caixa e organização de estoque.",
    "status": "ATIVA"
  }'

docs.api.endpoints.respostaLabel

json

{
  "id": "clx1a2b3c4d5e6f",
  "title": "Atendente de Loja",
  "status": "ATIVA",
  "applyToken": "clx9z8y7x6w5v4u",
  "applyUrl": "https://talpy.ai/apply/clx9z8y7x6w5v4u"
}

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

docs.api.ep.jobPatch.titulo

docs.api.ep.jobPatch.desc

docs.api.endpoints.paramsLabel docs.api.ep.jobPatch.params

curl

curl -X PATCH "https://talpy.ai/api/v1/jobs/clx1a2b3c4d5e6f" \
  -H "Authorization: Bearer sk_live_5f2a9c1e7b4d8f0a3c6e9b2d5f8a1c4e7b0d3f6a9c2e5b8d1f4a7c0e3b6d9f2a" \
  -H "Content-Type: application/json" \
  -d '{"status":"ENCERRADA"}'

docs.api.endpoints.respostaLabel

json

{ "id": "clx1a2b3c4d5e6f", "status": "ENCERRADA", "title": "Atendente de Loja" }

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

docs.api.ep.whatsapp.titulo

docs.api.ep.whatsapp.desc

docs.api.endpoints.paramsLabel docs.api.ep.whatsapp.params

curl

curl -X POST "https://talpy.ai/api/v1/candidates/clxcand0001/whatsapp" \
  -H "Authorization: Bearer sk_live_5f2a9c1e7b4d8f0a3c6e9b2d5f8a1c4e7b0d3f6a9c2e5b8d1f4a7c0e3b6d9f2a" \
  -H "Content-Type: application/json" \
  -d '{"acao":"entrevista"}'

docs.api.endpoints.respostaLabel

json

{ "ok": true, "interviewId": "clxint0001", "status": "CONVIDADA" }

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

docs.api.ep.jobCandidates.titulo

docs.api.ep.jobCandidates.desc

docs.api.endpoints.paramsLabel docs.api.ep.jobCandidates.params

curl

curl "https://talpy.ai/api/v1/jobs/clx1a2b3c4d5e6f/candidates" \
  -H "Authorization: Bearer sk_live_5f2a9c1e7b4d8f0a3c6e9b2d5f8a1c4e7b0d3f6a9c2e5b8d1f4a7c0e3b6d9f2a"

docs.api.endpoints.respostaLabel

json

{
  "candidates": [
    {
      "id": "clxcand0001",
      "name": "Maria Souza",
      "email": "maria@exemplo.com",
      "phone": "11999990000",
      "matchScore": 78,
      "status": "AVALIADO",
      "createdAt": "2026-07-11T09:00:00.000Z",
      "avaliacao": {
        "overallScore": 8.2,
        "adherence": 86,
        "competencies": [
          { "competencia": "Comunicação", "score": 8.8, "peso": 40, "evidencia": "..." }
        ],
        "summary": "..."
      }
    }
  ]
}

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

docs.api.ep.candidateDetail.titulo

docs.api.ep.candidateDetail.desc

docs.api.endpoints.paramsLabel docs.api.ep.candidateDetail.params

curl

curl "https://talpy.ai/api/v1/candidates/clxcand0001" \
  -H "Authorization: Bearer sk_live_5f2a9c1e7b4d8f0a3c6e9b2d5f8a1c4e7b0d3f6a9c2e5b8d1f4a7c0e3b6d9f2a"

docs.api.endpoints.respostaLabel

json

{
  "id": "clxcand0001",
  "name": "Maria Souza",
  "email": "maria@exemplo.com",
  "phone": "11999990000",
  "jobId": "clx1a2b3c4d5e6f",
  "jobTitle": "Atendente de Loja",
  "matchScore": 78,
  "matchNotes": "Triado via API pública — pdf",
  "status": "APROVADO",
  "decidedByName": "Ana (RH)",
  "decidedAt": "2026-07-12T15:40:00.000Z",
  "decisionNote": "Segue para entrevista final.",
  "createdAt": "2026-07-11T09:00:00.000Z",
  "avaliacao": {
    "overallScore": 8.2,
    "adherence": 86,
    "competencies": [
      { "competencia": "Comunicação", "score": 8.8, "peso": 40, "evidencia": "..." }
    ],
    "redFlags": [],
    "highlights": ["Boa articulação de exemplos concretos."],
    "summary": "..."
  }
}

POST/api/v1/candidatescandidates:write

docs.api.ep.candidateCreate.titulo

docs.api.ep.candidateCreate.desc

docs.api.endpoints.paramsLabel docs.api.ep.candidateCreate.params

curl

curl -X POST "https://talpy.ai/api/v1/candidates" \
  -H "Authorization: Bearer sk_live_5f2a9c1e7b4d8f0a3c6e9b2d5f8a1c4e7b0d3f6a9c2e5b8d1f4a7c0e3b6d9f2a" \
  -H "Content-Type: application/json" \
  -d '{
    "jobId": "clx1a2b3c4d5e6f",
    "name": "João Pereira",
    "email": "joao@exemplo.com",
    "phone": "11988887777",
    "cvText": "Currículo: 3 anos como atendente, experiência com Zendesk..."
  }'

docs.api.endpoints.respostaLabel

json

{
  "candidateId": "clxcand0099",
  "matchScore": 71
}

docs.api.webhooks.h2

docs.api.webhooks.p1

docs.api.webhooks.p2

docs.api.webhooks.eventosLabel

docs.api.webhooks.thEvento	docs.api.webhooks.thQuando
candidato.criado	docs.api.evento.candidato.criado
candidato.triado	docs.api.evento.candidato.triado
entrevista.iniciada	docs.api.evento.entrevista.iniciada
candidato.avaliado	docs.api.evento.candidato.avaliado
candidato.decidido	docs.api.evento.candidato.decidido

docs.api.webhooks.payloadLabel

docs.api.webhooks.payloadDesc

json

{
  "event": "candidato.avaliado",
  "createdAt": "2026-07-11T14:02:00.000Z",
  "data": {
    "candidateId": "clxcand0001",
    "candidateName": "Maria Souza",
    "jobId": "clx1a2b3c4d5e6f",
    "overallScore": 8.2,
    "adherence": 86,
    "competencies": [
      { "competencia": "Comunicação", "score": 8.8, "peso": 40, "evidencia": "..." }
    ]
  }
}

docs.api.webhooks.verifLabel

docs.api.webhooks.verifDesc

javascript

const crypto = require("crypto");

function assinaturaValida(secret, corpoCru, headerAssinatura) {
  const recebido = (headerAssinatura || "").replace(/^sha256=/, "");
  const esperado = crypto
    .createHmac("sha256", secret)
    .update(corpoCru) // o corpo BRUTO da requisição, antes de fazer JSON.parse
    .digest("hex");
  return crypto.timingSafeEqual(Buffer.from(recebido), Buffer.from(esperado));
}

// Ex.: num handler Express
app.post("/webhooks/talpy", express.raw({ type: "*/*" }), (req, res) => {
  const assinatura = req.headers["x-talpy-signature"];
  if (!assinaturaValida(process.env.MEU_WEBHOOK_SECRET, req.body, assinatura)) {
    return res.status(401).send("assinatura inválida");
  }
  const evento = JSON.parse(req.body.toString("utf8"));
  console.log(evento.event, evento.data);
  res.sendStatus(200);
});

docs.api.webhooks.nota

docs.api.con.h2

docs.api.con.p1

docs.api.con.p2

docs.api.con.receitaLabel

text

docs.api.zapierReceita