Aviso de seguridad: clave de administración del API

Importante

Desde la actualización del 27 de octubre de 2026, crear, consultar y eliminar empresas por el API exige una clave de administración. Después de actualizar hay que crear esa clave: es un solo bloque para copiar y pegar en la consola.

Facturar, enviar notas, nómina y eventos sigue funcionando igual.

Si su API está alojada por FacturaLatam, nosotros nos encargamos y no tiene que hacer nada.

Si acaba de instalar con el script de Docker

Desde el 30 de octubre de 2026 los scripts de instalación (scripapi.sh y scripapi20.sh) crean la clave solos: la escriben en el .env como PLATFORM_ADMIN_TOKEN y la dejan en setup/private.txt, bajo el título CLAVE DE ADMINISTRACION DEL API, junto a las demás claves de la instalación. Antes de terminar, el script la comprueba y debe mostrar COMPROBACION: TODO CORRECTO.

En una instalación así no hay que hacer los pasos 1 y 2: basta con entregar la clave. Para volver a verla, ejecute docker exec -ti php_api php artisan api:admin-token.

Antes de empezar

Necesita entrar por consola (SSH) al servidor del API o, en Windows, abrir la Terminal de Laragon. Son tres pasos: actualizar el API, crear la clave y entregarla.

En cada bloque, cambie solo lo que está en MAYÚSCULAS antes de pegarlo. Pegue un bloque a la vez y espere a que termine antes de pegar el siguiente:

En el bloque dice	Cámbielo por
/RUTA/DEL/API	La carpeta del API, donde está el archivo artisan. Por ejemplo /var/www/html/apidian
CARPETA-DEL-API	Solo en Windows: la carpeta del API dentro de C:\laragon\www. Por ejemplo apidian
https://SU-DOMINIO-DEL-API	La dirección de su API, por ejemplo https://api.miempresa.com

En Docker los bloques usan docker exec -ti php_api, que funciona desde cualquier carpeta del servidor: no hace falta buscar el docker-compose.yml. php_api es el nombre que el instalador le da al contenedor del API; si un comando responde No such container, vea los nombres con docker ps --format "{{.Names}}" y use el del contenedor PHP del API, no el de nginx, el de scheduling ni el de la base de datos.

Paso 1. Actualizar el API

Docker

cd /RUTA/DEL/API
git pull origin master
docker exec -ti php_api sh -c "php artisan optimize:clear && php artisan config:cache && php artisan migrate --force"

Si el git pull trajo cambios en el Dockerfile o en la carpeta docker/

Hay que reconstruir la imagen antes de seguir, como explica Actualización.

Servidor Linux (LAMP)

cd /RUTA/DEL/API
git pull origin master
php artisan optimize:clear
php artisan config:cache
php artisan migrate --force

Windows con Laragon

Abra Laragon, pulse el botón Terminal y pegue:

cd /d C:\laragon\www\CARPETA-DEL-API
git pull origin master
php artisan optimize:clear
php artisan config:cache
php artisan migrate --force

Paso 2. Crear la clave

Un solo comando guarda una copia del .env, crea la clave, la muestra y comprueba la instalación. Si lo ejecuta dos veces no crea una clave nueva: la vuelve a mostrar, así que sirve también para consultarla más adelante.

Docker

docker exec -ti php_api php artisan api:admin-token

Servidor Linux (LAMP)

cd /RUTA/DEL/API
php artisan api:admin-token

Windows con Laragon

cd /d C:\laragon\www\CARPETA-DEL-API
php artisan api:admin-token

Copie la clave que aparece entre las dos líneas de ===== y guárdela en un lugar seguro. El comando termina con la comprobación: debe decir COMPROBACIÓN: TODO CORRECTO. Si dice otra cosa, vea Si algo falla al ejecutar los comandos.

Si ya usaba el correo general

Si el .env ya tenía una clave en SMTP_ADMIN_TOKEN (la que pide el correo general, PUT /api/ubl2.1/config/smtp-global), el comando reutiliza ese valor en lugar de crear otro y lo avisa con Se reutiliza la clave que ya estaba en SMTP_ADMIN_TOKEN. Los sistemas que ya la enviaban no tienen que cambiarla: basta con que la envíen también al crear, consultar y eliminar empresas.

Paso 3. Entregar la clave

