← Dashboard · Webhooks · vagafit.net

API VagaFit

Hub de documentação para integrar o ATS VagaFit com Make, Zapier, n8n ou ferramentas próprias. Base URL: https://vagafit.net

Visão geral

A API HTTP vive em /api/*. Esta página (/api) é só documentação; as rotas de dados continuam em subpaths (/api/vagas, /api/colaboradores-internos/sync, etc.).

Para automações externas (Make/Zapier), prefira webhooks outbound (o VagaFit chama você) ou o sync secret nas rotas de sincronização — sem cookie de sessão.

Autenticação

1. Sessão B2B (dashboard)

Login em /clientes (magic link ou Google). O cookie de sessão é enviado automaticamente em requests same-origin do dashboard. Em scripts externos, a sessão costuma não ser prática — use o sync secret ou webhooks.

2. Sync secret (Make / Zapier / HTTP)

Para POST …/colaboradores…/sync e POST …/sucessao/risco, autentique com o mesmo valor do webhook_secret da organização (Configurações → Comunicação), em um destes formatos: 

X-VagaFit-Sync-Secret: SEU_WEBHOOK_SECRET
Authorization: Bearer SEU_WEBHOOK_SECRET

Alternativa aceita: header X-VagaFit-Signature com o secret em texto puro (não confundir com a assinatura HMAC dos webhooks outbound).

sync secret Configure o secret no dashboard; nunca o commite em repositórios públicos.

3. Assinatura de webhooks outbound

Quando o VagaFit envia eventos para a sua URL, o header X-VagaFit-Signature é o HMAC-SHA256 do body JSON com o webhook_secret. Detalhes em /docs/webhooks.

Webhooks outbound

Configure URL + secret em Comunicação → Webhooks outbound. Cada evento é um POST JSON. Falhas ficam na aba Sheets EventosWebhook (até 5 tentativas; o cron diário reprocessa pendentes).

Eventos principais:

Documentação completa (payloads, WhatsApp, portal): /docs/webhooks

APIs de sync / inbound

Rotas pensadas para integração externa (HRIS → VagaFit, Make, Zapier).

POST /api/v1/colaboradores/sync sync secret ou sessão

Alias estável. Também disponível em POST /api/colaboradores-internos/sync (mesmo contrato).

Body:

{
  "colaboradores": [
    {
      "nome": "Ana Silva",
      "email": "ana@empresa.com",
      "area": "Produto",
      "senioridade": "Pleno",
      "cargo_atual": "Product Analyst",
      "departamento": "Produto",
      "tempo_casa_meses": 18,
      "tags": "sql, analytics",
      "skills_texto": "SQL, Looker, discovery",
      "avaliacao_resumo": "Forte em ownership",
      "metas_resumo": "OKRs Q2"
    }
  ],
  "full_sync": false
}

Resposta (200): { ok, via: "secret"|"sessao", …contadores do upsert }

Sucessão — cargo crítico em risco (9-Box)

Quando Mereo (ou outro RH) sinaliza que uma liderança crítica pode ficar vaga, envie o alerta. O VagaFit ranqueia o Banco de Talentos, abre uma vaga no Kanban e vincula os melhores perfis (origem: sucessao). Sucessores internos (funcionários) usam Mobilidade / sync de colaboradores.

POST /api/v1/sucessao/risco sync secret ou sessão

Alias: POST /api/sucessao/risco e POST /api/sucessao/eventos (mesmo handler).

Body (exemplo Mereo / Make):

{
  "source": "mereo",
  "external_id": "mereo-role-123",
  "event_type": "lideranca_critica_em_risco",
  "cargo": {
    "titulo": "Head de Produto",
    "area": "Produto",
    "senioridade": "Sênior",
    "skills": ["product strategy", "OKRs", "liderança"],
    "descricao": "Liderança do chapter de produto"
  },
  "titular": {
    "nome": "João Silva",
    "email": "joao@empresa.com",
    "box_9": "alto_potencial",
    "risco": "saida_iminente"
  },
  "min_score": 70,
  "limite": 10,
  "criar_vaga": true,
  "vincular_matches": true
}

Resposta (201): evento, matches, vaga_id, lista vinculados.

Listagem (sessão B2B): GET /api/sucessao/eventos · GET /api/sucessao/:id. UI: dashboard → Sucessão.

Outras rotas de mobilidade (sessão B2B)

Ingest de talentos (extensão)

POST /api/talentos/ingest origem permitida

Usado pela extensão Chrome. Body com curriculo (texto ≥ 50 chars); opcional vaga_titulo / vaga_id para vincular candidatura + score. Origem deve ser extension ou domínio permitido (CORS).

Cron interno

GET /api/cron/daily — agendado pela Vercel; protegido por secret de cron. Reprocessa webhooks, lembretes de entrevista e rituais de experiência. Não use em integrações externas.

APIs B2B comuns (sessão)

Exigem cookie de sessão B2B. Úteis para scripts internos ou o próprio dashboard.

Vagas

Candidaturas

Config e automações

APIs públicas / candidato

Exemplos

curl — sync de colaboradores (Make/Zapier)

curl -X POST 'https://vagafit.net/api/v1/colaboradores/sync' \
  -H 'Content-Type: application/json' \
  -H 'X-VagaFit-Sync-Secret: SEU_WEBHOOK_SECRET' \
  -d '{
    "colaboradores": [
      { "nome": "Ana Silva", "email": "ana@empresa.com", "cargo_atual": "Analyst", "tags": "sql" }
    ],
    "full_sync": false
  }'

curl — sucessão / cargo crítico (9-Box)

curl -X POST 'https://vagafit.net/api/v1/sucessao/risco' \
  -H 'Content-Type: application/json' \
  -H 'X-VagaFit-Sync-Secret: SEU_WEBHOOK_SECRET' \
  -d '{
    "source": "mereo",
    "external_id": "mereo-role-123",
    "cargo": {
      "titulo": "Head de Produto",
      "area": "Produto",
      "senioridade": "Sênior",
      "skills": ["product strategy", "OKRs"]
    },
    "titular": { "risco": "saida_iminente" },
    "min_score": 70
  }'

fetch — listar vagas (sessão no browser)

const res = await fetch('https://vagafit.net/api/vagas', {
  credentials: 'include'
});
const vagas = await res.json();

Make — módulo HTTP

  1. Módulo HTTP → Make a request
  2. URL: https://vagafit.net/api/v1/colaboradores/sync
  3. Method: POST
  4. Headers: Content-Type: application/json, X-VagaFit-Sync-Secret: {{seu_secret}}
  5. Body type: Raw / JSON com o array colaboradores

Para receber eventos do ATS: use um Webhook Make (URL custom) e configure essa URL em Comunicação → Webhooks. Valide X-VagaFit-Signature (HMAC). Ver docs de webhooks.

Validar HMAC (Node)

const crypto = require('crypto');
function ok(secret, rawBody, signatureHeader) {
  const expected = crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
  return expected === signatureHeader;
}

Erros

Status Quando
400 Body inválido, campos obrigatórios ausentes
401 Sem sessão / sync secret inválido / token expirado
403 Origem CORS não autorizada
404 Recurso não encontrado
429 Rate limit (ex.: simulação de triagem)
502 Falha em dependência (ex.: IA na simulação)

Respostas de erro tipicamente: { "error": "mensagem" }.

Rate limits

Há rate limit em memória por IP em rotas sensíveis de simulação de triagem: 30 req / minuto em /api/triagem/sim/* → 429 se excedido.

Em serverless, o contador é por instância (proteção básica). Integrações Make/Zapier de sync não têm o mesmo limite explícito; evite bursts muito agressivos (respeite o máx. 2000 colaboradores/request).

Payload de contratação / PDI

Ative em Configurações → 5. Avançado. Ao mover para Contratado, o VagaFit emite contratacao.payload_pdi (e inclui o bloco em candidatura.contratada.data.payload_contratacao). 

{
  "evento": "contratacao.payload_pdi",
  "ts": "2026-07-20T15:00:00.000Z",
  "candidatura_id": "CD-12345678",
  "data": {
    "forcas": ["Comunicação", "Ownership"],
    "gaps_identificados": ["Desenvolver skill: python"],
    "sugestao_pdi_90_dias": [
      {
        "titulo": "Dominar o playbook do time em 30 dias",
        "prazo_dias": 90,
        "origem": "okr_rampa",
        "prioridade": 1
      }
    ],
    "colaborador": { "nome": "...", "email": "..." },
    "vaga_titulo": "Product Analyst",
    "score_match": 82,
    "atribuicao_canal": {
      "origem": "extension",
      "canal_label": "Extensão VagaFit",
      "veio_da_extensao": true,
      "chaves_cruzamento": { "email_colaborador": "ana@empresa.com" },
      "performance_pos_contratacao": { "metas_batidas_pct": null, "faturamento_atribuido": null },
      "custo_contratacao_eficiente": { "custo_por_contratacao": null }
    }
  }
}

No Make/n8n: filtre por evento === "contratacao.payload_pdi". Use atribuicao_canal.origem + e-mail para cruzar performance Mereo (semente de Custo por Contratação Eficiente). Detalhes em /docs/webhooks.

Dúvidas de produto: Central de Ajuda no dashboard. Esta página documenta a superfície pública/integração — endpoints internos de UI podem evoluir sem aviso.