> ## Documentation Index > Fetch the complete documentation index at: https://docs.salu.com.vc/llms.txt > Use this file to discover all available pages before exploring further. # Como usar *** ## Sumário * [1. O que é a API Salú?](#pt-1) * [1.1. Como funciona a hierarquia de empresas no Brasil (Unidade / Setor / Cargo) — Contexto de Saúde Ocupacional](#pt-1-1) * [2. Ambientes: dev x prd](#pt-2) * [3. O que é o client\_integration\_code?](#pt-3) * [4. Autenticação e API Key](#pt-4) * [4.1. Cabeçalhos importantes](#pt-4-1) * [4.2. Como conseguir sua API Key](#pt-4-2) * [4.3. Exemplo de requisição com curl](#pt-4-3) * [4.4. Exemplo de criação (POST) com corpo JSON](#pt-4-4) * [5. Como navegar na documentação](#pt-5) * [5.1. O que cada página de endpoint mostra](#pt-5-1) * [6. Como testar uma rota na prática](#pt-6) * [6.1. Testando pelo API Playground](#pt-6-1) * [6.2. Testando com curl](#pt-6-2) * [7. Entendendo respostas e erros comuns](#pt-7) * [7.1. Respostas de sucesso](#pt-7-1) * [7.2. Erros de autenticação](#pt-7-2) * [7.3. Erros de validação (422)](#pt-7-3) * [7.4. Erros internos (5xx)](#pt-7-4) * [7.5. Limite de requisições (429)](#pt-7-5) * [7.6. Recurso não encontrado (404) e requisição inválida (400)](#pt-7-6) * [8. Paginação e ordenação dos endpoints](#pt-8) * [9. Checklist rápido](#pt-9) * [10. Versionamento, limites e boas práticas](#pt-10) * [11. Suporte e mudanças](#pt-11) *** ## 1. O que é a API Salú? A API Salú é um conjunto de **rotas HTTP** que permitem integrar sistemas externos com a Salú. * Você faz uma requisição HTTP (por exemplo, `GET /v0/sector`) * A API responde com dados em **JSON** (listas, objetos, etc.) * Tudo é protegido por autenticação (`x-api-key` no header) ## 1.1. Como funciona a hierarquia de empresas no Brasil (Unidade / Departamento / Cargo) — Contexto de Saúde Ocupacional No Brasil, as empresas geralmente organizam seus funcionários usando uma hierarquia simples de três níveis: Unidade (Filial / Local de Trabalho / Instalação) → Setor (Área / Departamento) → Cargo (Posição / Título do Cargo) Esta estrutura é especialmente importante na saúde ocupacional, pois os requisitos legais (riscos de exposição, exames médicos obrigatórios, programas de vigilância, etc.) dependem de onde o funcionário trabalha e do que ele faz. ### Unidade (Filial / Local de Trabalho / Instalação) **O que significa:** Um local físico ou legal onde as pessoas trabalham. **Por que é importante na saúde ocupacional:** Diferentes unidades podem ter perfis de exposição completamente distintos, mesmo dentro da mesma empresa. **Exemplos:** Escritório de São Paulo Fábrica do Rio de Janeiro Armazém de Belo Horizonte A unidade responde: “Onde o funcionário trabalha?” ### Setor (Área / Departamento) **O que significa:** Uma área funcional dentro de uma unidade que agrupa pessoas realizando atividades semelhantes. **Por que é importante na saúde ocupacional:** Dois departamentos no mesmo prédio podem envolver riscos muito diferentes (por exemplo, administração vs. manutenção vs. laboratório). **Exemplos:** Administração Produção Manutenção Laboratório RH O departamento responde: “Em qual área eles trabalham?” ### Cargo (Posição / Título do Cargo) **O que significa:** A função específica que o funcionário desempenha. **Por que é importante na saúde ocupacional:** Esta é geralmente a camada mais importante para definir: riscos ocupacionais (ruído, produtos químicos, exposição biológica, ergonomia, etc.) exames médicos necessários regras de vigilância da saúde **Exemplos:** Assistente Administrativo Operador de Máquina Soldador Enfermeiro Motorista de Empilhadeira O cargo responde: “O que o funcionário faz?” ### Juntando tudo Na saúde ocupacional brasileira, os requisitos são tipicamente definidos combinando: Onde a pessoa trabalha (Unidade) + seu ambiente de trabalho (Setor) + o que ela faz (Cargo) **Exemplo:** Dois funcionários podem trabalhar para a mesma empresa e até na mesma unidade, mas se estiverem em diferentes departamentos e cargos, podem ter riscos de exposição e exames obrigatórios completamente distintos. *** ## 2. Ambientes: `dev` x `prd` Existem dois ambientes principais: * **dev** → ambiente de desenvolvimento/homologação * **prd** → ambiente de produção (dados reais) O ambiente de dev é destinado a testes e validações e, por esse motivo, pode apresentar instabilidades, uma vez que recebe atualizações frequentes e a introdução contínua de novas funcionalidades. Dessa forma, não garantimos disponibilidade integral (100%) nesse ambiente. Além disso, o ambiente de dev encontra-se disponível de segunda a sexta-feira, das 9h às 20h. As URLs base são: ```text theme={null} https://public-api.salu.com.vc/dev/routes https://public-api.salu.com.vc/prd/routes ``` Chamaremos isso de **`BASE_URL`**. Os endpoints seguem o padrão: > **`BASE_URL` + `path`** Exemplo para listar setores: ```http theme={null} GET {BASE_URL}/v0/sector ``` *** ## 3. O que é o client\_integration\_code? Para facilitar a integração por parte dos clientes, disponibilizamos um campo do tipo string em algumas entidades principais — Unidade (Branch), Setor (Sector), Cargo (Position) e Colaborador (Employee). Esse campo pode ser utilizado para armazenar um identificador interno do cliente, permitindo o mapeamento entre os registros do seu sistema e os registros da nossa plataforma, tornando as integrações mais simples, seguras e rastreáveis. Além disso, esse mesmo campo está disponível nos filtros de listagem dessas entidades, podendo ser utilizado como parâmetro de busca, o que facilita a recuperação e o sincronismo dos dados durante as integrações. *** ## 4. Autenticação e API Key A maioria das rotas da API Salú exige um header chamado **`x-api-key`**. ### 4.1. Cabeçalhos importantes * `x-api-key` → **obrigatório**: identifica o cliente que está chamando a API Exemplo de headers: ```text theme={null} x-api-key: SUA_API_KEY_AQUI ``` Se você **não** enviar a `x-api-key`, ou se ela estiver **inválida/expirada**, a API responderá com erro de autenticação. ### 4.2. Como conseguir sua API Key As API Keys são gerenciadas pela sua organização no **Portal Salú**. Fluxo típico: 1. Um usuário com permissão adequada acessa o **Portal Salú**. 2. Navega até **Configurações / Api Key**. 3. Clica em **Nova Api**. 4. Informa um **nome descritivo** para a chave (ex.: `erp-integracao-folha`). 5. Seleciona as organizações que a Api terá acesso, caso seja aplicavel. 6. O portal gera a chave e exibe **uma única vez** o valor completo. 7. Copie a chave e configure no sistema que fará as chamadas (backend, Postman, Insomnia etc.). Observações: * Guarde a chave em um lugar seguro (idealmente em um **vault** ou variável de ambiente). * Se a chave for exposta/comprometida, **revogue** e gere **uma nova** no portal. * Você pode ter **múltiplas chaves ativas** (para diferentes sistemas ou ambientes). Se você não tem acesso ao portal, peça para alguém do seu time com perfil de admin gerar a chave. ### 4.3. Exemplo de requisição com `curl` Supondo que você esteja em **dev**: ```bash theme={null} curl --request GET "https://public-api.salu.com.vc/dev/routes/v0/sector" \ --header "Accept: application/json" \ --header "x-api-key: SUA_API_KEY_AQUI" ``` ### 4.4. Exemplo de criação (POST) com corpo JSON ```bash theme={null} curl --request POST "https://public-api.salu.com.vc/dev/routes/v0/sector" \ --header "Accept: application/json" \ --header "Content-Type: application/json" \ --header "x-api-key: SUA_API_KEY_AQUI" \ --data '{ "name": "Enfermagem", "is_active": true }' ``` *** ## 5. Como navegar na documentação Na lateral do site você verá algumas abas. As mais importantes aqui são: * **Como usar** → contexto geral da Api * **Endpoints** → documentação específica da API da Salú Dentro da aba **API Salú**: Em **Como usar** você encontra: * A página de visão geral da API Salú Em **Endpoints** você tem grupos como: * **Branches** (Unidades) * **Positions** (Cargos) * **Sectors** (Setores) * **Employees** (Colaboradores) * **Organizations** (Organizações) * **Pendencies** (Exames) ### 5.1. O que cada página de endpoint mostra Na página de um endpoint (por exemplo **Public List Sectors**) você sempre verá: * Título do endpoint * Método + path (ex.: `GET /v0/sector`) * Descrição do que a rota faz * Informações de autenticação (ex.: header `x-api-key`) * Parâmetros de: * **Path** (ex.: `:sector_id`) * **Query** (ex.: `is_active`, `order_by`) * **Headers** * Exemplo de requisição (geralmente em `curl`) * Exemplo de resposta (JSON) * O **API Playground**, onde você pode testar a rota direto na doc *** ## 6. Como testar uma rota na prática Você tem duas opções principais: 1. Usar o **API Playground** da própria doc 2. Usar ferramentas como **Postman**, **Insomnia** ou `curl` no terminal ### 6.1. Testando pelo API Playground 1. Acesse a aba **API Pública**. 2. Escolha um endpoint (por exemplo: **Public List Sectors**). 3. No topo do Playground: * Confirme o **servidor/ambiente** (dev ou prd). 4. Na seção de **Headers**, preencha: * `x-api-key` → sua chave pública. 5. Preencha os **parâmetros** que quiser (query, path, etc.). 6. Clique em **Send**. 7. Veja a resposta JSON no painel de resposta (status `200`, `4xx`, `5xx`, etc.). Se der erro, role a tela até o corpo da resposta – normalmente haverá um JSON explicando o problema. ### 6.2. Testando com `curl` Mesmo exemplo de antes, agora destacando o padrão: ```bash theme={null} curl --request "" \ --header "Accept: application/json" \ --header "x-api-key: SUA_API_KEY_AQUI" \ [--header "Content-Type: application/json" \ --data '{"json":"se for POST/PUT"}'] ``` Para listar setores em **produção**: ```bash theme={null} curl --request GET "https://public-api.salu.com.vc/prd/routes/v0/sector" --header "Accept: application/json" --header "x-api-key: SUA_API_KEY_AQUI" ``` *** ## 7. Entendendo respostas e erros comuns ### 7.1. Respostas de sucesso * `200 OK` → requisição deu certo (ex.: listagem, busca, etc.). * `201 Created` → algo foi criado com sucesso (em rotas `POST`). O corpo costuma ser um JSON, por exemplo: ```json theme={null} { "data": [ { "id": "uuid-do-setor", "name": "Enfermagem", "is_active": true } ] } ``` ### 7.2. Erros de autenticação Alguns exemplos típicos: **API Key ausente ou inválida** * Status: `401` ou `403`. * Possíveis mensagens: ```json theme={null} { "status_code": 403, "errors": [ { "error": "INVALID_APIKEY_ERROR", "detail": "A ApiKey informada não é válida." } ] } ``` Verifique: * Se o header `x-api-key` está sendo enviado. * Se não há espaços extras/copiar-e-colar com caracteres estranhos. * Se você está usando a chave certa para aquele ambiente (dev x prd). ### 7.3. Erros de validação (`422`) Quando algum parâmetro está errado ou faltando, você pode ver algo como: ```json theme={null} { "detail": [ { "type": "missing", "loc": [ "body", "organization_id" ], "msg": "Field required", "input": { "name": "string", "description": "string", "hr_code": "string", "client_integration_code": "string" } } ] } ``` Isso significa que o campo **organization\_id** que é um campo obrigatorio nao foi enviado. Nesse caso: * Confira na doc todos os campos obrigatorios. * Ajuste e tente novamente. ### 7.4. Erros internos (`5xx`) Se ocorrer algum erro `500` ou similar: 1. Tente novamente depois de alguns segundos. 2. Se persistir, anote: * Endpoint chamado. * Ambiente (dev ou prd). * Horário aproximado. * Corpo da resposta de erro. 3. Envie essas informações para o suporte da Salú. ### 7.5. Limite de requisições (`429`) A API aplica controle de taxa (rate limiting) por chave de API, com o objetivo de garantir estabilidade, segurança e uso justo do serviço. Quando o limite de chamadas permitido em um determinado período é excedido, a API retorna o código HTTP 429 (Too Many Requests), com a seguinte resposta: ```json theme={null} { "error": "Too many requests" } ``` **Política de Rate Limit** * Limite: 300 requisições a cada 5 minutos * Critério: combinação de IP de origem + chave de API (x-api-key) * Escopo: aplicado apenas às rotas públicas configuradas **Comportamento em caso de excesso** * Ao ultrapassar o limite, a chave de API é bloqueada temporariamente por aproximadamente 5 minutos. * Durante esse período, novas requisições receberão resposta 429. **Reincidência e bloqueio permanente** * Em casos de reincidência de abuso, a chave de API poderá ser bloqueada permanentemente, impedindo qualquer novo uso da credencial. Essa medida é aplicada para proteger a infraestrutura e garantir a qualidade do serviço para todos os consumidores da API. ### 7.6. Recurso não encontrado (`404`) e requisição inválida (`400`) * `404 Not Found` → o recurso solicitado não existe (ex.: ID inexistente). * `400 Bad Request` → a requisição é inválida (ex.: combinação de parâmetros inconsistente). Veja o corpo JSON para detalhes. ## 8. Paginação e ordenação dos endpoints A maioria dos endpoints de listagem suporta **paginação** e **ordenação** via query params. Um exemplo de requisição é: ```http theme={null} GET {BASE_URL}/v0/RECURSO?order_by=created_at&order_dir=asc&page=0&limit=20 ``` Parâmetros suportados: * `page` → página que você deseja buscar. Se não for enviado, o valor padrão é `0`. * `limit` → quantidade de itens por página. Se não for enviado, o padrão é `20`. * `order_by` → campo utilizado para ordenar os resultados. O padrão é o campo de **data de criação** (geralmente `created_at`). Você pode utilizar outro campo existente na estrutura do recurso que está consultando (por exemplo, `name`, `updated_at`, `status`, etc.), desde que esse campo exista no payload desse recurso. * `order_dir` → direção da ordenação. Aceita `asc` (crescente) ou `desc` (decrescente). Exemplo de resposta paginada: ```json theme={null} { "data": [ ], "cursor": { "total": 49, "page": 0, "page_size": 20, "total_pages": 3, "next_page": true } } ``` Significado dos campos do `cursor`: * `total` → total de registros no filtro atual. * `page` → página atual (base 0). * `page_size` → quantidade de itens retornados por página. * `total_pages` → total de páginas disponíveis considerando o `page_size`. * `next_page` → indica se existe uma próxima página (`true`/`false`). Observações: * Se você não enviar `page` e `limit`, serão usados os padrões: `page=0` e `limit=20`. * A escolha de `order_by` depende dos campos do recurso. Consulte o schema/estrutura retornada no endpoint específico para verificar os campos disponíveis. * Em geral, manter `order_by=created_at` com `order_dir=asc` retorna os itens do mais antigo para o mais recente; com `order_dir=desc`, do mais recente para o mais antigo. Nota: Em alguns endpoints, `page_size` pode aparecer como alias de `limit`. Quando presente, ambos têm o mesmo efeito; preferimos padronizar `limit` nesta documentação. *** ## 9. Checklist rápido Antes de reportar um problema, confira: * Estou usando a URL base correta (**dev x prd**)? * Estou enviando o header **`x-api-key`**? * A API Key é realmente a **API da Salú**? * Preenchi todos os **parâmetros obrigatórios**? * Li a mensagem do erro JSON (campo `detail`)? Se mesmo assim continuar difícil, compartilhe esses detalhes com o time da Salú – isso acelera muito a análise. *** ## 10. Versionamento, limites e boas práticas * Versionamento: os caminhos usam o prefixo `v0`. Mudanças incompatíveis resultarão em uma nova versão (`v1`, `v2`, ...). Comunicaremos breaking changes com antecedência. * Rate limiting: respeite os limites informados na documentação. Em caso de `429`, implemente retries com backoff exponencial. * Timeouts: utilize timeouts razoáveis no cliente. Requisições podem falhar por indisponibilidades transitórias. * Idempotência: para operações de escrita críticas, recomendamos idempotência no cliente (por exemplo, evitando reenvio múltiplo do mesmo comando). * Segurança: apenas HTTPS é aceito. Não compartilhe sua `x-api-key`. Armazene-a em cofres/variáveis de ambiente. * Formatos: respostas JSON em UTF-8. Datas em ISO 8601; salvo indicado, considere timezone UTC. *** ## 11. Suporte e mudanças * Suporte: ao abrir um chamado, inclua endpoint, ambiente (dev/prd), horário aproximado, payload e resposta completa (incluindo status e headers relevantes). * Mudanças e depreciações: acompanhe os avisos na documentação. Endpoints descontinuados terão período de convivência sempre que possível.