Skip to main content

​
Sumário

​
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: 
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: 
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: 
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: 
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

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 Endpoints.
  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: 
curl --request <MÉTODO> "<BASE_URL><PATH>" \
  --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: 
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: 
{
  "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:
{
  "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: 
{
  "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: 
{
  "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 é: 
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: 
{
  "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.