# Listar (/docs/developers/api-reference/job-positions/list)

## Descripcion general [#descripcion-general]

Este endpoint permite obtener un listado paginado de los puestos pertenecientes a tu organización. Los resultados se devuelven en formato JSON e incluyen metadatos de paginación. Los puestos eliminados se excluyen automáticamente. El tamaño de página es fijo en 20 resultados.

Las bandas salariales (`salary_band_min`, `salary_band_max`) se serializan como **strings decimales** (por ejemplo `"15000.00"`) para preservar la precisión.

## Endpoint [#endpoint]

`GET https://app.integranom.com/api/v1/job-positions`

## Consulta multiples puestos [#consulta-multiples-puestos]

***

## Query params [#query-params]

| Parametro | Tipo                  | Requerido | Default | Descripcion                                           |
| --------- | --------------------- | --------- | ------- | ----------------------------------------------------- |
| `page`    | integer ≥ 1           | No        | 1       | Página solicitada. El tamaño de página es fijo en 20. |
| `active`  | `"true"` \| `"false"` | No        | -       | Filtra por el flag `is_active`.                       |

**cURL**

```bash
curl -X GET "https://app.integranom.com/api/v1/job-positions" \
-H "Authorization: Bearer TU_API_KEY" \
-H "Content-Type: application/json"
```

**Respuesta**

```json
{
"count": 24,
"page": 1,
"page_size": 20,
"total_pages": 2,
"next": "https://app.integranom.com/api/v1/job-positions?page=2",
"previous": null,
"results": [
  {
    "id": "ck...",
    "job_position_number": 1,
    "name": "Gerente de Ventas",
    "code": "GER-VEN",
    "description": "Gerencia comercial",
    "salary_band_min": "15000.00",
    "salary_band_max": "35000.00",
    "is_active": true,
    "sort_order": 0,
    "created_at": "2026-05-24T10:00:00.000Z",
    "updated_at": "2026-05-24T10:00:00.000Z"
  }
]
}
```

## Consulta un puesto especifico [#consulta-un-puesto-especifico]

***

Se puede buscar un puesto particular por su número, nombre o código. Los tres filtros hacen coincidencia exacta sin distinguir mayúsculas y minúsculas: el nombre y el código se almacenan en mayúsculas y el filtro se compara también en mayúsculas.

## Query params [#query-params-1]

| Parametro             | Tipo    | Requerido | Default | Descripcion                                          |
| --------------------- | ------- | --------- | ------- | ---------------------------------------------------- |
| `job_position_number` | integer | No        | -       | Filtra por número de puesto exacto.                  |
| `name`                | string  | No        | -       | Filtra por nombre exacto.                            |
| `code`                | string  | No        | -       | Filtra por código exacto (almacenado en mayúsculas). |

**cURL**

```bash
curl -X GET "https://app.integranom.com/api/v1/job-positions?job_position_number=1" \
-H "Authorization: Bearer TU_API_KEY" \
-H "Content-Type: application/json"
```

**Respuesta**

```json
{
"count": 1,
"page": 1,
"page_size": 20,
"total_pages": 1,
"next": null,
"previous": null,
"results": [
  {
    "id": "ck...",
    "job_position_number": 1,
    "name": "Gerente de Ventas",
    "code": "GER-VEN",
    "description": "Gerencia comercial",
    "salary_band_min": "15000.00",
    "salary_band_max": "35000.00",
    "is_active": true,
    "sort_order": 0,
    "created_at": "2026-05-24T10:00:00.000Z",
    "updated_at": "2026-05-24T10:00:00.000Z"
  }
]
}
```

## Errores [#errores]

| Status | Causa                                               |
| ------ | --------------------------------------------------- |
| `400`  | Valor inválido en `job_position_number` o `active`. |
| `401`  | API key ausente o inválida.                         |
| `403`  | La API key no tiene el permiso `getJobPositions`.   |