Documentación de la API

Shifton Tareas permite automatizar el trabajo con la plataforma y conectarla a servicios externos a través de una API abierta. Mediante la API están disponibles todas las entidades clave —tareas, clientes, empleados, listas de comprobación, inventario, zonas de servicio, documentos de Documentos financieros e informes—, por lo que Shifton se puede enlazar con sus sistemas de RR. HH., cálculo de nóminas y analítica, así como con los servicios internos de la empresa.

La documentación está publicada en dos versiones:

🚀 Nueva documentación — la versión actual del manual, con la estructura renovada y los últimos métodos: 👉 https://api2.shifton.com/openapi/
📄 Documentación antigua — la versión anterior (que se sigue manteniendo para las integraciones existentes): 👉 https://api2.shifton.com/docs/

Ambas versiones se pueden abrir directamente desde la aplicación: en el apartado Developer, en la pestaña Resumen, con los botones «Nueva documentación» y «Documentación antigua».

La documentación está disponible en dos idiomas. En la esquina superior derecha de la página de la nueva documentación hay un conmutador EN / RU: el idioma elegido se recuerda.

Cómo obtener una clave de API

La clave de API se crea en la propia aplicación:

Abra el apartado Developer.
Vaya a la pestaña Claves de API («Claves de API»).
Pulse «Crear clave API».

Qué rellenar al crear la clave

Se abrirá el panel lateral Crear clave API con los siguientes campos:

título — nombre de la clave, campo obligatorio. Póngale un nombre según su finalidad, para que después quede claro qué desactivar: «Exportación a 1C», «Informes para analítica».
Expira a las — fecha a partir de la cual la clave dejará de funcionar. Si deja el campo vacío, la validez será ilimitada.
Acceso — alcance de los permisos de la clave:
Full access (act as me) — la clave funciona en su nombre y con sus permisos.
Permisos restringidos — un conjunto limitado de permisos que usted mismo elige.

Pulse Agregar para crear la clave, o Cancelar para cerrar el panel.

📷 *Captura del panel de creación de la clave — hacer en producción*

La clave se crea para una empresa concreta y funciona solo con sus datos. La clave se puede revocar en cualquier momento: la revocación surte efecto de inmediato y todas las peticiones posteriores con esa clave devolverán el error 401.

Importante: la clave creada se muestra una sola vez. Cópiela enseguida y guárdela en un lugar seguro: no es posible volver a obtenerla. Si pierde la clave, cree una nueva y revoque la antigua.

Autorización

Todas las peticiones a la API se firman con la clave en la cabecera:

Authorization: Bearer {your_API_key}

Dirección base de la API:

https://api2.shifton.com/work/1.0.0

Una petición sin una clave válida devuelve 401 y el cuerpo {"message":"Unauthenticated."}.

Primera petición

Por ejemplo, para obtener la lista de empleados de la empresa (ponga el ID de su empresa en lugar de {companyId}):

GET https://api2.shifton.com/work/1.0.0/companies/{companyId}/employees
Authorization: Bearer {your_API_key}
Accept: application/json

Lo mismo mediante curl:

curl -H "Authorization: Bearer {your_API_key}" \
     -H "Accept: application/json" \
     https://api2.shifton.com/work/1.0.0/companies/{companyId}/employees

El ID de la empresa se ve en la barra de direcciones de la aplicación: app.shifton.com/c/8397/..., es decir, el número que sigue a /c/.

Qué está disponible a través de la API

El manual abarca más de 360 métodos. Apartados principales para el servicio de campo:

Tareas — /companies/{companyId}/tasks: creación, modificación, estados y archivos de las tareas.
Lista de tareas pendientes (To Do) — /companies/{companyId}/todo.
Clientes — /companies/{companyId}/clients, así como direcciones y campos personalizados de los clientes.
Listas de comprobación — /companies/{companyId}/checklists.
Zonas de servicio — /companies/{companyId}/tasks/service-areas.
Habilidades — /companies/{companyId}/skills.
Empleados — /companies/{companyId}/employees: alta, edición, baja y restauración.
Inventario — artículos, categorías, conjuntos y existencias en los almacenes.
Documentos financieros — presupuestos, órdenes de trabajo, facturas, recibos, contadores de documentos y logotipo.
Informes — exportación de datos de trabajo y de asistencia.

Además, están disponibles los horarios y los turnos, las vacaciones y las solicitudes de días libres, la asistencia, la facturación y la facturación por SMS, las notificaciones y los módulos.

Webhooks

Si en lugar de consultar la API periódicamente necesita recibir los eventos en el momento en que se producen, utilice los webhooks: pestaña Webhooks del apartado Developer. Shifton enviará por su cuenta una petición a su dirección cuando se produzca el evento correspondiente; la lista de eventos admitidos la devuelve un método aparte.

