Recruit API Reference

A Recruit API é uma REST API que permite acesso programático a todas as funcionalidades da plataforma Eu Nerd: recrutamento, CRM, ticketing, contratos, financeiro, conteúdo e mais. Projetada para integrações com agentes de IA, automações e sistemas externos.

Base URL

https://wzcftlekhxlsavsjgfhb.supabase.co/functions/v1/openclaw-api

Todas as requisições devem usar HTTPS. HTTP não é suportado.

Recursos Disponíveis (21)

Referência rápida de todos os recursos e métodos HTTP suportados:

Authentication

Autentique suas requisições incluindo o header Authorization com o valor Bearer {RECRUIT_API_KEY}.

curl -H "Authorization: Bearer ocl_sk_xxxxxxxxxxxxx" \
     -H "Content-Type: application/json" \
     https://wzcftlekhxlsavsjgfhb.supabase.co/functions/v1/openclaw-api/candidates

Pagination & Search

Todos os endpoints de listagem suportam paginação via query parameters:

Exemplo de resposta paginada

{
  "data": [...],
  "total": 342,
  "limit": 50,
  "offset": 0
}

Para navegar páginas, incremente o offset pelo valor de limit:

# Página 1
GET /candidates?limit=50&offset=0

# Página 2
GET /candidates?limit=50&offset=50

# Página 3
GET /candidates?limit=50&offset=100

Rate Limits

A API implementa dois tipos de limitação:

Ao exceder o limite, a API retorna 429 Too Many Requests. Implemente exponential backoff para lidar com limites temporários.

Error Handling

A API usa códigos HTTP padrão. Respostas de erro incluem um campo error com descrição legível:

{
  "error": "Candidate not found"
}

Candidates

Gerencie o banco de talentos de técnicos de TI. Candidatos possuem geolocalização, certificações, perfil técnico e podem ser movidos por etapas de recrutamento (triagem → entrevista → proposta → contratado → arquivado).

List candidates

curl -H "Authorization: Bearer $KEY" \
  "$BASE/candidates?etapa=contratado&cidade=São Paulo&limit=10"

{
  "data": [
    {
      "id": "uuid",
      "nome": "João Silva",
      "email": "joao@email.com",
      "telefone": "11999999999",
      "cidade": "São Paulo",
      "estado": "SP",
      "nivel_senioridade": "pleno",
      "etapa": "contratado",
      "status": "adequado",
      "cnpj": "12.345.678/0001-90",
      "created_at": "2024-01-15T10:00:00Z",
      "total_jobs_completed": 42
    }
  ],
  "total": 1,
  "limit": 10,
  "offset": 0
}

Get candidate

Retorna dados detalhados incluindo perfil técnico, categorias de trabalho e disponibilidade.

Create candidate

curl -X POST -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "nome": "Maria Souza",
    "email": "maria@email.com",
    "telefone": "21988887777",
    "cidade": "Rio de Janeiro",
    "estado": "RJ",
    "nivel_senioridade": "pleno",
    "certificacoes": ["ITIL", "Azure"]
  }' "$BASE/candidates"

Update candidate

Campos atualizáveis: nome, email, telefone, cidade, estado, bairro, etapa, status, certificacoes, nivel_senioridade, nivel_ingles, observacoes, cnpj, cpf, disponibilidade_inicio, service_radius_km.

curl -X PATCH -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"etapa": "entrevista", "status": "adequado"}' \
  "$BASE/candidates/{id}"

Vacancies

Gerencie vagas de emprego com suporte a publicação multi-canal.

List vacancies

Filtros: status (open, closed, draft), search (título, cliente).

Get vacancy

Create vacancy

Update vacancy

Campos atualizáveis: title, description, client_name, location, status, work_mode, contract_type, job_area, requirements, salary_range_min, salary_range_max, published_at.

Vacancy Applications

Lista as candidaturas de uma vaga específica, incluindo dados do candidato.

Filtros: status (new, reviewed, shortlisted, rejected).

curl -H "Authorization: Bearer $KEY" \
  "$BASE/vacancy-applications/{vacancy_id}?status=new"

