Fichar la entrada de un empleado

Registra el inicio de la jornada de un empleado y abre un nuevo tramo de trabajo. - employee_id y source (web/mobile) son obligatorios; occurred_at por defecto es ahora. - Falla si ya has fichado la entrada, o fuera del periodo de contratación: 422 business_rule_violation (clocking_outside_employment_period). - Un empleado dado de baja es de solo lectura y no puede fichar la entrada, ni siquiera el día de su baja: 422 business_rule_violation (employee_inactive).

Registra los días que trabajó con un fichaje manual. - Devuelve 201 con la entrada clock_in.

Authorization

AuthorizationBearer <token>

Tu API key como token Bearer: fact_live_… en producción, fact_test_… en sandbox. Consulta la guía de autenticación.

En: header

Parámetros de ruta

company*string

Identificador público (UUID v7) de la empresa. Obtenlo de GET /v1/me (data.scope[].id).

Formatouuid

Headers

Idempotency-Key?string

Clave opaca generada por el cliente (hasta 255 caracteres; se recomienda UUID v7) que hace seguros los reintentos: la primera respuesta se cachea y se reproduce en las repeticiones sin volver a ejecutar la mutación. Reutilizar una clave con un cuerpo distinto devuelve 422 idempotency_key_reused; los valores de los campos secretos (password, secret…) cuentan como parte del cuerpo, así que reintentar con un secreto corregido bajo la misma clave es una petición distinta, nunca la repetición de la respuesta anterior. Consulta la guía de idempotencia.

Longitud1 <= length <= 255

Factuarea-Version?string

Fija la versión de la API (YYYY-MM-DD, versionado por fecha estilo Stripe) para esta petición; omítelo para usar la versión fijada de la clave, o la última si no hay ninguna. Versión no soportada → 400 unsupported_api_version; malformada → 400 parameter_invalid_format. La versión efectiva se refleja en la cabecera de respuesta Factuarea-Version. Consulta la guía de Versioning.

Formatodate

Cuerpo de la petición

application/json

Definiciones de TypeScript

Usa el tipo request body en TypeScript.

employee_id*string

ID del empleado (UUID v7) que ficha (entrada o salida).

Formatouuid

source*string

Origen del fichaje: web o mobile.

Valor en"web" | "mobile"

occurred_at?|

Marca de tiempo del fichaje en ISO 8601 (por defecto, el instante del servidor).

Formatodate-time

Cuerpo de la respuesta

`application/json`

Ejemplo de petición

const apiKey = process.env.FACTUAREA_API_KEY;if (!apiKey) throw new Error("Set FACTUAREA_API_KEY");const response = await fetch("https://api.factuarea.com/v1/companies/01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01/time-entries/clock-in", {  method: "POST",  headers: { Authorization: `Bearer ${apiKey}`, ...{"Accept":"application/json","Content-Type":"application/json","Idempotency-Key":"erp-2026-public-api-v1-time_entries-clock_in"} },  body: JSON.stringify({  "employee_id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b01",  "source": "web",  "occurred_at": "2026-06-01T09:00:00+02:00"}),});if (!response.ok) throw new Error(await response.text());if (response.status !== 204) console.log(await response.json());

Ejemplo de respuesta

{
  "data": {
    "id": "01933a21-ae43-7d5f-9b6c-3c4d5e6f7a01",
    "object": "time_entry",
    "employee_id": "01933a1f-8c21-7b3d-9e4f-1a2b3c4d5e01",
    "entry_type": "clock_in",
    "occurred_at": "2026-05-04T09:00:00Z",
    "recorded_at": "2026-05-04T09:00:01Z",
    "source": "web",
    "is_retroactive": false,
    "reason": null,
    "created_at": "2026-05-04T09:00:01Z"
  }
}

Se envió la cabecera X-Active-Profile retirada

{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_unknown",
    "subcode": "retired_active_profile_header",
    "message": "La cabecera 'X-Active-Profile' fue retirada de la API v1: la empresa efectiva se indica en el segmento de empresa de la ruta.",
    "param": "X-Active-Profile",
    "doc_url": "https://docs.factuarea.com/guides/errors#parameter_unknown",
    "request_id": "req_01J8Y3M2Q40000000000000001"
  }
}

Cabecera Factuarea-Version malformada

{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_invalid_format",
    "message": "El header 'Factuarea-Version' debe tener formato YYYY-MM-DD.",
    "param": "Factuarea-Version",
    "doc_url": "https://docs.factuarea.com/guides/errors#parameter_invalid_format",
    "request_id": "req_01J8Y3M2Q40000000000000002"
  }
}

Factuarea-Version no admitida

{
  "error": {
    "type": "invalid_request_error",
    "code": "unsupported_api_version",
    "message": "La versión de API '2020-01-01' no está soportada.",
    "param": "Factuarea-Version",
    "doc_url": "https://docs.factuarea.com/guides/errors#unsupported_api_version",
    "request_id": "req_01J8Y3M2Q40000000000000003"
  }
}

{
  "error": {
    "type": "authentication_error",
    "code": "missing_api_key",
    "message": "Falta header Authorization o X-API-Key.",
    "doc_url": "https://docs.factuarea.com/guides/errors#missing_api_key",
    "request_id": "req_6bd71be6209bfa22ca0525caa1"
  }
}

POST /v1/companies/{company}/time-entries/clock-in · 403 insufficient_scope

