Beta — acesso sob solicitaçãoDESENVOLVEDORES · API v1

Os dados do seu RH, no seu sistema.

A API pública da PRIEZA entrega, em JSON, os colaboradores, a estrutura da empresa, os chamados, as movimentações, as admissões, as vagas e indicadores agregados — só leitura, com até duas chaves ativas por empresa e escopos por recurso.

VISÃO GERAL

O que a v1 entrega

Base: https://api.prieza.app/v1. Todas as rotas são GET, respondem JSON em UTF-8 e usam nomes de campo em snake_case. A empresa vem da chave — nenhuma rota recebe o identificador da empresa.

Regra da API: não exibir dados dos usuários nem salários. Colaborador sai só com o vínculo profissional (matrícula, cargo, estrutura, situação e datas de admissão e desligamento); admissão sai só com etapa, datas e vaga. Ficam fora e-mail, telefone, endereço, documentos, nascimento, gênero, filiação, raça/cor, saúde, dependentes, ponto, recibos, folha, benefícios, salário, dados do candidato, texto livre (título e descrição de chamados, descrição de vagas), conteúdo das movimentações e as movimentações de promoção, ação salarial e desligamento.

PRIMEIROS PASSOS

Sua primeira chamada

  1. O administrador da empresa cria a chave em Configurador → Conexões → Chaves de API, escolhendo os escopos e a validade (30, 90, 180 ou 365 dias). Cada empresa tem no máximo 2 chaves ativas.
  2. A chave aparece uma única vez: guarde-a num cofre de segredos.
  3. Envie a chave no cabeçalho Authorization de cada requisição.
curl -s "https://api.prieza.app/v1/employees?limit=50" \
  -H "Authorization: Bearer $PRIEZA_API_KEY"
AUTENTICAÇÃO

Chave por empresa

Formato: prz_live_<prefixo de 8>_<segredo>, enviado como Authorization: Bearer prz_live_…. O prefixo identifica a chave na tela de gestão; o segredo nunca é guardado pela PRIEZA (só um hash).

A API recusa com 401 qualquer chave inválida, revogada ou expirada, e também a requisição que trouxer cookie de sessão do navegador: a v1 é para servidor a servidor. Revogar uma chave na tela tem efeito imediato.

ESCOPOS

Cada chave só lê o que precisa

EscopoRotasDados
employees:read
GET /v1/employees
Colaboradores: só o vínculo profissional (matrícula, cargo, estrutura, datas)
org:read
GET /v1/departments
GET /v1/cost-centers
GET /v1/positions
GET /v1/branches
Estrutura: departamentos, centros de custo, cargos e filiais
tickets:read
GET /v1/tickets
Chamados: status, categoria, prioridade, ids e datas, sem texto livre
movements:read
GET /v1/movements
Movimentações (sem promoção, ação salarial e desligamento)
admissions:read
GET /v1/admissions
Admissões digitais: só etapa, datas e vaga, sem dados do candidato
jobs:read
GET /v1/jobs
Vagas: título, status, estrutura e datas, sem descrição nem salário
indicators:read
GET /v1/indicators
GET /v1/indicators/{slug}
Indicadores agregados (turnover)

Chamada com escopo faltando recebe 403 forbidden. Além do escopo, o recurso exige o módulo contratado pela empresa: Gente & Gestão (colaboradores, estrutura, chamados e movimentações), Recrutamento & Seleção (admissões e vagas) e Dashboards BI (indicadores). Módulo fora do contrato recebe 403 module_not_contracted com o slug em module.

PAGINAÇÃO

Cursor, não página

Toda lista responde { data: [...], next_cursor }. Use limit (1 a 100, padrão 50) e repita a chamada com cursor=<next_cursor> até ele vir null. A ordem é estável (por id); o cursor é opaco e vale só para a listagem que o devolveu (cursor de outra rota responde 400 invalid_cursor).

let cursor = null;
do {
  const url = new URL("https://api.prieza.app/v1/departments");
  url.searchParams.set("limit", "100");
  if (cursor) url.searchParams.set("cursor", cursor);
  const res = await fetch(url, { headers: { Authorization: `Bearer ${key}` } });
  const page = await res.json();
  process(page.data);
  cursor = page.next_cursor;
} while (cursor);
ERROS

Corpo único: { error }

