​

Como usar a API pública da Salú

1. O que é a Public API
2. Diferença entre ambientes (dev e prd)
3. Como conseguir e usar a sua API Key (x-api-key)
4. Como navegar na documentação (abas, endpoints, exemplos)
5. Como testar uma rota usando o API Playground e curl
6. Como interpretar as respostas e erros mais comuns

​

1. O que é a Public API?

• 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)

​

2. Ambientes: dev x prd

• dev → ambiente de desenvolvimento/homologação
• prd → ambiente de produção (dados reais)

https://public-api.salu.com.vc/dev/routes
https://public-api.salu.com.vc/prd/routes

BASE_URL + path

GET {BASE_URL}/v0/sector

​

3. Autenticação e API Key

​

3.1. Cabeçalhos importantes

• x-api-key → obrigatório: identifica o cliente que está chamando a API

x-api-key: SUA_API_KEY_AQUI

​

3.2. Como conseguir sua API Key

1. Um usuário com permissão adequada acessa o Portal Salú.
2. Navega até a área de Integrações / Public API (nome pode variar ligeiramente).
3. Clica em Criar nova API Key.
4. Informa um nome descritivo para a chave (ex.: erp-integracao-folha) e, se aplicável, escolhe o ambiente/escopo.
5. O portal gera a chave e exibe uma única vez o valor completo.
6. A empresa copia essa chave e configura no sistema que fará as chamadas (backend, integração, Postman, Insomnia etc.).

• Guarde a chave em um lugar seguro (idealmente em um vault ou variável de ambiente).
• Se a chave for exposta/comprometida, você pode revogar e gerar uma nova pelo próprio portal.
• Você pode ter múltiplas chaves ativas, por exemplo, uma por sistema ou por ambiente interno.

​

3.3. Exemplo de requisição com curl

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. Como navegar na documentação

• API reference → exemplos genéricos
• Public API → documentação específica da API pública da Salú

• A página de visão geral da Public API
• (Opcionalmente) links para páginas de visão geral ou guias

• Branches (Unidades)
• Positions (Cargos)
• Sectors (Setores)
• Employees (Colaboradores)
• Organizations (Organizações)

​

4.1. O que cada página de endpoint mostra

• 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

​

5. Como testar uma rota na prática

1. Usar o API Playground da própria doc
2. Usar ferramentas como Postman, Insomnia ou curl no terminal

​

5.1. Testando pelo API Playground

1. Acesse a aba Public API.
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.).

​

5.2. Testando com curl

curl --request <MÉTODO> "<BASE_URL><PATH>"   --header "Accept: application/json"   --header "x-api-key: SUA_API_KEY_AQUI"   [--data '{"json":"se for POST/PUT"}']

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"

​

6. Entendendo respostas e erros comuns

​

6.1. Respostas de sucesso

• 200 OK → requisição deu certo (ex.: listagem, busca, etc.).
• 201 Created → algo foi criado com sucesso (em rotas POST).

{
  "data": [
    {
      "id": "uuid-do-setor",
      "name": "Enfermagem",
      "is_active": true
    }
  ]
}

​

6.2. Erros de autenticação

• Status: 401 ou 403.
• Possíveis mensagens:

{
  "detail": "Not authenticated"
}

{
  "detail": "Invalid API key"
}

• 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).

​

6.3. Erros de validação (422)

{
  "detail": [
    {
      "loc": ["query", "order_by"],
      "msg": "value is not a valid enumeration member",
      "type": "type_error.enum"
    }
  ]
}

• Veja em Parameters na doc quais valores são aceitos (order_by, order_dir, etc.).
• Ajuste e tente novamente.

​

6.4. Erros internos (5xx)

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. Checklist rápido

• Estou usando a URL base correta (dev x prd)?
• Estou enviando o header x-api-key?
• A API Key é realmente a da Public API da Salú?
• Preenchi todos os parâmetros obrigatórios?
• Li a mensagem do erro JSON (campo detail)?