Skip to main content

​
Table of contents

​
1. What is the Public API?

The Public API is a set of HTTP routes that allow external systems to integrate with Salú.
  • You make an HTTP request (for example, GET /v0/sector)
  • The API responds with data in JSON (lists, objects, etc.)
  • Access is protected with authentication (x-api-key header)

​
1.1. How company hierarchy works in Brazil (Branch / Sector / Position) — Occupational Health context

In Brazil, companies commonly organize employees using a simple three-level hierarchy: Branch (Unit / Worksite / Facility) → Sector (Area / Department) → Position (Job Role / Job Title) This structure is especially important in occupational health, because legal requirements (exposure risks, mandatory medical exams, surveillance programs, etc.) depend on where the employee works and what they do.

​
Branch (Unit / Worksite / Facility)

What it means: A physical or legal location where people work. Why it matters in occupational health: Different units can have completely different exposure profiles, even within the same company. Examples: São Paulo Office Rio de Janeiro Factory Belo Horizonte Warehouse The unit answers: “Where does the employee work?”

​
Sector (Area / Department)

What it means: A functional area inside a unit that groups people doing similar activities. Why it matters in occupational health: Two departments in the same building may involve very different risks (e.g., administration vs. maintenance vs. laboratory). Examples: Administration Production Maintenance Laboratory HR The department answers: “In which area do they work?”

​
Position (Job Role / Job Title)

What it means: The specific function the employee performs. Why it matters in occupational health: This is usually the most important layer for defining: occupational risks (noise, chemicals, biological exposure, ergonomics, etc.) required medical exams health surveillance rules Examples: Administrative Assistant Machine Operator Welder Nurse Forklift Driver The job role answers: “What does the employee do?”

​
Putting it all together

In Brazilian occupational health, requirements are typically defined by combining: Where the person works (Branch) + their work environment (Sector) + what they do (Position) Example: Two employees may work for the same company and even the same unit, but if they are in different departments and job roles, they may have completely different exposure risks and mandatory exams.

​
2. Environments: dev vs prd

There are two main environments:
  • dev → development / staging environment
  • prd → production environment (real data)
The dev environment is intended for tests and validations and may present instability, as it receives frequent updates and new functionality continuously. Therefore, we do not guarantee full (100%) availability in this environment. Additionally, the dev environment is available Monday to Friday, from 9:00 to 20:00 (local time).
Base URLs: 
https://public-api.salu.com.vc/dev/routes
https://public-api.salu.com.vc/prd/routes
We will refer to this as BASE_URL. Endpoints follow the pattern:
BASE_URL + path
For example, to list sectors: 
GET {BASE_URL}/v0/sector

​
3. What is the client_integration_code?

To make client integrations easier, we provide a string field called client_integration_code on some core entities — Branch, Sector, Position, and Employee. You can use this field to store your own internal identifier, allowing you to map records from your system to records in our platform. This makes integrations simpler, safer, and more traceable. Additionally, this same field is available in the list filters for these entities and can be used as a search parameter, which helps with data retrieval and synchronization during integrations.

​
4. Authentication and API Key

Most Public API routes require a header called x-api-key.

​
4.1. Important headers

  • x-api-key → required: identifies the client calling the API
Example headers: 
x-api-key: YOUR_API_KEY_HERE
If you do not send x-api-key, or if it is invalid/expired, the API will return an authentication error.

​
4.2. How to obtain your API Key

API Keys are managed by your organization in the Salú Portal. Typical flow:
  1. A user with the appropriate permissions accesses the Salú Portal.
  2. Navigate to Settings / Api Key.
  3. Click New Api.
  4. Provide a descriptive name for the key (e.g. erp-payroll-integration).
  5. Select the organizations the API will have access to, when applicable.
  6. The portal generates the key and displays the full value once.
  7. Copy the key and configure it in the system that will make the calls (backend, Postman, Insomnia, etc.).
Notes:
  • Store the key in a secure place (ideally a vault or environment variable).
  • If the key is exposed/compromised, revoke it and generate a new one in the portal.
  • You can have multiple active keys (for different systems or environments).
