---
name: prieza-api
description: Use para ler dados de RH de uma empresa na PRIEZA (colaboradores, departamentos, centros de custo, cargos, filiais, chamados, movimentações, admissões, vagas e indicador de turnover) pela API pública v1 somente leitura, com chave de empresa, escopos, paginação por cursor e limites de uso. Cobre REST e o servidor MCP.
---

# PRIEZA — API pública v1 (beta, acesso sob solicitação)

API REST **somente leitura** da PRIEZA (RH Gestão). A empresa vem da chave: nenhuma rota recebe o
identificador da empresa. Respostas em JSON, campos em `snake_case`.

- Base: `https://api.prieza.app/v1`
- Contrato OpenAPI 3.1: https://www.prieza.app/openapi/v1.json
- Portal: https://www.prieza.app/desenvolvedores
- MCP: `https://api.prieza.app/v1/mcp`

## Autenticação

Envie a chave no cabeçalho de toda requisição:

```
Authorization: Bearer prz_live_<prefixo>_<segredo>
```

A chave é criada pelo administrador da empresa em Configurador → Conexões → Chaves de API, com
validade obrigatória de 30, 90, 180 ou 365 dias (no máximo 2 chaves ativas por empresa), e aparece
uma única vez. Chave vencida ou revogada responde 401: peça uma nova ao admin. Nunca a coloque em URL, log, código versionado ou resposta ao usuário.
Requisição com cookie de navegador é recusada (a API é servidor a servidor).

## Escopos

| Escopo            | Rotas                                                                      | Ferramenta MCP                                                             |
| ----------------- | -------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
| `employees:read`  | `GET /v1/employees`                                                        | `list_employees`                                                           |
| `org:read`        | `GET /v1/departments`, `/v1/cost-centers`, `/v1/positions`, `/v1/branches` | `list_departments`, `list_cost_centers`, `list_positions`, `list_branches` |
| `tickets:read`    | `GET /v1/tickets`                                                          | `list_tickets`                                                             |
| `movements:read`  | `GET /v1/movements`                                                        | `list_movements`                                                           |
| `admissions:read` | `GET /v1/admissions`                                                       | `list_admissions`                                                          |
| `jobs:read`       | `GET /v1/jobs`                                                             | `list_jobs`                                                                |
| `indicators:read` | `GET /v1/indicators`, `GET /v1/indicators/{slug}`                          | `get_indicators`                                                           |

Regra da API: **não exibir dados dos usuários nem salários**. Colaborador sai só com o vínculo
profissional (`id`, `name`, `registration`, `status`, `admission_date`, `termination_date` e os ids
de cargo, departamento, centro de custo e filial); admissão sai só com etapa, datas e `job_id`;
chamado sai sem título nem descrição, com o solicitante só por `requester_employee_id`; vaga sai
sem descrição nem faixa salarial. 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 de chamados, conteúdo de movimentações e
movimentações de promoção, ação salarial e desligamento. Não tente obtê-los por outra rota.

## Módulo contratado

Além do escopo, cada recurso exige que a empresa tenha contratado o módulo dele: `gente-gestao`
(colaboradores, estrutura, chamados, movimentações), `recrutamento-selecao` (admissões, vagas) e
`dashboards-bi` (indicadores). Sem o módulo a resposta é `403` com
`{ "error": "module_not_contracted", "module": "<slug>" }`. Não insista: o contrato é da empresa.

## Paginação por cursor

Toda lista responde `{ "data": [...], "next_cursor": "..." | null }`. Parâmetros: `limit` (1 a
100, padrão 50) e `cursor`. Repita com `cursor=<next_cursor>` até vir `null`. O cursor é opaco:
não monte nem altere, e use cada cursor só na listagem que o devolveu (cursor alterado ou de outra
rota = `400 invalid_cursor`).

## Erros

Corpo sempre `{ "error": "<código>" }`.

| HTTP | `error`                                   | O que fazer                                                                  |
| ---- | ----------------------------------------- | ---------------------------------------------------------------------------- |
| 400  | `invalid_request` / `invalid_cursor`      | Corrija o parâmetro; recomece a listagem sem cursor.                         |
| 401  | `unauthorized`                            | Chave ausente, inválida, revogada ou expirada. Peça uma chave nova ao admin. |
| 403  | `forbidden`                               | A chave não tem o escopo da rota.                                            |
| 403  | `module_not_contracted`                   | A empresa não contratou o módulo (`module` no corpo).                        |
| 403  | `access_blocked`                          | Conta da empresa bloqueada. Não insista.                                     |
| 404  | `not_found`                               | Rota ou indicador fora da v1.                                                |
| 405  | `method_not_allowed`                      | Método sem suporte (ex.: GET em `/v1/mcp`).                                  |
| 429  | `rate_limited`                            | Espere `Retry-After` segundos antes de tentar de novo.                       |
| 5xx  | `internal_error` / `database_unavailable` | Tente de novo com espera; informe o `X-Request-Id`.                          |

## Limites

300 requisições por minuto por chave (todas as rotas e o MCP somam no mesmo balde) e 600 por
IP. Cabeçalhos `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`. Ao receber 429,
respeite `Retry-After`; nunca dispare em paralelo para "furar" o limite.

## Exemplos

```bash
# 1. Primeira página de colaboradores
curl -s "https://api.prieza.app/v1/employees?limit=50" \
  -H "Authorization: Bearer $PRIEZA_API_KEY"

# 2. Página seguinte da MESMA listagem (next_cursor da resposta anterior de /v1/employees)
curl -s "https://api.prieza.app/v1/employees?limit=50&cursor=$NEXT_CURSOR" \
  -H "Authorization: Bearer $PRIEZA_API_KEY"

# 3. Indicador de turnover da empresa
curl -s "https://api.prieza.app/v1/indicators/turnover" \
  -H "Authorization: Bearer $PRIEZA_API_KEY"
```

## MCP × REST

- **MCP** (`POST https://api.prieza.app/v1/mcp`, Streamable HTTP, sem sessão): quando você é um
  assistente conectado como cliente MCP e quer consultar sob demanda, ferramenta por ferramenta.
  Mesma chave no cabeçalho `Authorization`, mesmos escopos (`tools/list` só mostra o permitido),
  mesmos módulos (ferramenta de módulo não contratado aparece na lista e o `tools/call` dá 403),
  mesmos dados e mesmo limite. Uma mensagem JSON-RPC por requisição: lote (array) = `400`.
- **REST**: para sincronizar listas inteiras (laços de paginação), integrações em lote, BI e
  scripts. Prefira REST quando precisar de todas as páginas.

Nas duas portas a API é somente leitura: não existe ferramenta nem rota de escrita na v1.