{
  "vacancy": { "id": "uuid", "title": "Técnico de Redes" },
  "data": [
    {
      "id": "uuid",
      "candidate_id": "uuid",
      "candidate_name": "João Silva",
      "candidate_email": "joao@email.com",
      "candidate_phone": "11999999999",
      "candidate_city": "São Paulo",
      "candidate_state": "SP",
      "form_answers": {},
      "status": "new",
      "created_at": "2024-01-15T10:00:00Z"
    }
  ],
  "total": 1, "limit": 50, "offset": 0
}

Vacancy Requests

Solicitações de vagas enviadas por clientes através do portal. Podem ser aprovadas e convertidas em vagas.

List vacancy requests

Filtros: status (pending, approved, rejected), client_name.

Get vacancy request

Create vacancy request

Update vacancy request

Campos atualizáveis: status, admin_notes, reviewed_by, reviewed_at, converted_vacancy_id, job_title, job_description, work_mode, contract_type, positions_count.

Allocations

Alocações ativas de técnicos em clientes. Inclui dados de billing e período.

List allocations

Get allocation

Retorna dados da alocação incluindo o candidato associado (nome, email, cidade, estado).

Scheduling

Gerencie links de agendamento de entrevistas para candidatos.

List scheduling links

Filtros: candidate_id, vacancy_id.

Create scheduling link

curl -X POST -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"candidate_id":"uuid","created_by":"uuid"}' \
  "$BASE/scheduling"

{
  "data": {
    "id": "uuid",
    "candidate_id": "uuid",
    "vacancy_id": null,
    "token": "uuid-token",
    "expires_at": "2024-01-22T10:00:00Z",
    "created_at": "2024-01-15T10:00:00Z",
    "scheduling_url": "https://encontreumnerd.com.br/agendar/uuid-token"
  }
}

Companies

Gerencie empresas clientes B2B.

List companies

Get company

Create company

Update company

Campos: name, cnpj, email, phone, city, state, segment, is_active, contract_type, monthly_value, status.

Deal Pipelines

Lista os pipelines de vendas ativos com seus estágios configurados.

curl -H "Authorization: Bearer $KEY" "$BASE/deal-pipelines"

Deals

Gerencie oportunidades comerciais no CRM. Mudanças de estágio são automaticamente registradas como atividades.

List deals

Filtros: pipeline_id, stage, search.

Get deal

Inclui company_name resolvido da tabela de empresas.

Create deal

Update deal

Campos: stage, value, priority, contact_name, contact_email, contact_phone, notes, owner_id.

curl -X PATCH -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"stage": "proposta", "value": 5000}' \
  "$BASE/deals/{id}"

Deal Activities

Histórico de atividades de um deal: notas, mudanças de estágio, emails, etc.

List activities

Filtros: deal_id obrigatório, type (note, stage_change, email, call, meeting).

Create activity

Proposals

Propostas comerciais com workflow de envio, tracking de visualização e aceitação via link público.

List proposals

Filtros: status (rascunho, ativa, aceita, expirada), client_name (busca parcial), proposal_type, search (título ou cliente).

Retorna: id, title, slug, client_name, proposal_type, status, sent_at, accepted_at, expires_at, created_at.

Get proposal

Retorna TODOS os campos incluindo content (seções), metadata, signing_token, original_content, client_logo_url, source_file_url, vacancy_request_id, created_by, accepted_by.

Get proposal tracking

Retorna dados de tracking: signing_token (para URL pública /proposta/{token}), sent_at, accepted_at, accepted_by, expires_at, metadata.

Create proposal

Cria proposta em status rascunho. Auto-gera slug e signing_token (UUID).

Update proposal

Campos permitidos: status, title, client_name, content, metadata, expires_at, recipient_name, recipient_email, proposal_type, client_logo_url, source_file_url.

Service Orders

Ordens de serviço de campo (OS). Códigos auto-gerados no formato OS-YYYY-XXXXX.

List service orders

Get service order

Create service order

Update service order

Campos: status, priority, category, candidate_id, scheduled_date, completion_notes, rating, description.

Tickets

Sistema de helpdesk. Tickets são auto-numerados no formato TK-YYYYMMDD-XXXX.

List tickets

Filtros: status (open, in_progress, resolved, closed).

Get ticket

Inclui client_ticket_messages associadas.

Create ticket

Update ticket