If you do not have access to the portal, ask someone on your team with admin permissions to generate the key.

​
4.3. Example curl request

Assuming you are using the dev environment: 
curl --request GET "https://public-api.salu.com.vc/dev/routes/v0/sector" \
  --header "Accept: application/json" \
  --header "x-api-key: YOUR_API_KEY_HERE"

​
4.4. Example of a creation (POST) with JSON body

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: YOUR_API_KEY_HERE" \
  --data '{
    "name": "Nursing",
    "is_active": true
  }'

​
5. How to navigate the documentation

On the left side of the site you will see some sections. The most important here are:
  • How to use → general API context
  • Endpoints → Salú Public API specific documentation
Within the Salú API section: In How to use you will find:
  • The Salú Public API overview page
In Endpoints you will find groups such as:
  • Branches
  • Positions
  • Sectors
  • Employees
  • Organizations
  • Pendencies

​
5.1. What each endpoint page shows

On an endpoint page (for example Public List Sectors) you will typically see:
  • Endpoint title
  • Method + path (e.g. GET /v0/sector)
  • A description of what the route does
  • Authentication info (e.g. x-api-key header)
  • Parameters:
    • Path parameters (e.g. :sector_id)
    • Query parameters (e.g. is_active, order_by)
    • Headers
  • Example request (usually curl)
  • Example response (JSON)
  • The API Playground, where you can test the route directly in the docs

​
6. How to test an endpoint in practice

You have two main options:
  1. Use the API Playground in the documentation
  2. Use tools such as Postman, Insomnia or curl in your terminal

​
6.1. Testing via the API Playground

  1. Open the Public API section.
  2. Choose an endpoint (for example Public List Sectors).
  3. In the Playground header:
    • Confirm the server/environment (dev or prd).
  4. In Headers, set:
    • x-api-key → your key
  5. Fill in any parameters you want (query, path, etc.).
  6. Click Send.
  7. Inspect the JSON response in the response panel (status 200, 4xx, 5xx, etc.).
If an error occurs, check the response body — it usually contains JSON explaining the issue.

​
6.2. Testing with curl

Pattern: 
curl --request <METHOD> "<BASE_URL><PATH>" \
  --header "Accept: application/json" \
  --header "x-api-key: YOUR_API_KEY_HERE" \
  [--header "Content-Type: application/json" \
   --data '{"json": "if POST/PUT"}']
To list sectors in production: 
curl --request GET "https://public-api.salu.com.vc/prd/routes/v0/sector" \
  --header "Accept: application/json" \
  --header "x-api-key: YOUR_API_KEY_HERE"

​
7. Understanding common responses and errors

​
7.1. Success responses

  • 200 OK → request succeeded (e.g. list, fetch)
  • 201 Created → resource created successfully (on POST)
Typical response body example: 
{
  "data": [
    {
      "id": "sector-uuid",
      "name": "Nursing",
      "is_active": true
    }
  ]
}

​
7.2. Authentication errors

Typical cases: Missing or invalid API Key
  • Status: 401 or 403.
  • Possible responses:
{
  "status_code": 403,
  "errors": [
    {
      "error": "INVALID_APIKEY_ERROR",
      "detail": "The provided ApiKey is not valid."
    }
  ]
}
Check:
  • That the x-api-key header is being sent.
  • That there are no extra spaces/stray characters from copy-paste.
  • That you are using the correct key for the selected environment (dev vs prd).

​
7.3. Validation errors (422)

When a parameter is missing or invalid, you may see something like: 
{
  "detail": [
    {
      "type": "missing",
      "loc": [
        "body",
        "organization_id"
      ],
      "msg": "Field required",
      "input": {
        "name": "string",
        "description": "string",
        "hr_code": "string",
        "client_integration_code": "string"
      }
    }
  ]
}
This means the organization_id field, which is required, was not sent. In this case:
  • Check the docs for all required fields.
  • Fix and try again.

​
7.4. Server errors (5xx)

