Saltar al contenido principal

Actualización a APIDIAN 2027

Esta página es para quien ya tiene un APIDIAN 2026 instalado y tiene que decidir y ejecutar el cambio al 2027. Los pasos detallados de cada entorno siguen en las guías del repositorio: aquí está el panorama completo —qué cambia, qué se necesita antes, en qué orden va todo y cómo comprobarlo— para no empezar a ciegas.

Si lo que necesita es instalar el API desde cero, vaya a Instalación.

Qué cambia y por qué​

APIDIAN 2026APIDIAN 2027
FrameworkLaravel 10.49.1Laravel 13
PHP8.1 como mínimo declarado8.5 recomendado (mínimo 8.3)
Repositorioco-apidian2026co-apidian2027
Composer2.82.10.3
Dockerimagen construida en su servidorimagen publicada jeremyabel710/php85-api:8.5.12
  • Laravel 10 a 13. El salto se hizo en tres pasos (10 → 11 → 12 → 13) conservando la estructura clásica del proyecto, y se instaló de verdad antes de publicarlo: Laravel 13.40, Carbon 3.15.1, dompdf 3.1.6 y PHPUnit 12.5, sin avisos de seguridad pendientes.
  • La versión de PHP. Laravel 13 admite de 8.3 a 8.5. El API declara "php": "^8.3", así que ese es el mínimo real —pensado para el hosting compartido que todavía no ofrece 8.5— y las guías de instalación de Windows, Ubuntu LAMP y Docker usan 8.5 (probado en PHP 8.5.12). Con una versión anterior a 8.3, el composer install se detiene en la comprobación de plataforma.
  • Un repositorio nuevo. El código vive ahora en https://git.buho.la/facturalatam/apidian/co-apidian2027.git. No hay que volver a clonar: se cambia el origen de la carpeta que ya tiene con git remote set-url.
  • Docker ya no construye la imagen. Los servicios php_api y scheduling_api pasan de build: a image: jeremyabel710/php85-api:8.5.12, que trae PHP 8.5.12 con las extensiones del API, OpenSSL con soporte para certificados .p12 antiguos, pdftotext para las fichas RUT, OPcache y PHP-FPM con 20 procesos. El Dockerfile del repositorio (PHP 8.3.36) se queda para quien prefiera construir la imagen en su propio servidor.
No hay fecha límite publicada

El API no fija ningún plazo para pasar al 2027. Lo que sí es urgente, con 2026 o con 2027, es tener PHP parcheado: vea el Aviso de seguridad PHP.

Qué no cambia para quien integra​

Nada de lo que consume una integración cambia con el 2027. Esto no es una promesa: es lo que quedó verificado antes de publicar la versión.

  • Los endpoints y el JSON son los mismos. La colección de Postman del 2027 es idéntica a la del 2026: mismas rutas, mismos cuerpos, mismas respuestas. La Referencia API de este manual se genera desde esa colección. No hay que tocar las integraciones.
  • La base de datos se conserva. Las 205 migraciones corren sin errores en PostgreSQL 16 y en MySQL 8. En PostgreSQL el esquema queda idéntico al de Laravel 10; en MySQL 8 cambian 8 columnas de double(8,2) / double(5,2) a double (las de monitoring_snapshots y el percentage de type_law_deductions y type_overtime_surcharges): es el mismo tipo de almacenamiento, sin precisión declarada. No se borra ni se recrea nada: la actualización corre php artisan migrate sobre su base actual, sin --seed.
  • Lo que genera el API se comporta igual. Firma DIAN, PDF, QR, Excel, cliente HTTP y Swagger se comprobaron contra Laravel 10 y responden lo mismo. Los 48 tests pasan en las dos versiones.
La única salvedad conocida

POST /api/ubl2.1/join-pdfs no funciona en PHP 8. No es una regresión del 2027: falla desde antes, porque la librería que une los PDF usa una función eliminada en PHP 8.0. Está documentado como pendiente de reimplementar.