Campos: status, priority, category, assigned_to, resolution_notes.

Leads

Leads originados de formulários de diagnóstico, formulários de contato, website e deals de CRM. Subset filtrado da tabela client_tickets por source.

List leads

Filtros: status, source (diagnostic-form, diagnostic-form-partial, contact-form, website, crm-deal).

Busca: sender_email, sender_name, subject, client_name.

Get lead

Retorna registro completo incluindo parsed_data com:

Contracts

Contratos digitais com assinaturas. Somente leitura via API.

List contracts

List contracts

Cada contrato inclui um objeto candidate com id, nome e curriculo_url.

Get contract

Inclui contract_signatures associadas e um objeto candidate com id, nome, email, telefone, curriculo_url e curriculo_mime_type.

Document Signatures

Crie e gerencie solicitações de assinatura digital de documentos. Suporta upload de URLs externas, envio de emails automático e download de documentos assinados.

List signature requests

Filtros: status (sent, partially_signed, completed, cancelled).

Get signature request

Inclui todos os document_signature_recipients.

Get signature status

Resumo: total, assinados, pendentes. Inclui signing_url para pendentes.

Download document

Query: format=url (default, retorna signed URL válida por 1h) ou format=binary (retorna o PDF).

Create signature request

curl -X POST -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Contrato de Prestação",
    "file_url": "https://example.com/contrato.pdf",
    "file_name": "contrato-prestacao.pdf",
    "recipients": [
      { "name": "João Silva", "email": "joao@email.com" },
      { "name": "Maria Souza", "email": "maria@email.com" }
    ],
    "message": "Por favor assine o contrato anexo."
  }' "$BASE/document-signatures"

Resend signing email

Reenvia email de assinatura para destinatários pendentes. Opcionalmente passe recipient_id para reenviar apenas para um.

Cancel signature request

Cancela a solicitação e todos os destinatários pendentes.

Invoice Batches

Lotes de pagamento de colaboradores via Transfeera (PIX/TED). O fluxo é: criar batch → processar (cria transferências) → fechar (executa pagamentos).

List batches

Filtros: status. Resposta enriquecida com estatísticas de faturas.

Get batch detail

Inclui faturas, transações de pagamento e estatísticas agregadas.

Check payment status

Retorna status de cada transação Transfeera com resumo (pending, processing, completed, failed, returned).

Process batch

Cria transferências na Transfeera para todas as faturas aprovadas. Inclui anti-duplicação, split automático de valores acima de R$15.000 e resolução de chaves PIX.

Close batch

Fecha o lote na Transfeera, disparando os pagamentos efetivos.

Employee Invoices

Faturas individuais de colaboradores dentro de um batch de pagamento.

List invoices

Filtros: status, batch_id, employee_id.

Get invoice

Inclui dados do colaborador (nome, email, cnpj, cargo, departamento).

Update invoice

Campos: status, paid_at, notes, final_value, rejection_reason.

curl -X PATCH -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"status":"paid","notes":"Pago via Omie"}' \
  "$BASE/employee-invoices/{id}"

Provider Invoices

Notas fiscais de prestadores de serviço (candidatos contratados).

List provider invoices

Filtros: status, candidate_id.

Get provider invoice

Inclui dados do candidato (nome, email, cnpj).

Update provider invoice

Campos: status, notes, rejection_reason, estimated_payment_date, paid_at.

Employees

Cadastro e consulta de colaboradores internos.

List employees

Filtros: status, departamento, tipo_contrato, search (nome, email, cargo).

Get employee

Retorna todos os campos do colaborador incluindo dados bancarios.

Create employee

curl -X POST -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "nome": "Maria Silva",
    "email": "maria@empresa.com",
    "cargo": "Analista de TI",
    "departamento": "Tecnologia",
    "tipo_contrato": "pj"
  }' "$BASE/employees"

{
  "data": {
    "id": "uuid",
    "nome": "Maria Silva",
    "email": "maria@empresa.com",
    "cargo": "Analista de TI",
    "departamento": "Tecnologia",
    "tipo_contrato": "pj",
    "status": "ativo",
    "data_admissao": "2026-03-19",
    "created_at": "2026-03-19T14:00:00Z"
  }
}

WhatsApp

Envie mensagens via Meta Cloud API usando templates aprovados.