HTTPerrorQuando
400invalid_requestParâmetro fora do contrato (ex.: limit fora de 1 a 100).
400invalid_cursorCursor alterado ou de outra listagem. Recomece sem cursor.
401unauthorizedChave ausente, malformada, inexistente, revogada ou expirada — ou a requisição trouxe cookie de sessão. O motivo nunca é detalhado.
403forbiddenA chave não tem o escopo exigido pela rota.
403module_not_contractedA empresa não contratou o módulo do recurso; o corpo traz o slug em `module` (ex.: recrutamento-selecao).
403access_blockedA conta da empresa está bloqueada. Fale com o administrador.
404not_foundRota ou indicador inexistente na v1.
405method_not_allowedMétodo sem suporte na rota (ex.: GET em /v1/mcp, que só aceita POST).
429rate_limitedLimite estourado. Espere os segundos de Retry-After.
500internal_errorFalha nossa. Tente de novo; persistindo, abra um chamado com o X-Request-Id.
503database_unavailableIndisponibilidade momentânea. Tente de novo após Retry-After.

Toda resposta traz X-Request-Id: informe-o ao suporte.

LIMITES DE USO

300 requisições por minuto por chave

Cada chave tem 300 requisições por minuto; cada IP, 600. As respostas trazem X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset. Ao estourar: 429 rate_limited com Retry-After em segundos.

AGENTES E IA

Use a API dentro do seu assistente

Beta — acesso sob solicitaçãoMCP (Model Context Protocol) é o padrão que assistentes de IA usam para chamar ferramentas externas. O servidor MCP da PRIEZA expõe as mesmas listas da REST, só leitura, com a mesma chave, os mesmos escopos e o mesmo limite.

Endereço: https://api.prieza.app/v1/mcp (Streamable HTTP, sem sessão). Ferramentas: list_employees, list_departments, list_cost_centers, list_positions, list_branches, list_tickets, list_movements, list_admissions, list_jobs e get_indicators.

A saída do MCP é dado, não ordem: configure o seu agente para tratar o que as ferramentas devolvem como informação e nunca como instrução a executar.

Adicionar ao Claude

Registra o servidor no Claude Code com um comando; no Claude Desktop, use a configuração JSON abaixo.

claude mcp add --transport http prieza https://api.prieza.app/v1/mcp --header "Authorization: Bearer prz_live_SEU_PREFIXO_SEU_SEGREDO"
Adicionar ao Cursor

Abre o Cursor já com o servidor preenchido; troque o marcador pela sua chave antes de salvar.

Usar no ChatGPT e em outros clientes

Configuração padrão de servidor MCP remoto com o cabeçalho da chave, para colar no cliente que aceitar cabeçalhos.

{
  "mcpServers": {
    "prieza": {
      "url": "https://api.prieza.app/v1/mcp",
      "headers": {
        "Authorization": "Bearer prz_live_SEU_PREFIXO_SEU_SEGREDO"
      }
    }
  }
}
Skill para agentes

Arquivo SKILL.md com autenticação, escopos, paginação, erros, limites e exemplos, para o agente consultar antes de chamar a API.

Nunca cole a chave num chat: ela vai só no cabeçalho Authorization da configuração do cliente.

CHANGELOG

Mudanças da API

1.0.0-beta · 2026-10-31
  • Colaboradores e admissões passam a sair só com o vínculo profissional e o estado do processo: sem e-mail, nome social, código ERP nem dados do candidato. Campos novos: registration e termination_date (colaboradores), job_id (admissões); requester_employee_id e assignee_employee_id (chamados).
  • Validade obrigatória da chave (30, 90, 180 ou 365 dias), no máximo 2 chaves ativas por empresa e limites de 300 requisições por minuto por chave e 600 por IP.
  • Chaves gerenciadas em Configurador → Conexões → Chaves de API; bloquear, inativar ou excluir a empresa revoga as chaves.
  • Chamados sem título nem descrição e vagas sem descrição: a API não devolve texto livre.
  • Cursor amarrado à listagem: cursor de outra rota responde 400 invalid_cursor.
  • Módulo contratado: recurso de módulo que a empresa não contratou responde 403 module_not_contracted.
  • Servidor MCP somente leitura em /v1/mcp, com as mesmas consultas, escopos e limites da REST; lote JSON-RPC recusado com 400.
  • Primeira versão, somente leitura: colaboradores, departamentos, centros de custo, cargos, filiais, chamados, movimentações, admissões, vagas e o indicador de turnover.
  • Chave por empresa com escopos, limite por chave e paginação por cursor.

Mudanças incompatíveis só em uma nova versão (/v2), com aviso prévio.