Autenticación

La API de Fenicia usa API keys para autenticar cada request. Las llaves identifican a tu cuenta (tenant), definen los permisos disponibles y se envían en el header Authorization con el esquema Bearer.

Antes de empezar, necesitas obtener una API key desde el panel de Fenicia. Esta guía te lleva paso a paso por el proceso completo.

Base URL

https://api.fenicia.io

Dominio único

Todos los endpoints de la API de Fenicia viven bajo api.fenicia.io. El dominio accounts.fenicia.io se usa solo para el flujo de autenticación del panel, y webhooks.fenicia.io para recibir webhooks de terceros — ninguno se usa para consumir la API pública.

Obtener una API Key

Sigue estos pasos desde tu panel de Fenicia para generar una nueva API key.

Inicia sesión en tu panel de Fenicia

Abre app.fenicia.io en tu navegador e ingresa con tu correo y contraseña. Si tienes habilitada la autenticación de dos factores, introduce también el código.

Abre Configuración

En la barra lateral izquierda, haz clic en Configuración. Este es el ícono de engranaje en la parte inferior del menú principal.

Ve a Claves API

Dentro del submenú de Configuración, selecciona Claves API. Verás la lista de llaves existentes (o un estado vacío si es la primera vez).

Crea una nueva clave

Haz clic en el botón + Crear clave API en la esquina superior derecha de la pantalla.

Configura la clave

Completa el formulario con los datos de la nueva llave:

Nombre: descriptivo, por ejemplo Producción - Mi integración o Staging - Script de importación.
Fecha de expiración (opcional): recomendado para entornos productivos. Si no defines una, la llave no expira.
Scopes: selecciona únicamente los permisos que la integración necesita (por ejemplo orders:read, products:update). Aplica el principio de mínimo privilegio.

Copia la clave INMEDIATAMENTE

Solo se muestra una vez

Por seguridad, Fenicia solo muestra la clave completa en el momento de crearla. Después de cerrar el modal no podrás recuperarla. Si la pierdes, tendrás que crear una nueva y actualizar tu integración.

Copia la clave y guárdala en un lugar seguro: un gestor de contraseñas (1Password, Bitwarden), un gestor de secretos (AWS Secrets Manager, HashiCorp Vault) o una variable de entorno en tu servidor.

Guarda la clave en tu ambiente

Nunca pongas la API key directamente en el código fuente. La práctica recomendada es leerla desde una variable de entorno:

# .env
FENICIA_API_KEY=fn_live_tu_api_key_aqui

Asegúrate de que el archivo .env esté en tu .gitignore para no subirlo al repositorio.

Sección de Claves API en Configuración, con el botón Crear clave API en la esquina superior derecha — Configuración → Claves API. Desde aquí gestionas todas las API keys de tu cuenta.

Formatos de key

Las API keys de Fenicia tienen uno de estos prefijos según su origen:

Prefijo	Uso
`fn_live_...`	Ambiente de producción (formato actual)
`fkapi_...`	Keys legacy (siguen funcionando, se migrarán a `fn_live_` en el futuro)

Seguridad

Trata tus API keys como contraseñas

Nunca expongas tus API keys en código del cliente, repositorios públicos, logs, capturas de pantalla ni tickets de soporte. Si sospechas que una llave fue filtrada, revócala de inmediato y genera una nueva.

Enviar requests autenticados

Incluye tu API key en el header Authorization de cada request:

Authorization: Bearer fn_live_tu_api_key_aqui

Ejemplos por lenguaje

curl https://api.fenicia.io/orders \
  -H "Authorization: Bearer fn_live_tu_api_key" \
  -H "Content-Type: application/json"

Scopes (Permisos)

Cada API key tiene un conjunto de scopes que definen qué recursos puede acceder. El formato es resource:action.

Scope	Permite
`orders:read`	Listar y consultar pedidos
`orders:create`	Crear pedidos manuales
`orders:update`	Modificar pedidos existentes
`orders:*`	Todas las acciones sobre pedidos
`products:read`	Consultar catálogo de productos
`inventory:update`	Ajustar niveles de stock
`:`	Acceso completo (solo owners)

Si intentas usar un endpoint sin el scope requerido, recibirás un error 403 INSUFFICIENT_PERMISSIONS.

Rate Limiting

La API tiene un límite de 100 requests por 60 segundos por IP. Si excedes el límite, recibirás un 429 Too Many Requests:

{
  "error": "Too many requests",
  "retryAfter": 45
}

Tip

Implementa reintentos con backoff exponencial respetando el valor de retryAfter (en segundos).

Rotar o revocar una clave

Rotar las API keys de forma periódica (cada 60-90 días) es una buena práctica de seguridad. Fenicia permite rotar sin downtime si sigues este proceso.

Rotar una clave sin interrupción

Crea una nueva API key

Desde Configuración → Claves API, crea una nueva clave con los mismos scopes que la actual. Dale un nombre que identifique el ciclo de rotación (por ejemplo Producción - 2026-Q2).

Actualiza tu aplicación

Despliega el cambio de variable de entorno (FENICIA_API_KEY) en todos tus servidores o funciones. Verifica que las requests funcionen correctamente con la nueva clave.

Revoca la clave anterior

