Primeros Pasos con la API, Autenticación y Respuestas

Centro de Documentación de la API

Siguiente →

Comienza aquí para autenticarte, realizar tu primera solicitud, interpretar las respuestas y consultar los metadatos del servidor.

En esta página

1. 1. Inicio Rápido

2. 2. Autenticación

3. 3. Convenciones de Respuesta

4. 5. Estado del Servicio y Autenticación

5. 6. Metadatos del Servidor

1. Inicio Rápido

export API_BASE="https://secure.timesheets.com/api/public/v1"
export API_KEY="YOUR_API_KEY"
export TOKEN="YOUR_JWT_TOKEN"

# Sin autenticación
curl -s "$API_BASE/health-check"

# Autenticación (administrador principal de una cuenta activa o de prueba)
curl -s -X POST "$API_BASE/auth/token" \
  -H "Content-Type: application/json" \
  -d '{"username":"admin@example.com","password":"secret"}'

# Solicitud autenticada (la mayoría de los endpoints)
curl -s "$API_BASE/users?Status=USER_STATUS_ACTIVE&MaxRows=10" \
  -H "Authorization: Bearer $TOKEN" \
  -H "apikey: $API_KEY"

2. Autenticación

1. Llama a POST /auth/token con el nombre de usuario y la contraseña (sin necesidad de un token previo).

2. Recibe apikey, token y, opcionalmente, auth_headers.

3. Envía tanto apikey como Authorization: Bearer <token> en las solicitudes posteriores (excepto en los endpoints del reloj, que solo requieren la apikey).

Solo los administradores principales de cuentas activas o de prueba pueden obtener credenciales de la API. Las claves tienen un límite de solicitudes (5 solicitudes por cada 60 segundos de forma predeterminada, a menos que estén incluidas en la lista de excepciones). Superar este límite devuelve el código HTTP 420.

curl -s -X POST "$API_BASE/auth/token" \
  -H "Content-Type: application/json" \
  -d '{"username":"admin@example.com","password":"secret"}'

{
  "apikey": "abc123...",
  "token": "eyJhbGciOi...",
  "auth_headers": {
    "apikey": "abc123...",
    "Authorization": "Bearer eyJhbGciOi..."
  }
}

Consulta las claves activas del usuario actual:

curl -s "$API_BASE/auth/token" \
  -H "Authorization: Bearer $TOKEN" \
  -H "apikey: $API_KEY"

3. Convenciones de Respuesta

La mayoría de los endpoints devuelven HTTP 200 incluso cuando fallan las validaciones o las reglas de negocio. Siempre revisa el cuerpo de la respuesta:

{
  "errors": [],
  "data": {}
}

Excepciones y variantes:

• GET /health-check devuelve { "status": "ok!", "timestamp": ... } (sin la estructura que contiene errors).

• Las respuestas de los turnos del reloj utilizan una estructura ligeramente diferente (error en lugar de errors en algunas rutas).

• Los recibos de gastos devuelven Msg / MsgType / Data del servicio de informes.

• Algunos endpoints de informes devuelven estructuras de respuesta del servicio de informes en lugar de la estructura genérica {errors,data}.

Los endpoints de asignación (clientes, proyectos y códigos de cuenta) permiten agregar o eliminar asignaciones, no reemplazar la lista completa. Los ID no válidos o de solo lectura provocan que toda la solicitud por lotes falle.

Las solicitudes DELETE no tienen cuerpo. Envía las listas de ID como parámetros de consulta en los endpoints de colecciones o inclúyelos en la ruta de los endpoints de elementos individuales.

5. Estado del Servicio y Autenticación

GET /health-check

No requiere autenticación. Utilízalo para comprobar la disponibilidad del servicio.

curl -s "$API_BASE/health-check"
# {"status":"ok!","timestamp":"..."}

POST /auth/token / GET /auth/token

Consulta la sección 2. Autenticación.

6. Metadatos del Servidor

GET /server/constants

Devuelve las constantes de la aplicación agrupadas por categoría (estados de usuario, tipos de acceso, códigos de nómina, estados de registros, etc.). Es útil para identificar los valores de las enumeraciones utilizadas como filtros en los endpoints de listas e informes.

curl -s "$API_BASE/server/constants" \
  -H "Authorization: Bearer $TOKEN" \
  -H "apikey: $API_KEY"

GET /server/timezones

curl -s "$API_BASE/server/timezones" \
  -H "Authorization: Bearer $TOKEN" \
  -H "apikey: $API_KEY"

Utiliza los ID de zonas horarias de esta lista cuando llames a POST /user.

Centro de Documentación de la API

Siguiente →