Antes de empezar​

  1. Mire qué PHP tiene hoy, con php -v, y qué versión usa la web si son distintas (es lo habitual en cPanel). Si está por debajo de 8.3, hay que subirlo antes de traer el código.
  2. Si corre en Ubuntu 20.04 con LAMP (sin Docker), primero suba el sistema. No hay PHP 8.5 para focal, así que el orden es Ubuntu 22.04 y después el API: Actualización de Ubuntu 20.04 a 22.04 en VPS LAMP. Con Docker no hace falta: PHP viene en la imagen y el 20.04 sigue siendo válido (el API publica scripts/scripapi20.sh justamente para esa versión).
  3. Respalde la base de datos y la carpeta del API —sobre todo .env, storage y los certificados— antes de tocar nada. Si usa los respaldos del panel, están en Monitoreo y backups.
  4. Tenga a mano los accesos: la terminal del servidor (SSH, terminal de Laragon o terminal de cPanel), las credenciales del repositorio y, con Docker, la ruta del docker-compose.yml, que no siempre está dentro de la carpeta del API.
  5. Avise a las integraciones. Si viene de una instalación anterior a octubre de 2026, al actualizar se activan las credenciales de administración: crear, consultar y eliminar empresas, los planes, los administradores y el correo general exigen el header X-Admin-Token. Después de actualizar hay que crear la clave con php artisan api:admin-token y entregarla. Detalle en Aviso de seguridad: clave de administración del API.

Los pasos, por entorno​

