Integración domótica La Poste, gratuita y de código abierto
Siga sus paquetes de La Poste, Colissimo y Chronopost en Gladys.
Publicado por guim31
- Dispositivos
- Versión 1.0.1
- Requiere Gladys >=5.1.0
- ★ 0
Siga sus paquetes de La Poste en Gladys: Colissimo, Chronopost y cartas certificadas con seguimiento («lettre suivie»), con la API oficial de seguimiento de La Poste («Suivi» v2).
Desarrollada sin el hardware (aquí: sin clave de API de La Poste): sus comentarios son bienvenidos en el foro de Gladys. Las respuestas de la API se simularon a partir de su documentación.
Qué hace la integración
- Usted añade un paquete con su número de seguimiento (y un nombre si lo desea), desde la configuración o desde una escena.
- La integración lee su estado en La Poste cada 30 minutos (ajustable) y se detiene una vez entregado.
- Un dispositivo «Paquetes La Poste» da los contadores (en curso, en reparto, para recoger, problemas, entregados recientemente) y una frase de resumen.
- El widget «Mis paquetes» enumera sus paquetes con su estado, su último paso y su fecha.
- Cuatro activadores de escena: en reparto, entregado, para recoger, problema. Dos acciones de escena: seguir un paquete, leer mis paquetes.
- Un paquete entregado sale solo de la lista al cabo de 7 días (ajustable).
Requisitos
- Gladys 5.1.0 o posterior.
- Una clave de API de La Poste, gratuita:
- cree una cuenta en developer.laposte.fr;
- abra la API Suivi y suscríbase a su plan gratuito;
- copie la clave de la suscripción (la
X-Okapi-Key, 64 caracteres).
- Gladys debe acceder a Internet (
api.laposte.fr).
Configuración
Instale la integración desde Integraciones → Instalar desde GitHub con la dirección
https://github.com/guim31/gladys-laposte y abra después su configuración.
| Ajuste | Por defecto | Función |
|---|---|---|
| Clave de API | (obligatoria) | La clave de su suscripción «Suivi». Nunca aparece en los registros. |
| Intervalo de lectura | 30 minutos | Con qué frecuencia se lee cada paquete en curso (de 15 minutos a 4 horas). Un entregado ya no se lee. |
| Conservar los paquetes entregados | 7 días | Un paquete entregado o devuelto sale de la lista tras este tiempo (de 1 a 30 días). |
| Idioma | Francés | Nombres de las funciones del nuevo dispositivo, idioma de los textos de La Poste, mensajes y frases. |
El estado de conexión de la pantalla de configuración indica si La Poste acepta la clave.
Acciones de la pantalla de configuración:
- Añadir un paquete: número de seguimiento (de 11 a 15 letras y cifras, se admiten espacios) y un nombre opcional. Un número ya seguido conserva su paquete y toma el nuevo nombre si indica uno. El paquete se lee en el acto.
- Quitar un paquete: por su nombre o su número.
- Leer los paquetes ahora: lee cada paquete en curso sin esperar al intervalo, y comprueba la clave.
El dispositivo
Cree el dispositivo Paquetes La Poste en la pestaña Descubrir. Es un solo dispositivo para todos sus paquetes: un paquete solo vive unos días, y un dispositivo por paquete dejaría un dispositivo muerto tras cada entrega.
| Función | Tipo | Contenido |
|---|---|---|
| Paquetes en curso | Contador | Paquetes aún no entregados |
| En reparto | Contador | Paquetes en la ruta de hoy del cartero o del repartidor |
| Para recoger | Contador | Paquetes que esperan en una oficina de correos o un punto de recogida |
| Problemas | Contador | Retrasados, retenidos en aduana, no entregables o devueltos al remitente |
| Entregados recientemente | Contador | Paquetes entregados que siguen en la lista |
| Resumen | Texto | «Tiene 2 paquetes en curso: Zapatos, en reparto; Libro, en tránsito.» |
Los contadores conservan su historial y sirven en las condiciones de escena.
El widget
Mis paquetes (Panel → Editar → añadir un widget de la integración) enumera hasta 8 paquetes, primero los que le necesitan (en reparto, para recoger, problema) y después los demás. Cada fila muestra el nombre, una insignia de estado, el último paso y su fecha. Al tocar se abre el detalle: transportista, número, fecha prevista o de entrega, punto de recogida, últimos pasos y un enlace a la página de seguimiento de laposte.fr. Una línea avisa cuando falta la clave o se rechaza, o cuando La Poste no responde.
Activadores de escena
| Activador | Cuándo |
|---|---|
| Un paquete está en reparto | El paquete está en la ruta de hoy |
| Un paquete se ha entregado | La Poste lo indica entregado (no para un paquete ya entregado al añadirlo) |
| Un paquete espera su recogida | Espera en una oficina de correos o un punto de recogida, tras una entrega fallida o por elección |
| Un paquete tiene un problema | Retraso, dirección incompleta, aduana, no entregable o devolución al remitente |
Cada activador se dispara una vez cuando el paquete entra en el estado, con estas variables: nombre del paquete, número de seguimiento, estado, último paso (texto de La Poste), transportista, punto de recogida, página de seguimiento.
Acciones de escena
- Seguir un paquete: añade un paquete a la lista. El campo del número admite también un texto entero, como el asunto de un correo: se usa su primer número de seguimiento. Salidas: número, nombre, estado, paquete nuevo (1 o 0). Sin número en el texto, la acción falla y la escena lo registra.
- Leer mis paquetes: da una frase con los paquetes en curso («Tiene 2 paquetes en curso: …») y el número de paquetes en curso, en reparto y para recoger.
Ejemplos de escenas
- Entrega hoy: activador «Un paquete está en reparto» → enviar un mensaje «… llega hoy», con la variable «Nombre del paquete» del activador.
- No olvidar la recogida: activador «Un paquete espera su recogida» → mensaje con el punto de recogida.
- Resumen matinal: cada día a las 8:00 → «Leer mis paquetes» → decir la frase en un altavoz, solo si «Paquetes en curso» es mayor que 0 (paso «Condición sobre variables»).
- Seguimiento desde los correos: con una integración que convierte los correos recibidos en activadores (IMAP), activador «correo recibido de Colissimo» → «Seguir un paquete» con el asunto del correo como número.
Solución de problemas
- «La Poste rechaza la clave de API»: compruebe que copió la clave de la suscripción «Suivi», sin espacios, y que la suscripción está activa en developer.laposte.fr. Las lecturas se reanudan en cuanto cambia la clave.
- Un paquete sigue «Aún desconocido»: La Poste solo conoce un paquete cuando el remitente lo entrega. El número se conserva y se vuelve a leer; tras 30 días sin respuesta, se quita.
- «Cuota de La Poste alcanzada» o «no responde»: las lecturas hacen una pausa (una hora, o el tiempo indicado por La Poste; 10 minutos en caso de avería) y se reanudan solas.
- Ningún valor en el dispositivo: cree el dispositivo en la pestaña Descubrir; sus valores se envían en el acto.
- Registros detallados:
LOG_LEVEL=debugen el contenedor.
Límites
- Desarrollada sin el hardware: sin clave de API, las pruebas se hicieron con respuestas simuladas a partir de la documentación de la API. Los primeros usuarios dirán si cada estado se lee bien.
- 50 paquetes como máximo. Los paquetes de otros transportistas (DHL, UPS, Mondial Relay…) no están cubiertos.
- La cuota del plan gratuito figura en developer.laposte.fr (10 peticiones por segundo al escribir estas líneas): con una petición por paquete cada 30 minutos, la integración se queda muy por debajo. El uso de la API sigue sus condiciones de uso en developer.laposte.fr.
- Los textos de los pasos vienen de La Poste, en el idioma de la configuración (inglés, francés, alemán o español).
- Los nombres de las funciones se fijan al crear el dispositivo: cambiar el idioma después no los renombra.
- Sin relación con La Poste. La Poste, Colissimo y Chronopost son marcas de sus propietarios.
Parámetros de configuración
Estos son los parámetros que La Poste te pide en su pantalla de configuración en Gladys.
| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| Su clave de API de La Poste | section | No | Cree una cuenta gratuita en developer.laposte.fr, suscríbase a la API «Suivi» (gratuita) y pegue su clave abajo. Después, añada sus paquetes con la acción «Añadir un paquete» y cree el dispositivo «Paquetes La Poste» en la pestaña Descubrir. |
| Clave de API (X-Okapi-Key) | secret | Sí | La clave de su suscripción «Suivi» en developer.laposte.fr. |
| Intervalo de lectura | select | No | Con qué frecuencia se lee cada paquete en curso. Un paquete entregado ya no se lee. |
| Conservar los paquetes entregados | select | No | Un paquete entregado o devuelto sale de la lista tras este tiempo. |
| Idioma | select | No | Idioma de los nombres de las funciones del nuevo dispositivo, de los textos de La Poste y de los mensajes. |
Cómo instalar La Poste en Gladys
- En Gladys, abre Integraciones: La Poste 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-laposte: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-laposte.
La Poste 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
La Poste 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