Plataforma · Técnico

API REST & Webhooks

O Nodus expõe uma API REST simples com autenticação Bearer token e webhooks com assinatura HMAC-SHA256. Use pra integrar com qualquer sistema que fale HTTP — Zapier, n8n, ferramentas internas, automações.

Base URL: https://nodusrh.com.br/api/index.php

Auth: Bearer token

Formato: JSON

Gerar um token

Logue no Nodus como admin.
Menu ⚙️ Sistema → API & Webhooks.
Click + Gerar Token.
Dê um nome descritivo (ex: "Zapier produção", "Integração ERP X").
Escolha o escopo:
- Leitura — só GET (consulta dados)
- Escrita — POST/PUT/DELETE (modifica dados)
Click Gerar → o token aparece UMA vez. Copie e guarde com segurança.

⚠️ Token aparece uma vez só

O Nodus armazena só o hash do token. Se perder, gere outro e revogue o anterior. Não há "recuperação".

Exemplos cURL

Listar funcionários

curl https://nodusrh.com.br/api/index.php?action=api_rest&resource=funcionarios \
  -H "Authorization: Bearer ndus_xxxx_yyyyy"

Info da empresa do token

curl https://nodusrh.com.br/api/index.php?action=api_rest&resource=me \
  -H "Authorization: Bearer ndus_xxxx_yyyyy"

Listar vagas abertas

curl https://nodusrh.com.br/api/index.php?action=api_rest&resource=vagas \
  -H "Authorization: Bearer ndus_xxxx_yyyyy"

Recursos disponíveis

resource	Retorna	Métodos
`me`	Info da empresa do token	GET
`funcionarios`	Lista de colaboradores ativos	GET
`departamentos`	Lista de departamentos	GET
`vagas`	Vagas (abertas + fechadas)	GET
`candidatos`	Candidatos das vagas	GET

Webhooks

Receba notificações em tempo real quando eventos acontecem na sua empresa. O Nodus posta JSON no seu endpoint com assinatura HMAC-SHA256.

Criar um webhook

Menu ⚙️ Sistema → API & Webhooks → card Webhooks → + Novo Webhook.
Nome: descritivo (ex: "Notificar ERP X").
URL de destino: https://seusistema.com.br/webhooks/nodus
Eventos: selecione quais quer receber (ou * pra todos).
Click Salvar → o secret aparece uma vez. Guarde.

Validar a assinatura no seu endpoint

Cada POST recebido vem com header X-Nodus-Signature: sha256=<hex>. Calcule HMAC-SHA256 do body bruto usando seu secret e compare. Se diferente, descarte (alguém forjou).

// Node.js exemplo
const crypto = require('crypto');
const signature = req.headers['x-nodus-signature'].replace('sha256=', '');
const expected = crypto
  .createHmac('sha256', WEBHOOK_SECRET)
  .update(req.rawBody)
  .digest('hex');
if (!crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))) {
  return res.status(401).send('invalid signature');
}
// processa o evento aqui...

Eventos disponíveis

A lista completa aparece dentro do produto. Categorias principais:

funcionario.criado · funcionario.atualizado · funcionario.desligado
vaga.criada · vaga.fechada
candidatura.recebida · candidato.aprovado
holerite.liberado · folha.fechada
ponto.batida · ponto.anomalia_detectada
kudos.publicado

Rate limits

Tipo	Limite	Resposta ao ultrapassar
Bearer token GET	120 req/min	HTTP 429
Bearer token POST	60 req/min	HTTP 429
Webhook outbound (do Nodus pra você)	Retry exponencial em falha	3 retries com backoff

Códigos de erro

HTTP	Significado	O que fazer
200	OK	—
400	Payload inválido	Confira corpo da requisição
401	Token inválido ou ausente	Gere outro token, revogue o antigo
403	Token sem permissão pra esse recurso	Use token com escopo "escrita" pra POST
429	Rate limit excedido	Espere a janela (~1 min)
500	Erro interno	Reporte no Suporte com timestamp

Endpoints públicos de saúde

Não exigem auth. Úteis pra monitoramento:

action	Retorna
`health`	`{status:'ok', db:'connected', ts}` · 503 se DB caiu
`version`	`{app, version, env, php, time, schema}`