Una vez confirmado que todo el tráfico usa la nueva clave, revoca la anterior desde la lista de Claves API.

Revocar una clave

En la lista de Claves API, haz clic en el ícono de eliminar junto a la llave que quieres revocar y confirma la acción.

Efecto inmediato

Las claves revocadas dejan de funcionar al instante: cualquier request que las use recibirá 401 INVALID_API_KEY. Asegúrate de haber migrado todo el tráfico antes de revocar.

Errores de autenticación

Código	Status	Descripción
`MISSING_AUTHORIZATION`	401	No se envió el header `Authorization`
`INVALID_AUTHORIZATION_FORMAT`	401	El header no usa el formato `Bearer <key>`
`INVALID_API_KEY`	401	La API key no existe, está expirada o revocada
`INSUFFICIENT_PERMISSIONS`	403	La key no tiene el scope necesario para este endpoint
`account/billing_restricted`	403	La cuenta está suspendida por billing

Siguientes pasos

Autenticación

Antes de empezar, necesitas obtener una API key desde el panel de Fenicia. Esta guía te lleva paso a paso por el proceso completo.

Obtener una API Key

Sigue estos pasos desde tu panel de Fenicia para generar una nueva API key.

Inicia sesión en tu panel de Fenicia

Abre app.fenicia.io en tu navegador e ingresa con tu correo y contraseña. Si tienes habilitada la autenticación de dos factores, introduce también el código.

Abre Configuración

En la barra lateral izquierda, haz clic en Configuración. Este es el ícono de engranaje en la parte inferior del menú principal.

Ve a Claves API

Dentro del submenú de Configuración, selecciona Claves API. Verás la lista de llaves existentes (o un estado vacío si es la primera vez).

Crea una nueva clave

Haz clic en el botón + Crear clave API en la esquina superior derecha de la pantalla.

Configura la clave

Completa el formulario con los datos de la nueva llave:

Nombre: descriptivo, por ejemplo Producción - Mi integración o Staging - Script de importación.
Fecha de expiración (opcional): recomendado para entornos productivos. Si no defines una, la llave no expira.
Scopes: selecciona únicamente los permisos que la integración necesita (por ejemplo orders:read, products:update). Aplica el principio de mínimo privilegio.

Copia la clave INMEDIATAMENTE

Solo se muestra una vez

Copia la clave y guárdala en un lugar seguro: un gestor de contraseñas (1Password, Bitwarden), un gestor de secretos (AWS Secrets Manager, HashiCorp Vault) o una variable de entorno en tu servidor.

Guarda la clave en tu ambiente

Nunca pongas la API key directamente en el código fuente. La práctica recomendada es leerla desde una variable de entorno:

# .env
FENICIA_API_KEY=fn_live_tu_api_key_aqui

Asegúrate de que el archivo .env esté en tu .gitignore para no subirlo al repositorio.

Configuración → Claves API. Desde aquí gestionas todas las API keys de tu cuenta.

Prefijo

Uso

fn_live_...

Ambiente de producción (formato actual)

fkapi_...

Keys legacy (siguen funcionando, se migrarán a fn_live_ en el futuro)

Scopes (Permisos)

Cada API key tiene un conjunto de scopes que definen qué recursos puede acceder. El formato es resource:action.

Scope

Permite

orders:read

Listar y consultar pedidos

orders:create

Crear pedidos manuales

orders:update

Modificar pedidos existentes

orders:*

Todas las acciones sobre pedidos

products:read

Consultar catálogo de productos

inventory:update

Ajustar niveles de stock

*:*

Acceso completo (solo owners)

Si intentas usar un endpoint sin el scope requerido, recibirás un error 403 INSUFFICIENT_PERMISSIONS.

Rotar o revocar una clave

Rotar las API keys de forma periódica (cada 60-90 días) es una buena práctica de seguridad. Fenicia permite rotar sin downtime si sigues este proceso.

Crea una nueva API key

Desde Configuración → Claves API, crea una nueva clave con los mismos scopes que la actual. Dale un nombre que identifique el ciclo de rotación (por ejemplo Producción - 2026-Q2).

Actualiza tu aplicación

Despliega el cambio de variable de entorno (FENICIA_API_KEY) en todos tus servidores o funciones. Verifica que las requests funcionen correctamente con la nueva clave.

Revoca la clave anterior

Una vez confirmado que todo el tráfico usa la nueva clave, revoca la anterior desde la lista de Claves API.

En la lista de Claves API, haz clic en el ícono de eliminar junto a la llave que quieres revocar y confirma la acción.

Efecto inmediato

Las claves revocadas dejan de funcionar al instante: cualquier request que las use recibirá 401 INVALID_API_KEY. Asegúrate de haber migrado todo el tráfico antes de revocar.

Errores de autenticación

Código

Status

Descripción

MISSING_AUTHORIZATION

401

No se envió el header Authorization

INVALID_AUTHORIZATION_FORMAT

401

El header no usa el formato Bearer <key>

INVALID_API_KEY

401

La API key no existe, está expirada o revocada

INSUFFICIENT_PERMISSIONS

403

La key no tiene el scope necesario para este endpoint

account/billing_restricted

403

La cuenta está suspendida por billing