curl -X POST -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "template_id": "uuid",
    "phone": "11999999999",
    "variables": { "nome": "João", "empresa": "ACME" }
  }' "$BASE/whatsapp"

{
  "success": true,
  "meta_status": 200,
  "wamid": "wamid.xxxxx",
  "provider_response": { ... }
}

Articles

CRUD completo para o blog/knowledge base. Suporta lookup por UUID ou slug. Auto-geração de slug e preenchimento de campos SEO.

List articles

Filtros: status (draft, published, archived), category.

Get article

Aceita UUID ou slug como identificador.

Create article

Update article

Aceita UUID ou slug. Todos os campos do POST são atualizáveis.

Delete article

Remove permanentemente o artigo.

Metrics

Métricas agregadas da plataforma em tempo real.

{
  "candidates": {
    "total": 3200,
    "triagem": 450,
    "entrevista": 89,
    "proposta": 23,
    "contratado": 1800,
    "arquivado": 838,
    "withCnpj": 1200,
    "profileComplete": 950
  },
  "total_vacancies": 45,
  "open_tickets": 12,
  "active_service_orders": 8
}

Payables (Contas a Pagar)

Gerenciamento de contas a pagar com filtros por status, período e busca.

Returns detail with joined category, company, and bank_account.

Create payable

{
  "description": "Aluguel escritório",
  "amount": 5000.00,
  "due_date": "2026-05-10",
  "category_id": "uuid",
  "company_id": "uuid",
  "notes": "Contrato mensal"
}

Update payable

Allowed: description, amount, due_date, status, paid_date, paid_amount, notes, category_id, bank_account_id.

Receivables (Contas a Receber)

Gerenciamento de contas a receber com filtros por status, período e busca.

Detail with joined category, company, and bank_account.

Create receivable

Update receivable

Allowed: description, amount, due_date, status, received_date, received_amount, notes, category_id, bank_account_id.

Cashflow (Fluxo de Caixa)

Projeção diária do fluxo de caixa com saldos brutos e ajustados.

{
  "totals": {
    "total_payables_pending": 125000,
    "total_payables_overdue": 8500,
    "total_receivables_pending": 340000,
    "total_receivables_overdue": 15000
  },
  "daily": [
    {
      "date": "2026-04-14",
      "payables_due": 5000,
      "payables_paid": 5000,
      "receivables_due": 12000,
      "receivables_received": 0,
      "receivables_adjusted": 11040,
      "balance": 7000,
      "balance_adjusted": 6040
    }
  ],
  "settings": {
    "default_rate": 0.03,
    "variable_cost_pct": 0.05
  }
}

Finance Settings

Configurações financeiras globais para projeções de caixa.

Allowed: default_default_rate, default_variable_cost_pct, payout_batch_day, horizon_days.

Recurring Rules (Regras Recorrentes)

Regras para geração automática de contas a pagar/receber recorrentes.

Required: type, description, amount, recurrence, start_date.

Categories (Categorias Financeiras)

Categorias para classificação de contas a pagar e receber. Suporta upsert via omie_code.

{
  "name": "Infraestrutura",
  "type": "payable",
  "omie_code": "1.01.03",
  "is_active": true
}

Bank Accounts (Contas Bancárias)

Consulta de contas bancárias com saldo atual e dados de identificação.

Interview Bookings

Gerenciamento de agendamentos de entrevista com suporte a marcação de conduzida e avaliação.

Detail with joined slot, candidate, and vacancy data.

Update booking

{
  "conducted": true,
  "conduct_notes": "Candidato demonstrou boa experiência",
  "conduct_rating": 4
}

Google Drive

Operações de pasta e upload no Google Drive. Três ações disponíveis via sub-recurso.

Resolve folder

{
  "clientName": "Acme Corp",
  "parentFolderId": "1abc..."
}

Upload files

Max 10 files, 10MB each. Content must be base64-encoded.

Save (resolve + upload)

{
  "clientName": "Acme Corp",
  "parentFolderId": "1abc...",
  "files": [{ "name": "proposta.pdf", "mimeType": "application/pdf", "content": "base64..." }],
  "overwrite": true,
  "dealId": "uuid",
  "generatedBy": "crm-agent"
}