Integración domótica Parcel tracking (17TRACK, DHL), gratuita y de código abierto
Siga sus paquetes de todos los transportistas del mundo con 17TRACK y la API oficial de DHL.
Publicado por guim31
- Dispositivos
- Versión 1.0.1
- Requiere Gladys >=5.1.0
- ★ 0
Siga en Gladys sus paquetes de todos los transportistas, en su país y en el extranjero: Correos, SEUR, MRW, UPS, FedEx, DHL, GLS, DPD, los servicios postales de todo el mundo, los envíos desde China (Cainiao, YunExpress…) y más de 3.000 más, como las aplicaciones de seguimiento de paquetes.
Desarrollada sin cuenta de 17TRACK ni de DHL: sus comentarios son bienvenidos en el foro de Gladys. Las respuestas de ambas API se han simulado a partir de su documentación.
Para sus paquetes de La Poste, Colissimo y Chronopost, use mejor la integración
La Poste (guim31/gladys-laposte), que lee la API oficial de La Poste.
Esta integración no está afiliada a los transportistas ni a 17TRACK.
Qué hace la integración
- Usted añade un paquete por su número de seguimiento, y un nombre si lo desea («Zapatillas de correr»), desde la configuración o desde una escena. El transportista se reconoce a partir del número.
- Dos fuentes, cada una activada por su clave gratuita:
- DHL, por su API oficial, para los números de DHL y Deutsche Post;
- 17TRACK para todo lo demás: reconoce el transportista y reúne los pasos de todos los transportistas del trayecto (China Post y luego Correos, por ejemplo) en un solo historial.
- Cada paquete se convierte en un dispositivo en Gladys: estado, último paso, lugar, fecha, transportista y fecha de entrega prevista.
- El estado es el mismo para todos los transportistas: registrado, en tránsito, en reparto, para recoger, problema, entregado. El texto original del transportista (a menudo en inglés o alemán) sigue visible como detalle.
- El widget «Mis paquetes» lista sus paquetes, primero los que le esperan.
- Tres disparadores de escena (en reparto, entregado, un paquete requiere su atención) y tres acciones de escena (seguir un paquete, dejar de seguir un paquete, leer mis paquetes).
- Un paquete entregado se archiva solo al cabo de 7 días (ajustable).
Requisitos
- Gladys 5.1.0 o posterior, con acceso a Internet.
- Al menos una de las dos claves, ambas gratuitas:
- 17TRACK (todos los transportistas): cree una cuenta en api.17track.net y copie la clave en Settings → Security → Access key. Si activa la lista blanca de direcciones IP, añada la dirección pública de su router; si no, 17TRACK rechaza la clave.
- DHL (paquetes de DHL y Deutsche Post): cree una cuenta en developer.dhl.com, cree una aplicación con la API Shipment Tracking - Unified y copie su API Key (no el secreto).
- Las dos juntas dan el mejor resultado: DHL lee sus propios paquetes, 17TRACK el resto.
Configuración
Instale la integración desde Integraciones → Instalar desde GitHub con la dirección
https://github.com/guim31/gladys-colis y abra después su configuración.
| Ajuste | Por defecto | Función |
|---|---|---|
| Clave de API de 17TRACK | (vacío) | Su clave de 17TRACK. Nunca aparece en los registros. |
| Clave de API de DHL | (vacío) | La API Key de su aplicación DHL. Nunca aparece en los registros. |
| Conservar los paquetes entregados | 7 días | Un paquete entregado se archiva tras este tiempo (de 1 a 30 días). |
| Idioma | Francés | Idioma de los estados, de los nombres de funciones de los nuevos dispositivos y de los mensajes. |
Las acciones de la configuración:
- Seguir un paquete: el número de seguimiento (se admiten espacios, puntos y guiones) y un nombre opcional. El paquete se lee en el acto. El mismo número con otro nombre cambia el nombre del paquete. Cree después su dispositivo en la pestaña Descubrir.
- Dejar de seguir un paquete: por su nombre o su número. Su dispositivo sigue en Gladys: elimínelo desde la página del dispositivo.
- Leer los paquetes ahora: lee en el acto cada paquete en curso, comprueba las claves y muestra la cuota de 17TRACK restante y las consultas DHL usadas hoy.
Cuotas y ritmo de lectura
La integración lee cada paquete a un ritmo que sigue su estado, sin superar nunca los planes gratuitos:
| Estado | Lectura |
|---|---|
| En reparto | cada 15 minutos |
| En tránsito, problema | cada hora |
| Para recoger, aún desconocido | cada 2 horas |
| Registrado | cada 3 horas |
| Entregado | nunca más |
- DHL: el plan gratuito permite 250 consultas al día y una cada 5 segundos. La integración se detiene en 240 al día, espacia sus consultas 5 segundos y reduce el ritmo cuando muchos paquetes de DHL comparten el día (20 paquetes de DHL en tránsito: algo más de 2 horas entre dos lecturas). Hechas las 240 consultas, los paquetes de DHL esperan al día siguiente (medianoche UTC).
- 17TRACK: solo el registro de un número nuevo consume cuota, una vez por paquete; las lecturas siguientes son gratuitas y agrupadas (40 números por consulta, 3 consultas por segundo como máximo). El plan gratuito da un número limitado de registros: según el centro de ayuda de 17TRACK, 200 números concedidos una sola vez a las cuentas abiertas desde enero de 2026 (100 al mes en cuentas más antiguas). Consulte su panel de 17TRACK: la acción «Leer los paquetes ahora» muestra lo que queda. Un paquete archivado y seguido de nuevo no consume nada.
- 17TRACK consulta por su cuenta a los transportistas: justo después del registro, los primeros pasos pueden tardar unos minutos.
Los dispositivos
Un dispositivo por paquete, con el nombre del paquete («Zapatillas de correr (1Z999AA10123456784)»), que se crea en la pestaña Descubrir. Sus funciones, todas de solo lectura:
| Función | Contenido |
|---|---|
| Estado | Sin leer, Aún desconocido, Registrado, En tránsito, En reparto, Para recoger, Problema, Entregado |
| Último paso | El texto del transportista, tal como lo envía |
| Lugar | El lugar del último paso |
| Fecha del paso | Fecha y hora del último paso |
| Transportista | UPS, DHL Paket, Correos, Cainiao… |
| Entrega prevista | La fecha que anuncia el transportista, si existe |
Un guion (—) sustituye lo que el transportista no indica. Los nombres de las funciones toman el idioma elegido al crear el dispositivo.
Cuando el paquete se archiva, sale de la pestaña Descubrir, pero su dispositivo sigue en Gladys con sus últimos valores: elimínelo cuando ya no lo necesite (Gladys no permite que una integración elimine un dispositivo).
El widget
Añada el widget Mis paquetes a su panel. Lista hasta 8 paquetes: primero los que están en reparto, para recoger o con un problema, luego los demás. Cada línea da el nombre, el último paso con su fecha y una insignia de estado en color. Al tocarla se abre el detalle: transportista, número, fecha de entrega prevista, historial de pasos y un enlace a la página de seguimiento. Una línea al final avisa de una clave rechazada, una cuota alcanzada o un servicio que no responde.
Disparadores de escena
| Disparador | Cuándo |
|---|---|
| Un paquete está en reparto | El repartidor lleva el paquete en su ruta de hoy. |
| Un paquete se ha entregado | El transportista indica el paquete entregado (no para uno ya entregado al añadirlo). |
| Un paquete requiere su atención | El paquete espera en un punto de recogida o un casillero, o tiene un problema (entrega fallida, aduana, retraso, devolución). |
Cada disparador puede limitarse a un paquete (vacío: todos los paquetes). «Un paquete requiere su atención» puede limitarse también a un motivo: «Para recoger» o «Problema». La información que se pasa a las acciones de la escena: nombre del paquete, número, transportista, estado, último paso, lugar y página de seguimiento (y el motivo).
Un disparador se activa una vez por cambio de estado: un reinicio de Gladys o de la integración no lo vuelve a activar.
Acciones de escena
- Seguir un paquete: añade un paquete. El campo del número admite también un texto entero, como el asunto de un correo de confirmación de pedido: se usa el primer número de seguimiento que contiene. Resultados: número, nombre, estado, transportista y «Paquete nuevo» (1 o 0).
- Dejar de seguir un paquete: por su nombre o su número. Resultado «Quitado»: 1, o 0 si ningún paquete coincide.
- Leer mis paquetes: una frase como «Tiene 2 paquetes en curso: Zapatillas, en reparto hoy; Libro, esperando su recogida.», y los números de paquetes en curso, en reparto, para recoger y con un problema.
Ejemplos de escenas
- Llega el repartidor: disparador «Un paquete está en reparto», acción «Enviar un mensaje»: «El paquete {nombre del paquete} llega hoy ({transportista})». Añada una condición de presencia para avisar solo si no hay nadie en casa.
- Recordar el punto de recogida: disparador «Un paquete requiere su atención», motivo «Para recoger», y un mensaje «{nombre del paquete} le espera: {último paso}».
- Resumen de la mañana: disparador horario a las 8, acción «Leer mis paquetes», luego «Continuar solo si» paquetes en curso > 0, y un anuncio de voz de la frase.
- Seguimiento automático desde sus correos: con una integración de correo, pase el asunto del correo de envío a la acción «Seguir un paquete».
Solución de problemas
- «17TRACK rechaza la clave de API»: compruebe la clave (Settings → Security). Si la lista blanca de IP está activada en 17TRACK, añada la dirección pública de su router o desactívela.
- «DHL rechaza la clave de API»: copie la API Key de la aplicación (no el «API Secret») y compruebe que la aplicación tiene la API «Shipment Tracking - Unified».
- Un paquete sigue «Aún desconocido»: el remitente ha creado la etiqueta pero aún no ha entregado el paquete, o 17TRACK no reconoce el transportista. La integración vuelve a intentarlo y archiva el número a los 30 días.
- «Cuota de 17TRACK alcanzada»: no queda ningún registro gratuito en su cuenta; los paquetes ya en seguimiento se siguen leyendo. Quite los paquetes que ya no necesite.
- «Lecturas de DHL agotadas por hoy»: se han hecho las 240 consultas del día; los paquetes de DHL se reanudan a medianoche UTC.
- El dispositivo no muestra nada: créelo en la pestaña Descubrir y espere a la siguiente lectura o use «Leer los paquetes ahora».
- Para más detalles, ponga el nivel de registro en
debug(variableLOG_LEVEL=debug): cada lectura se describe allí, nunca con las claves.
Límites
- Desarrollada sin cuenta de 17TRACK ni de DHL: las respuestas se han simulado a partir de la documentación de ambas API. Se esperan los primeros comentarios reales.
- Los estados «En reparto» y «Para recoger» de DHL se deducen del texto del paso (inglés o alemán): una formulación nueva puede quedarse clasificada como «En tránsito».
- Los textos de los pasos se quedan en el idioma del transportista.
- Los disparadores siguen el ritmo de lectura: «en reparto» puede llegar hasta una hora después de que el repartidor recoja el paquete.
- 40 paquetes en seguimiento como máximo.
- UPS, FedEx y USPS también tienen API oficiales, pero piden una cuenta de empresa y una autenticación OAuth: estos transportistas pasan por 17TRACK.
- No se admiten los transportistas que exigen un código postal o un teléfono para el seguimiento.
Parámetros de configuración
Estos son los parámetros que Parcel tracking (17TRACK, DHL) te pide en su pantalla de configuración en Gladys.
| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| Sus claves de API gratuitas | section | No | Introduzca una clave de 17TRACK (todos los transportistas, detectados por el número), una de DHL o ambas. Use después «Seguir un paquete» y cree los dispositivos en la pestaña Descubrir. Para La Poste, use la integración La Poste. Sin relación con los transportistas ni con 17TRACK. |
| Clave de API de 17TRACK | secret | No | Settings → Security → Access key de su cuenta gratuita en api.17track.net. Todos los transportistas. |
| Clave de API de DHL | secret | No | La API Key de una aplicación «Shipment Tracking - Unified» en developer.dhl.com (gratuita, 250 consultas al día). |
| Conservar los paquetes entregados | select | No | Un paquete entregado se archiva tras este tiempo: sale de la lista, del widget y de la pestaña Descubrir. |
| Idioma | select | No | Idioma de los estados, de los nombres de las funciones de los nuevos dispositivos y de los mensajes. Los textos de los transportistas se quedan como los envían. |
Cómo instalar Parcel tracking (17TRACK, DHL) en Gladys
- En Gladys, abre Integraciones: Parcel tracking (17TRACK, DHL) aparece en el catálogo junto a las integraciones nativas, con una insignia de comunidad.
- Haz clic en Instalar. Gladys descarga la imagen Docker (
ghcr.io/guim31/gladys-colis:1.0.1), la ejecuta en un entorno aislado del núcleo y genera la interfaz de la integración (dispositivos, descubrimiento y configuración). - Abre la pantalla de Configuración de la integración, rellena los parámetros y guarda.
- También puedes instalarla directamente desde la URL de su repositorio: https://github.com/guim31/gladys-colis.
Parcel tracking (17TRACK, DHL) requiere Gladys >=5.1.0. El catálogo de Gladys se actualiza cada hora, así que una nueva versión está disponible como máximo una hora después de publicarse.
¿Todavía no usas Gladys? Es gratuito y de código abierto: sigue la guía de instalación para empezar.
Sobre las integraciones externas
Parcel tracking (17TRACK, DHL) es una integración externa: una integración comunitaria empaquetada como contenedor Docker y publicada en GitHub. Gladys la instala con un clic y la ejecuta en un entorno aislado del núcleo. La publica y mantiene guim31, no el equipo principal de Gladys.
- Explorar todas las integraciones, nativas y de la comunidad
- Crear y publicar tu propia integración externa
- Código fuente en GitHub — fuente de esta documentación