Visión general de la API REST
La API de timum permite a los desarrolladores integrar de forma totalmente programática la reserva de citas en su plataforma como solución de marca blanca.
Base URL
Todas las solicitudes de la API se envían a la siguiente URL base:
https://www.timum.deHTTPS obligatorio:
Autenticación
Todas las solicitudes de la API deben autenticarse con su clave de API. La clave se transmite en el encabezado HTTP X-TIMUM-CLIENT-ID:
curl -X GET "https://www.timum.de/crms/{crmId}/resources" \
-H "X-TIMUM-CLIENT-ID: your-api-key" \
-H "Content-Type: application/json"Obtención de la clave de API
Recibirá su clave de API (también llamada "directUseSecret") de timum al configurar su integración. La clave está vinculada a su ID de CRM y permite el acceso a todos los recursos dentro de su contexto de CRM.
ID de CRM:
Formato de referencia
timum utiliza un formato de referencia unificado para identificar entidades de forma inequívoca. Las referencias constan de dos partes separadas por @:
{uniqueId}@{platformName}
Beispiele:
- 12345@yourCrmUser (User-Referenz)
- abc-def-123@yourCrmAccount (Account-Referenz)
- property-42@yourCrmResource (Ressourcen-Referenz)Componentes
| Parte | Descripción |
|---|---|
uniqueId | El ID con el que gestiona esta entidad en su sistema |
platformName | Su sufijo de plataforma, acordado durante la integración (p. ej., "yourCrm", "is24") |
Almacenamiento de referencias:
Áreas de la API
La API está estructurada por casos de uso:
1. Configuración inicial – Initial Setup
Users, Accounts, Providers, Staff - crear la estructura básica
2. Configuración – Configure Offerings
Resources, Products, Contact Profiles - definir la oferta
3. Planificación de citas – Scheduling
Timeslots, Appointments, Participations, Customers
4. Reserva – Booking Flow
Endpoints orientados al consumidor para la reserva de citas
Formato de respuesta
Todas las respuestas de la API están en formato JSON. Cada respuesta incluye un objeto api-info con información de versión:
{
"api-info": {
"version": "1"
},
"user": {
"reference": "12345@yourCrm",
"email": "max@example.com",
"username": "maxmustermann",
"firstName": "Max",
"lastName": "Mustermann",
"phone": null,
"mobile": null
}
}Respuesta de error
En caso de errores, la respuesta contiene un array errors con códigos de error y mensajes:
{
"api-info": {
"version": "1"
},
"errors": [
{
"errorCode": "201",
"message": "Das überlappt mit einem anderen Termin."
}
]
}HTTP Status Codes
| Código | Significado | Situación típica |
|---|---|---|
200 | OK | Solicitud correcta, entidad existente devuelta |
201 | Created | Nueva entidad creada correctamente |
202 | Accepted | Actualización aceptada correctamente |
204 | No Content | Correcto, pero sin datos que devolver (p. ej., cliente no encontrado) |
400 | Bad Request | Falta un campo obligatorio, formato no válido, referencia incorrecta |
404 | Not Found | La entidad referenciada no existe |
409 | Conflict | Duplicado detectado (p. ej., correo electrónico o nombre de usuario ya en uso) |
412 | Precondition Failed | Cita ya reservada, capacidad agotada |
Códigos de error comunes
| errorCode | Significado |
|---|---|
201 | Solapamiento temporal con una cita existente |
CORS
La API admite Cross-Origin Resource Sharing (CORS) para integraciones basadas en navegador. Las solicitudes preflight se responden automáticamente.
Access-Control-Allow-Credentials: true
Access-Control-Allow-Methods: POST, GET, OPTIONS, PUT, DELETE
Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Authorization, X-Auth-TokenPróximos pasos
- Initial Setup - Empiece creando Users y Accounts
- Configure Offerings - Defina los recursos y productos
- Scheduling - Cree disponibilidades y citas
- Booking Flow - Integre la reserva de citas