> ## 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.

# How to use

***

## Table of contents

* [1. What is the Public API?](#en-1)
* [1.1. How company hierarchy works in Brazil (Branch / Sector / Position) — Occupational Health context](#en-1-1)
* [2. Environments: dev vs prd](#en-2)
* [3. What is the client\_integration\_code?](#en-3)
* [4. Authentication and API Key](#en-4)
  * [4.1. Important headers](#en-4-1)
  * [4.2. How to obtain your API Key](#en-4-2)
  * [4.3. Example curl request](#en-4-3)
  * [4.4. Example of a creation (POST) with JSON body](#en-4-4)
* [5. How to navigate the documentation](#en-5)
  * [5.1. What each endpoint page shows](#en-5-1)
* [6. How to test an endpoint in practice](#en-6)
  * [6.1. Testing via the API Playground](#en-6-1)
  * [6.2. Testing with curl](#en-6-2)
* [7. Understanding common responses and errors](#en-7)
  * [7.1. Success responses](#en-7-1)
  * [7.2. Authentication errors](#en-7-2)
  * [7.3. Validation errors (422)](#en-7-3)
  * [7.4. Server errors (5xx)](#en-7-4)
  * [7.5. Rate limiting (429)](#en-7-5)
  * [7.6. Not found (404) and bad request (400)](#en-7-6)
* [8. Pagination and sorting on list endpoints](#en-8)
* [9. Quick checklist](#en-9)
* [10. Versioning, limits and best practices](#en-10)
* [11. Support and changes](#en-11)

***

<a id="en-1" />

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

<a id="en-1-1" />

## 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.

***

<a id="en-2" />

## 2. Environments: `dev` vs `prd`

There are two main environments:

* **dev** → development / staging environment
* **prd** → production environment (real data)

<Note>
  The <strong>dev</strong> environment is intended for tests and validations and may present instability, as it receives frequent updates and new functionality continuously.
  Therefore, we <strong>do not guarantee full (100%) availability</strong> in this environment.
  Additionally, the dev environment is available <strong>Monday to Friday, from 9:00 to 20:00 (local time)</strong>.
</Note>

Base URLs:

```text theme={null}
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:

```http theme={null}
GET {BASE_URL}/v0/sector
```

***

<a id="en-3" />

## 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.

***

<a id="en-4" />

## 4. Authentication and API Key

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

<a id="en-4-1" />

### 4.1. Important headers

* `x-api-key` → **required**: identifies the client calling the API

Example headers:

```text theme={null}
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.

<a id="en-4-2" />

### 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.

<a id="en-4-3" />

### 4.3. Example `curl` request

Assuming you are using the **dev** environment:

```bash theme={null}
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"
```

<a id="en-4-4" />

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

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

***

<a id="en-5" />

## 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**

<a id="en-5-1" />

### 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

***

<a id="en-6" />

## 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

<a id="en-6-1" />

### 6.1. Testing via the API Playground

1. Open the **API Pública** 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.

<a id="en-6-2" />

### 6.2. Testing with `curl`

Pattern:

```bash theme={null}
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**:

```bash theme={null}
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"
```

***

<a id="en-7" />

## 7. Understanding common responses and errors

<a id="en-7-1" />

### 7.1. Success responses

* `200 OK` → request succeeded (e.g. list, fetch)
* `201 Created` → resource created successfully (on `POST`)

Typical response body example:

```json theme={null}
{
  "data": [
    {
      "id": "sector-uuid",
      "name": "Nursing",
      "is_active": true
    }
  ]
}
```

***

<a id="en-7-2" />

### 7.2. Authentication errors

Typical cases:

**Missing or invalid API Key**

* Status: `401` or `403`.
* Possible responses:

```json theme={null}
{
  "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).

<a id="en-7-3" />

### 7.3. Validation errors (`422`)

When a parameter is missing or invalid, you may see something like:

```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"
      }
    }
  ]
}
```

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.

<a id="en-7-4" />

### 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.

<a id="en-7-5" />

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

```json theme={null}
{
  "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.

<a id="en-7-6" />

### 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.

<a id="en-8" />

## 8. Pagination and sorting on list endpoints

Most list endpoints support **pagination** and **sorting** via query parameters. Example request:

```http theme={null}
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:

```json theme={null}
{
  "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.

***

<a id="en-9" />

## 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.

***

<a id="en-10" />

## 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.

***

<a id="en-11" />

## 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.