Entregue la clave a quien administra los sistemas que crean, consultan o eliminan empresas en su API. Esos sistemas deben enviarla en cada una de esas peticiones; las instrucciones para ellos están en Para quien desarrolla integraciones.

Cuando la tengan configurada, crear o consultar una empresa desde ese sistema debe funcionar como antes. Para volver a ver la clave sin cambiarla, repita el paso 2.

Si su hosting no tiene consola

1. Abra el archivo .env del API con el administrador de archivos del hosting y agregue al final esta línea, con una clave larga inventada por usted, de letras y números, sin espacios:

   PLATFORM_ADMIN_TOKEN=UNA-CLAVE-LARGA-DE-LETRAS-Y-NUMEROS

   Si el .env ya tiene una línea SMTP_ADMIN_TOKEN= con algo escrito después del =, use ese mismo texto como clave.

2. Borre el archivo bootstrap/cache/config.php del API, si existe.

3. Entregue la clave como dice el paso 3.

Si algo falla al ejecutar los comandos

Lo que ve	Qué hacer
REVISAR: el API todavía no ve la clave o REVISAR: el API rechaza su propia clave	Ejecute php artisan config:cache y repita el paso 2
AVISO: la clave funciona, pero el modo temporal está activado	Si no lo activó a propósito, siga Volver a activar la seguridad
Command "api:admin-token" is not defined.	El código no se actualizó. Revise el mensaje del git pull y vea Actualización
Could not open input file: artisan	No está en la carpeta del API. En Docker, entre al contenedor y escriba cd /var/www/html
No such container: php_api	Vea el nombre del contenedor como indica Antes de empezar
Composer detected issues in your platform	La consola usa una versión de PHP anterior a la del API. En Laragon: Menú › PHP › Versión, elija la versión del API y abra otra Terminal

Si un sistema deja de crear o consultar empresas

Es porque ese sistema todavía no envía la clave. Mientras lo actualizan, puede activar un modo temporal que deja crear y consultar empresas sin la clave. Eliminar empresas la sigue pidiendo y cada llamada sin la clave queda anotada en el log del API.

Docker:

cd /RUTA/DEL/API
[ -n "$(tail -c1 .env)" ] && echo >> .env
sed -i '/^ALLOW_PUBLIC_API_REGISTER=/d' .env
echo 'ALLOW_PUBLIC_API_REGISTER=true' >> .env
docker exec -ti php_api php artisan config:cache

Servidor Linux (LAMP):

cd /RUTA/DEL/API
[ -n "$(tail -c1 .env)" ] && echo >> .env
sed -i '/^ALLOW_PUBLIC_API_REGISTER=/d' .env
echo 'ALLOW_PUBLIC_API_REGISTER=true' >> .env
php artisan config:cache
echo "Modo temporal activado"

Windows con Laragon: abra el .env del API con notepad .env desde la Terminal, agregue al final la línea ALLOW_PUBLIC_API_REGISTER=true, guarde y cierre. Después ejecute php artisan config:cache.

Úselo solo mientras actualizan ese sistema. Cuando ya envíe la clave, vuelva a activar la seguridad.

Volver a activar la seguridad

Docker:

cd /RUTA/DEL/API
sed -i '/^ALLOW_PUBLIC_API_REGISTER=/d' .env
docker exec -ti php_api sh -c "php artisan config:cache && php artisan api:admin-token --check"

Servidor Linux (LAMP):

cd /RUTA/DEL/API
sed -i '/^ALLOW_PUBLIC_API_REGISTER=/d' .env
php artisan config:cache
php artisan api:admin-token --check

En Windows, borre esa línea del .env con notepad .env y ejecute los dos últimos comandos. En los tres casos debe terminar con COMPROBACIÓN: TODO CORRECTO.

Cambios que va a notar

• Empresas nuevas: al crear una empresa, la clave para entrar al panel ya no es el NIT. Aparece una sola vez al final del asistente de nueva empresa: guárdela.
• Panel: el asistente Empresa › Nuevo sigue funcionando sin la clave de administración.
• Portales de clientes y empleados: piden la clave cada vez que se abre una sesión nueva.
• Correos antiguos: el botón "Aceptar y/o Rechazar documento" de los correos enviados antes de esta actualización abre el portal del cliente y pide su clave.