{
  "error": {
    "type": "authorization_error",
    "code": "insufficient_scope",
    "message": "Esta operación requiere el scope 'time_entries:write'. Tu API key solo tiene los scopes: ninguno.",
    "doc_url": "https://docs.factuarea.com/guides/errors#insufficient_scope",
    "request_id": "req_d86c9f0028ebdd3f72741a9e79"
  }
}

Empresa desactivada

{
  "error": {
    "type": "authorization_error",
    "code": "company_inactive",
    "message": "Esta empresa está desactivada. Actívala para operar.",
    "param": "company",
    "doc_url": "https://docs.factuarea.com/guides/errors#company_inactive",
    "request_id": "req_01J8Y3M2Q40000000000000005"
  }
}

Recurso no encontrado

{
  "error": {
    "type": "not_found_error",
    "code": "resource_not_found",
    "message": "El recurso solicitado no existe o pertenece a otra empresa.",
    "param": null,
    "doc_url": "https://docs.factuarea.com/guides/errors#resource_not_found",
    "request_id": "req_01HKQS5NEQ6X1R4N9B0C5DWTPG"
  }
}

Empresa no encontrada o fuera del alcance de la API key

{
  "error": {
    "type": "not_found_error",
    "code": "profile_not_found",
    "message": "La empresa indicada no existe o no está en el ámbito de tu credencial.",
    "param": "company",
    "doc_url": "https://docs.factuarea.com/guides/errors#profile_not_found",
    "request_id": "req_01J8Y3M2Q40000000000000004"
  }
}

{
  "error": {
    "type": "conflict_error",
    "code": "resource_conflict",
    "message": "Hay otra operación reservando identificadores sobre 'time_record_ledger' en este momento y no ha podido completarse la reserva. Vuelve a intentarlo dentro de unos segundos; la operación es reintentable y no ha dejado nada a medias.",
    "doc_url": "https://docs.factuarea.com/guides/errors#resource_conflict",
    "request_id": "req_01J8Y3M2Q4CF0000000000IDR1"
  }
}

POST /v1/companies/{company}/time-entries/clock-in · 422 invalid_param_value

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_param_value",
    "message": "El campo employee_id es obligatorio.",
    "param": "employee_id",
    "errors": [
      {
        "param": "employee_id",
        "code": "parameter_missing",
        "message": "El campo employee_id es obligatorio."
      }
    ],
    "doc_url": "https://docs.factuarea.com/guides/errors#invalid_param_value",
    "request_id": "req_cee477cde416d62dc780fe4ecb"
  }
}

POST /v1/companies/{company}/time-entries/clock-in · 422 clocking_outside_employment_period

{
  "error": {
    "type": "invalid_request_error",
    "code": "business_rule_violation",
    "subcode": "clocking_outside_employment_period",
    "message": "No se puede fichar el 04/05/2026: el empleado está de alta desde el 11/05/2026.",
    "param": "occurred_at",
    "doc_url": "https://docs.factuarea.com/guides/errors#business_rule_violation",
    "request_id": "req_209714de530a8e58600cae3c45"
  }
}

POST /v1/companies/{company}/time-entries/clock-in · 422 employee_inactive

{
  "error": {
    "type": "invalid_request_error",
    "code": "business_rule_violation",
    "subcode": "employee_inactive",
    "message": "El empleado está de baja y no puede fichar la entrada. Si sigue trabajando, reactívalo antes.",
    "param": "employee_id",
    "doc_url": "https://docs.factuarea.com/guides/errors#business_rule_violation",
    "request_id": "req_5e0c1a7b93d24f68a1b2c3d4e5"
  }
}

POST /v1/companies/{company}/time-entries/clock-in · 422 already_clocked_in

{
  "error": {
    "type": "invalid_request_error",
    "code": "business_rule_violation",
    "subcode": "already_clocked_in",
    "message": "Ya has fichado la entrada.",
    "doc_url": "https://docs.factuarea.com/guides/errors#business_rule_violation",
    "request_id": "req_64299e2ed8bf4fa8fe6eb856c0"
  }
}

Idempotency key reutilizada con un payload distinto

{
  "error": {
    "type": "idempotency_error",
    "code": "idempotency_key_reused",
    "message": "La Idempotency-Key 'order-2026-0001' ya se usó con un payload distinto.",
    "param": "Idempotency-Key",
    "doc_url": "https://docs.factuarea.com/guides/errors#idempotency_key_reused",
    "request_id": "req_01J8Y3M2Q40000000000000007"
  }
}

Formato de Idempotency-Key no válido

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_param_format",
    "message": "La Idempotency-Key debe tener entre 1 y 255 caracteres ASCII printable.",
    "param": "Idempotency-Key",
    "doc_url": "https://docs.factuarea.com/guides/errors#invalid_param_format",
    "request_id": "req_01J8Y3M2Q40000000000000008"
  }
}

{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "message": "Has excedido el límite de requests permitido. Reintenta más tarde.",
    "doc_url": "https://docs.factuarea.com/guides/errors#rate_limit_exceeded",
    "request_id": "req_67815acef219e468f9c99dd122"
  }
}

{
  "error": {
    "type": "api_error",
    "code": "internal_error",
    "message": "Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.",
    "doc_url": "https://docs.factuarea.com/guides/errors#internal_error",
    "request_id": "req_cfb1867806df65a3d6e81a7ab7"
  }
}

Fichar la entrada de un empleado

Authorization

Parámetros de ruta

Headers

Cuerpo de la petición

Cuerpo de la respuesta

201application/json

400application/json

401application/json

403application/json

404application/json

409application/json

422application/json

429application/json

500application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`