If you receive a 500 or similar error:
  1. Retry after a few seconds.
  2. If the issue persists, collect:
    • The endpoint called
    • Environment (dev or prd)
    • Approximate time
    • The error response body
  3. Send these details to Salú support.

​
7.5. Rate limiting (429)

The API enforces rate limiting per API key to ensure stability, security, and fair usage of the service. When the allowed number of calls within a given period is exceeded, the API returns HTTP 429 (Too Many Requests) with a response like: 
{
  "error": "Too many requests"
}
Policy:
  • Limit: 300 requests every 5 minutes
  • Criterion: combination of source IP + API key (x-api-key)
  • Scope: applied only to configured public routes
Behavior when exceeded:
  • When the limit is exceeded, the API key is temporarily blocked for approximately 5 minutes.
  • During this period, new requests receive a 429 response.
Recurrence and permanent blocking:
  • In cases of repeated abuse, the API key may be permanently blocked, preventing any further use of the credential.
This measure protects the infrastructure and ensures quality of service for all API consumers.

​
7.6. Not found (404) and bad request (400)

  • 404 Not Found → the requested resource does not exist (e.g., non-existent ID).
  • 400 Bad Request → the request is invalid (e.g., inconsistent parameter combination). Inspect the JSON body for details.

​
8. Pagination and sorting on list endpoints

Most list endpoints support pagination and sorting via query parameters. Example request: 
GET {BASE_URL}/v0/RESOURCE?order_by=created_at&order_dir=asc&page=0&limit=20
Supported parameters:
  • page → which page to fetch. If omitted, the default is 0.
  • limit → number of items per page. If omitted, the default is 20.
  • order_by → which field to sort by. The default is the creation date field (usually created_at). You may use another field present in the resource schema (e.g. name, updated_at, status, etc.) as long as that field exists in that resource’s payload.
  • order_dir → sort direction. Accepts asc (ascending) or desc (descending).
Example paginated response: 
{
  "data": [
    
  ],
  "cursor": {
    "total": 49,
    "page": 0,
    "page_size": 20,
    "total_pages": 3,
    "next_page": true
  }
}
Cursor fields meaning:
  • total → total number of records for the current filter.
  • page → current page (zero-based).
  • page_size → number of items returned per page.
  • total_pages → total number of available pages given the page_size.
  • next_page → whether there is a next page (true/false).
Notes:
  • If you don’t send page and limit, the defaults are used: page=0 and limit=20.
  • The order_by value depends on the resource fields. Check the specific endpoint’s schema/structure to see which fields are available.
  • Typically, order_by=created_at with order_dir=asc returns items from oldest to newest; with order_dir=desc, from newest to oldest.
Note: In some endpoints, page_size may appear as an alias for limit. When present, both have the same effect; we standardize on limit in this documentation.

​
9. Quick checklist

Before reporting a problem, verify:
  • Are you using the correct base URL (dev vs prd)?
  • Are you sending the x-api-key header?
  • Is the API Key for Salú Public API?
  • Did you fill mandatory parameters?
  • Did you read the error JSON (field detail)?
If you still need help, share these details with the Salú team — it speeds up troubleshooting.

​
10. Versioning, limits and best practices

  • Versioning: paths use the v0 prefix. Backward-incompatible changes will result in a new version (v1, v2, …). We will communicate breaking changes in advance.
  • Rate limiting: respect the limits informed in the documentation. On 429, implement retries with exponential backoff.
  • Timeouts: use reasonable client-side timeouts. Requests can fail due to transient unavailability.
  • Idempotency: for critical write operations, we recommend client-side idempotency (for example, avoiding sending the same command multiple times).
  • Security: HTTPS only. Do not share your x-api-key. Store it in vaults/environment variables.
  • Formats: JSON responses in UTF-8. Dates in ISO 8601; unless indicated otherwise, consider UTC timezone.

​
11. Support and changes

  • Support: when opening a ticket, include the endpoint, environment (dev/prd), approximate time, payload, and the full response (including status and relevant headers).
  • Changes and deprecations: follow announcements in the documentation. Deprecated endpoints will have a coexistence period whenever possible.