Códigos de error

La API de Shifton utiliza los códigos de estado HTTP estándar:

200 — la petición se ha ejecutado correctamente.
201 — el objeto se ha creado correctamente.
400 — parámetros de la petición incorrectos.
401 — error de autorización: la clave no se ha enviado, no es válida o ha sido revocada.
403 — acceso denegado.
404 — recurso no encontrado (lo más habitual es una errata en la dirección del método).
500 — error del servidor.

Consejos de uso

Para las integraciones nuevas utilice la nueva documentación: la antigua se mantiene para las integraciones que ya están en funcionamiento.
Para comprobar las peticiones resultan cómodos Postman o curl, que permiten ver la respuesta sin escribir una sola línea de código.
No guarde la clave en texto plano dentro del código ni la comparta con terceros: la clave da acceso a los datos de la empresa.
Respete los límites de frecuencia de peticiones (rate limits): superarlos puede provocar un bloqueo temporal del acceso a la API.

Preguntas frecuentes

Pregunta: ¿Dónde se obtiene una clave de API? Respuesta: En la aplicación: apartado Developer → pestaña Claves de API → botón «Crear clave API». La clave se emite para la empresa actual.

Pregunta: He cerrado la ventana y no he copiado la clave. ¿Dónde la veo? Respuesta: En ningún sitio: la clave se muestra una sola vez y no se vuelve a emitir. Cree una clave nueva y revoque la antigua.

Pregunta: ¿Cómo se revoca una clave si ha caído en malas manos? Respuesta: Elimínela en la pestaña Claves de API. La revocación surte efecto de inmediato: todas las peticiones con esa clave empezarán a devolver 401.

Pregunta: ¿En qué se diferencian «Full access» y «Restricted permissions»? Respuesta: Full access (act as me) otorga a la clave los mismos permisos que tiene usted. Permisos restringidos permite darle a la clave solo el conjunto de permisos elegido: es más seguro para una integración que solo necesita acceder a una parte de los datos.

Pregunta: ¿Se puede limitar la validez de la clave? Respuesta: Sí, con el campo Expira a las al crearla. Si no se rellena, la clave será indefinida.

Pregunta: ¿Una misma clave sirve para varias empresas? Respuesta: No. La clave está vinculada a la empresa en la que se ha creado y funciona solo con sus datos. Para otra empresa, cree una clave aparte.

Pregunta: ¿Cuál es la dirección base de la API? Respuesta: https://api2.shifton.com/work/1.0.0. A continuación va la ruta del método, por ejemplo /companies/{companyId}/tasks.

Pregunta: ¿Dónde se obtiene el ID de la empresa para las peticiones? Respuesta: Está en la barra de direcciones de la aplicación, justo después de /c/: por ejemplo, en app.shifton.com/c/8397/tasks el identificador de la empresa es 8397.

Pregunta: ¿Qué versión de la documentación debo usar? Respuesta: Para las integraciones nuevas, la nueva (api2.shifton.com/openapi). La antigua (api2.shifton.com/docs) se mantiene para las integraciones existentes.

Pregunta: ¿Hay documentación en ruso? Respuesta: Sí. En la página de la nueva documentación, en la esquina superior derecha, hay un conmutador EN / RU.

Pregunta: ¿Con qué se pueden probar las peticiones a la API? Respuesta: Lo más cómodo es Postman o curl, que permiten enviar peticiones y ver las respuestas sin escribir código.

Pregunta: ¿Por qué recibo un 401 si he copiado la clave? Respuesta: Compruebe que la clave se envía en la cabecera Authorization con la palabra Bearer delante, que no ha sido revocada y que no ha caducado.

Pregunta: ¿Por qué recibo un 404? Respuesta: Lo más habitual es que la dirección sea incorrecta: la parte base debe ser https://api2.shifton.com/work/1.0.0 y, en la ruta del método, el {companyId} correcto.

Pregunta: ¿Qué se puede automatizar mediante la API? Respuesta: La creación y modificación de tareas, el trabajo con los clientes y sus direcciones, las listas de comprobación, las zonas de servicio, las habilidades, los empleados, el inventario, los documentos de Documentos financieros y la exportación de informes, así como los horarios, los turnos y las vacaciones.

Pregunta: ¿Se pueden recibir eventos de Shifton en lugar de sondear la API? Respuesta: Sí, para eso están los webhooks: pestaña Webhooks del apartado Developer.

Pregunta: ¿El cambio de contraseña afecta al funcionamiento de la integración? Respuesta: No. Las integraciones funcionan con la clave de API, no con la contraseña de la cuenta.