> ## Documentation Index
> Fetch the complete documentation index at: https://docs.filexpress.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Asistencia

> Enviar marcaciones desde relojes biométricos o aplicaciones y consultarlas

**Permiso requerido:** `hr.attendances`

La asistencia registrada alimenta la planilla: al generarla, el gestor revisa las inasistencias y horas extra detectadas y decide cuáles aplicar.

## Enviar marcaciones

```http theme={null}
POST /hr/attendances
```

Registra hasta **500 marcaciones** por solicitud. Cada registro es un empleado en un día.

```json theme={null}
{
  "records": [
    { "document_number": "01234567-8", "date": "2026-10-01", "check_in": "08:02", "check_out": "17:05" },
    { "employee_id": "uuid", "date": "2026-10-01", "check_in": "07:55", "check_out": "18:30", "notes": "Cierre de mes" },
    { "document_number": "98765432-1", "date": "2026-10-01", "check_in": "08:10" }
  ]
}
```

| Campo | Requerido | Descripción |
| - | - | - |
| `employee_id` | Uno de los dos | ID del empleado en FileXpress. |
| `document_number` | Uno de los dos | Número de documento del empleado (se ignoran guiones y espacios). Ideal para relojes biométricos. |
| `date` | Sí | Fecha (`YYYY-MM-DD`). |
| `check_in` | No | Hora de entrada (`HH:MM`, 24 h). |
| `check_out` | No | Hora de salida. Debe ser posterior a la entrada. |
| `notes` | No | Observaciones (máx. 500 caracteres). |

**Comportamiento**

* **Idempotente**: si ya existe un registro del empleado para esa fecha, se actualiza. Reenviar el mismo lote no duplica.
* Puedes enviar primero la entrada y más tarde la salida del mismo día: los campos omitidos conservan el valor anterior.
* Cada registro se procesa por separado: un error no detiene el resto del lote.

**Respuesta `200`**

```json theme={null}
{
  "status": true,
  "data": {
    "created": 2,
    "updated": 0,
    "failed": 1,
    "results": [
      { "index": 0, "status": "created", "id": "uuid", "employee_id": "uuid" },
      { "index": 1, "status": "created", "id": "uuid", "employee_id": "uuid" },
      { "index": 2, "status": "error", "message": "Employee not found (send a valid employee_id or document_number)." }
    ]
  }
}
```

`index` corresponde a la posición del registro en `records`. Si **todos** los registros fallan, la respuesta tiene código `422`.

## Consultar asistencia

```http theme={null}
GET /hr/attendances?start_date=2026-10-01&end_date=2026-10-15
```

| Parámetro | Requerido | Descripción |
| - | - | - |
| `start_date` | Sí | Fecha inicial. |
| `end_date` | Sí | Fecha final (máximo 93 días de rango). |
| `employee_id` | No | Filtra por empleado. |

```json theme={null}
{
  "status": true,
  "data": [
    {
      "id": "uuid",
      "employee_id": "uuid",
      "employee_name": "María López",
      "document_number": "01234567-8",
      "date": "2026-10-01",
      "check_in": "08:02",
      "check_out": "17:05",
      "notes": null
    }
  ]
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.