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 2026 | APIDIAN 2027 | |
|---|---|---|
| Framework | Laravel 10.49.1 | Laravel 13 |
| PHP | 8.1 como mínimo declarado | 8.5 recomendado (mínimo 8.3) |
| Repositorio | co-apidian2026 | co-apidian2027 |
| Composer | 2.8 | 2.10.3 |
| Docker | imagen construida en su servidor | imagen 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, elcomposer installse 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 congit remote set-url. - Docker ya no construye la imagen. Los servicios
php_apiyscheduling_apipasan debuild:aimage: jeremyabel710/php85-api:8.5.12, que trae PHP 8.5.12 con las extensiones del API, OpenSSL con soporte para certificados.p12antiguos,pdftotextpara las fichas RUT, OPcache y PHP-FPM con 20 procesos. ElDockerfiledel repositorio (PHP 8.3.36) se queda para quien prefiera construir la imagen en su propio servidor.
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)adouble(las demonitoring_snapshotsy elpercentagedetype_law_deductionsytype_overtime_surcharges): es el mismo tipo de almacenamiento, sin precisión declarada. No se borra ni se recrea nada: la actualización correphp artisan migratesobre 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.
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
- 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. - 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.shjustamente para esa versión). - Respalde la base de datos y la carpeta del API —sobre todo
.env,storagey los certificados— antes de tocar nada. Si usa los respaldos del panel, están en Monitoreo y backups. - 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. - 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 conphp artisan api:admin-tokeny 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.
-
PHP primero. El
composer installse detiene si el PHP del servidor es anterior al mínimo. -
Cambiar el origen del repositorio, dentro de la carpeta del API (ya no hace falta editar
.git/configa 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 -vLas dos líneas de
git remote -vdeben mostrarco-apidian2027.git. -
Traer el código:
git pull origin master. Si aparecen conflictos y puede descartar los cambios locales:git reset --hard origin/master. -
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
bootstrap/cache antes de composer installLa 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.
docker-compose.yml no siempre está en la carpeta del APIEl 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.
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:
- Entre al panel y abra una empresa: debe cargar con su certificado y sus resoluciones.
- Emita una factura en ambiente de habilitación y genere su PDF.
- Si administra empresas por API, ejecute
php artisan api:admin-token --check: debe terminar conCOMPROBACIÓ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 installfalla con Undefined array key "relative_path". Quedó la configuración cacheada por Laravel 10 enbootstrap/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
storageybootstrap/cachedespué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 logpara ubicarlo ygit reset --hard <commit>para volver a él. Si además quiere dejar el origen como estaba, repita elgit remote set-urlcon la URL anterior. - Las dependencias. Al volver al código anterior hay que volver a instalar su
vendor(rm composer.lock && composer installcon el PHP que usaba esa versión), porque elvendorde Laravel 13 no sirve para Laravel 10. - Docker. Deje de nuevo el
build:original —o el tag de imagen que usaba— enphp_apiyscheduling_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.
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.