El orden es siempre el mismo y importa: primero PHP, después el repositorio, después las dependencias.

  1. PHP primero. El composer install se detiene si el PHP del servidor es anterior al mínimo.

  2. Cambiar el origen del repositorio, dentro de la carpeta del API (ya no hace falta editar .git/config a mano):

    git config --global http.sslverify false
    git remote set-url origin https://git.buho.la/facturalatam/apidian/co-apidian2027.git
    git remote set-branches origin master
    git fetch origin
    git branch --set-upstream-to=origin/master master
    git remote -v

    Las dos líneas de git remote -v deben mostrar co-apidian2027.git.

  3. Traer el código: git pull origin master. Si aparecen conflictos y puede descartar los cambios locales: git reset --hard origin/master.

  4. Dependencias y migraciones:

    rm -f bootstrap/cache/*.php
    composer clear-cache
    composer self-update 2.10.3
    rm composer.lock
    composer install
    php artisan migrate
    php artisan optimize:clear
Borrar bootstrap/cache antes de composer install

La configuración cacheada por Laravel 10 hace fallar la instalación con Undefined array key "relative_path". El rm -f bootstrap/cache/*.php del primer comando lo evita. La migración ya no lleva --seed, y php artisan optimize:clear reemplaza a la cadena de config:cache + cache:clear.

Lo propio de cada entorno:

Windows (Laragon)​

Descargue PHP 8.5 en su versión NTS, instale el Visual C++ 2015-2022 (x64), elíjala en Menú → PHP → Versión y deje activas las extensiones curl, fileinfo, gd, intl, mbstring, openssl, pdo_mysql, soap y zip (más pdo_pgsql y pgsql si usa PostgreSQL). Pasos con capturas en Instalación API 2027 — Windows.

Ubuntu (LAMP)​

Instale php8.5 con sus extensiones, a2dismod la versión anterior, a2enmod php8.5, update-alternatives --set php /usr/bin/php8.5 y reinicie Apache. Si había ajustado el php.ini (memoria, tamaño de subida), repita esos valores en el de la versión nueva. Entre como root con export COMPOSER_ALLOW_SUPERUSER=1 y, después del php artisan migrate:

chmod -R 777 storage bootstrap/cache vendor/mpdf/mpdf
chown -R www-data:www-data storage bootstrap/cache vendor/mpdf/mpdf
systemctl restart apache2

Comandos completos en Instalación API 2027 — Linux Ubuntu 22.

Si la instalación corre en Docker​

No se instala PHP: se cambia la imagen. Donde el docker-compose.yml diga

    build:
context: .
dockerfile: Dockerfile

ponga, en php_api y en scheduling_api:

    image: jeremyabel710/php85-api:8.5.12

El resto del bloque (container_name, volumes, user, command, restart, networks) se queda igual. Compruebe el archivo con docker compose config -q y actualice:

cd /ruta/del/api && git pull origin master   # carpeta del código del API
cd /ruta/del/compose # carpeta donde está el docker-compose.yml
docker compose pull php_api scheduling_api
docker compose up -d php_api scheduling_api
docker exec php_api sh -c 'rm -f bootstrap/cache/*.php composer.lock'
docker exec php_api composer install --no-interaction
docker exec php_api php artisan migrate --force
docker exec php_api chmod -R 777 storage bootstrap/cache vendor/mpdf/mpdf
docker exec php_api chown -R www-data:www-data storage bootstrap/cache vendor/mpdf/mpdf
docker exec php_api php artisan optimize:clear
docker restart php_api scheduling_api nginx_api
docker exec php_api php -v # debe mostrar PHP 8.5.12

Nombre solo esos servicios en docker compose pull y docker compose up -d: el mismo archivo puede manejar el proxy, la base de datos u otros sitios del servidor. Si su instalación no tiene scheduling_api, quítelo de los comandos. El docker restart de nginx evita un 502 Bad Gateway que aparece cuando el contenedor PHP cambia de IP interna al recrearse. Aproveche para cambiar también las imágenes de nginx: Aviso de seguridad nginx. Guía completa en Instalación API 2027 — Docker.

cPanel (hosting compartido)​

Asigne al dominio la versión más alta disponible entre 8.5, 8.4 y 8.3 en Select PHP Version o MultiPHP Manager, y revise aparte el PHP de la terminal, que suele ser más viejo que el de la web. Pasos con capturas en Instalación API 2027 — cPanel.

El docker-compose.yml no siempre está en la carpeta del API

El git pull y la edición del .env se hacen en la carpeta del API, pero los comandos docker compose se ejecutan desde la carpeta donde está el docker-compose.yml, porque leen el archivo del directorio actual. Si no sabe dónde quedó, docker compose ls muestra la ruta en la columna CONFIG FILES; si prefiere no cambiar de carpeta, agregue -f /ruta/docker-compose.yml a cada comando. Los nombres de los servicios también varían según el instalador (a veces llevan el dominio como sufijo, por ejemplo php_api_api_midominio_com): véalos con docker compose ps.

Certificados .p12 antiguos

OpenSSL 3 no puede leer los certificados emitidos con cifrado viejo (RC2/3DES). El API los convierte solo la primera vez que los usa; para convertirlos todos de una vez —por ejemplo después de actualizar el servidor— hay un comando nuevo:

php artisan certificates:modernize --dry-run   # solo informa cuáles son antiguos
php artisan certificates:modernize # los convierte, con respaldo del original

Comprobar que quedó bien​

php -v                      # 8.5 (o 8.3 como mínimo)
php artisan --version # Laravel Framework 13
php artisan migrate:status # ninguna pendiente

Con Docker, los dos primeros son docker exec php_api php -v (debe mostrar PHP 8.5.12) y docker exec php_api php artisan --version.

Después, una prueba de punta a punta:

  1. Entre al panel y abra una empresa: debe cargar con su certificado y sus resoluciones.
  2. Emita una factura en ambiente de habilitación y genere su PDF.
  3. Si administra empresas por API, ejecute php artisan api:admin-token --check: debe terminar con COMPROBACIÓN: TODO CORRECTO.

Errores habituales después de actualizar​

Los tres que aparecen al pasar del 2026 al 2027, con su solución en Errores frecuentes:

  • #19 — composer install falla con Undefined array key "relative_path". Quedó la configuración cacheada por Laravel 10 en bootstrap/cache. Bórrela y repita.
  • #20 — Laragon: No se encuentra el punto de entrada nghttp2... al elegir PHP 8.5. Se descargó la versión Thread Safe; hay que usar la NTS.
  • #21 — Al facturar: mkdir(): Permission denied (Cache.php). Faltan los permisos de storage y bootstrap/cache después de la actualización.

Si la instalación corre en Docker y aparece un 502 Bad Gateway justo después de recrear los contenedores, es el contenedor PHP que cambió de IP interna: docker restart nginx_api. Está en el Aviso de seguridad PHP.

Si algo falla: volver atrás​

El código se puede devolver; la base de datos, no del todo. Por eso el respaldo del paso 3 de Antes de empezar es lo que de verdad protege la instalación.

  • El código. Mientras no haya borrado la carpeta, el commit en el que estaba sigue en su repositorio local: git log para ubicarlo y git reset --hard <commit> para volver a él. Si además quiere dejar el origen como estaba, repita el git remote set-url con la URL anterior.
  • Las dependencias. Al volver al código anterior hay que volver a instalar su vendor (rm composer.lock && composer install con el PHP que usaba esa versión), porque el vendor de Laravel 13 no sirve para Laravel 10.
  • Docker. Deje de nuevo el build: original —o el tag de imagen que usaba— en php_api y scheduling_api, y levante los servicios otra vez.
  • La base de datos. Las migraciones que ya corrieron no tienen una vuelta atrás documentada. Si necesita el esquema anterior, la vía es restaurar el respaldo que tomó antes de empezar.
precaución

Antes de revertir nada, conviene abrir un caso con soporte: casi todos los problemas de esta actualización son los tres de la lista de arriba y se resuelven sin volver atrás.