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.
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.
Sua primeira chamada
- 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.
- A chave aparece uma única vez: guarde-a num cofre de segredos.
- Envie a chave no cabeçalho
Authorizationde cada requisição.
curl -s "https://api.prieza.app/v1/employees?limit=50" \
-H "Authorization: Bearer $PRIEZA_API_KEY"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.
Cada chave só lê o que precisa
| Escopo | Rotas | Dados |
|---|---|---|
employees:read | GET /v1/employees | Colaboradores: só o vínculo profissional (matrícula, cargo, estrutura, datas) |
org:read | GET /v1/departmentsGET /v1/cost-centersGET /v1/positionsGET /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/indicatorsGET /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.
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);Corpo único: { error }
| HTTP | error | Quando |
|---|---|---|
| 400 | invalid_request | Parâmetro fora do contrato (ex.: limit fora de 1 a 100). |
| 400 | invalid_cursor | Cursor alterado ou de outra listagem. Recomece sem cursor. |
| 401 | unauthorized | Chave ausente, malformada, inexistente, revogada ou expirada — ou a requisição trouxe cookie de sessão. O motivo nunca é detalhado. |
| 403 | forbidden | A chave não tem o escopo exigido pela rota. |
| 403 | module_not_contracted | A empresa não contratou o módulo do recurso; o corpo traz o slug em `module` (ex.: recrutamento-selecao). |
| 403 | access_blocked | A conta da empresa está bloqueada. Fale com o administrador. |
| 404 | not_found | Rota ou indicador inexistente na v1. |
| 405 | method_not_allowed | Método sem suporte na rota (ex.: GET em /v1/mcp, que só aceita POST). |
| 429 | rate_limited | Limite estourado. Espere os segundos de Retry-After. |
| 500 | internal_error | Falha nossa. Tente de novo; persistindo, abra um chamado com o X-Request-Id. |
| 503 | database_unavailable | Indisponibilidade momentânea. Tente de novo após Retry-After. |
Toda resposta traz X-Request-Id: informe-o ao suporte.
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.
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.
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"Abre o Cursor já com o servidor preenchido; troque o marcador pela sua chave antes de salvar.
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"
}
}
}
}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.
Mudanças da API
- 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.