Para quien desarrolla integraciones

Cómo enviar la clave de administración en las peticiones

Envíe la clave en el header X-Admin-Token en estas peticiones:

Ruta	Qué hace
POST /api/ubl2.1/config/{nit}/{dv}	Crear o actualizar una empresa
GET /api/ubl2.1/config/query/{nit}	Consultar los datos de una empresa
POST /api/ubl2.1/config/delete/{nit}/{email}	Eliminar una empresa

Ejemplos:

# Crear o actualizar una empresa (datos.json lleva el cuerpo de siempre)
curl -X POST "https://SU-DOMINIO-DEL-API/api/ubl2.1/config/900123456/7" \
  -H "Accept: application/json" -H "Content-Type: application/json" \
  -H "X-Admin-Token: SU_CLAVE" \
  -d @datos.json

# Consultar una empresa
curl "https://SU-DOMINIO-DEL-API/api/ubl2.1/config/query/900123456" \
  -H "Accept: application/json" -H "X-Admin-Token: SU_CLAVE"

# Eliminar una empresa
curl -X POST "https://SU-DOMINIO-DEL-API/api/ubl2.1/config/delete/900123456/correo@empresa.com" \
  -H "Accept: application/json" -H "X-Admin-Token: SU_CLAVE"

Sin la clave, o con otra, la respuesta es 403 y el campo message dice qué falta:

message empieza por	Qué hacer
La instalación no tiene clave de administración.	Ejecutar php artisan api:admin-token en el servidor del API
Falta la clave de administración en el header X-Admin-Token.	Agregar el header a la petición
La clave de administración (X-Admin-Token) no es válida.	Usar la misma clave que muestra php artisan api:admin-token

También exigen el X-Admin-Token el correo general (PUT /api/ubl2.1/config/smtp-global), los planes (/api/ubl2.1/plan) y los administradores (/api/ubl2.1/administrator).

Detalle técnico

Para el equipo de sistemas: rutas que cambian, nombres de las claves y comandos opcionales

Claves del .env del API

Clave	Qué hace
PLATFORM_ADMIN_TOKEN	Clave de administración. Debe llegar en el header X-Admin-Token. La crea php artisan api:admin-token, y php artisan api:admin-token --check solo comprueba que el API la vea y que la seguridad esté activa
SMTP_ADMIN_TOKEN	Nombre anterior de la misma clave. Se sigue aceptando
ALLOW_PUBLIC_API_REGISTER	Modo temporal. Sin definir o en false, crear y consultar empresas exigen la clave. En true también aceptan llamadas sin ella

Rutas que cambian

Rutas	Desde esta versión
Crear, consultar y eliminar empresa, rotar token, correo general, planes y administradores	Exigen el header X-Admin-Token. Crear y consultar dejan de exigirlo con ALLOW_PUBLIC_API_REGISTER=true
signdocument, senddocument, statusdocument y statuszip	Exigen el api_token de la empresa
Rutas que reciben un NIT: descargas, resoluciones, recarga de PDF y borrar por NIT	Solo responden si el NIT es de la empresa del token
POST /api/accept-reject-document	Eliminada. Los eventos se envían por POST /api/ubl2.1/send-event
POST /api/send-email-customer	Sin token, el correo va siempre al correo registrado del adquiriente

Quién sigue llamando sin la clave

Mientras el modo temporal esté activado, cada creación o consulta de empresa sin el header queda anotada en el log del día, con la ruta y la IP:

cd /RUTA/DEL/API
grep -h "periodo de gracia" storage/logs/laravel-*.log | tail -20

Opcional: cambiar el token de una empresa

Las empresas nuevas reciben un api_token aleatorio. Las creadas antes de esta versión conservan el suyo, que se calculó a partir del NIT. Cambiarlo lo vuelve aleatorio, pero el token anterior deja de funcionar en ese momento: no lo ejecute sin coordinar antes con cada integración. El comando pide confirmación y muestra el token nuevo de cada empresa.

cd /RUTA/DEL/API
php artisan api:rotate-token 900123456
php artisan api:rotate-token --derived

En Docker: docker exec -ti php_api php artisan api:rotate-token --derived.

Por API: PUT /api/ubl2.1/config/rotate-token/{nit} con el X-Admin-Token.