Autenticación y API keys

Toda solicitud a la API de facturación lleva una API key como token Bearer. La única ruta sin llave es GET /v1/status.

curl https://api.flashpi.com.ec/v1/documents \
  -H "Authorization: Bearer $FLASHPI_API_KEY"

Llaves de prueba y de producción

Prefijo	Ambiente	Para qué sirve
`fp_test_`	Ambiente de pruebas del SRI (ambiente 1)	Desarrollo, pruebas automatizadas y el sandbox. Los comprobantes no tienen efecto tributario.
`fp_live_`	Producción del SRI (ambiente 2)	Comprobantes con efecto tributario.

Ambos tipos llaman a la misma API en https://api.flashpi.com.ec. La llave decide el ambiente, y cada ambiente está separado: una llave de prueba solo ve comprobantes, certificados, endpoints de webhooks y eventos de prueba, y una de producción solo los de producción. Un certificado subido con el alta desde el certificado sirve a ambos ambientes, así que ambas llaves lo ven. Las claves de idempotencia también son distintas por ambiente.

Una llave tiene la forma fp_test_ o fp_live_, seguida de un ID público de 16 caracteres y de un secreto de 32 caracteres (56 caracteres en total, solo letras y dígitos). El ID público no es secreto: la consola y los request logs lo muestran para que distingas tus llaves. Flashpi guarda solo un hash SHA-256 de la llave completa, así que nadie, ni siquiera Flashpi, puede volver a mostrarla después de crearla.

Crear llaves

Las API keys se crean en la consola, en API keys; la API no tiene un endpoint para crearlas. Cada llave tiene un nombre, un ambiente, un alcance, un nivel de acceso y una lista opcional de IP permitidas. La llave completa se muestra una sola vez, al crearla.

Llaves de prueba: las pueden crear los propietarios de la cuenta y los miembros con lectura y escritura en todos los emisores.
Llaves de producción: solo las crean los propietarios de la cuenta, que confirman con el código de su app de autenticación (la verificación en dos pasos es obligatoria para los propietarios). Antes, la cuenta necesita un emisor propio, que no sea el emisor demo, con un certificado de firma aceptado. Consulta Emisores y Certificados.

El alcance y el nivel de acceso no cambian después de crear la llave; su nombre y su lista de IP sí. Para cambiar lo demás, crea una llave nueva y revoca la anterior.

Alcance

account (toda la cuenta): todos los emisores de la cuenta, incluidos los que se agreguen después.
issuer (un emisor): un solo emisor (un RUC). La llave solo puede emitir y leer los comprobantes y eventos de ese emisor.

Una llave de un emisor recibe 403 con el código key_scope_mismatch cuando indica otro emisor o llama a una ruta de toda la cuenta: administrar emisores, establecimientos, puntos de emisión, certificados y endpoints de webhooks. El emisor demo compartido también requiere una llave con alcance account.

Nivel de acceso

read_write: puede emitir comprobantes, reenviarlos por correo y, con alcance account, administrar la configuración.
read_only: puede leer comprobantes, su XML y su RIDE, y los eventos. Todo lo que escribe responde 403 con el código key_read_only.

Administrar emisores, establecimientos, puntos de emisión, certificados y endpoints de webhooks requiere una llave read_write con alcance account, también para leerlos.

Lista de IP permitidas

Una llave puede limitarse a una lista de hasta 20 direcciones IPv4 o IPv6 o rangos CIDR, como 203.0.113.10 o 2001:db8::/48. Una lista vacía permite cualquier dirección.

La dirección que se valida es la desde la que tu solicitud llega al borde de Flashpi: la dirección pública de tu servidor o de su NAT, no una privada.
Una solicitud desde cualquier otra dirección recibe 403 con el código ip_not_allowed, y el detail indica la dirección que vio Flashpi, para que puedas agregarla.
Un rango con bits de host (10.0.0.1/8) se rechaza porque probablemente es un error. Escribe la dirección de red (10.0.0.0/8).
Cambiar la lista de IP de una llave de producción en la consola pide el código de tu app de autenticación.

Errores

Situación	Respuesta
Sin encabezado `Authorization`, o no es un token Bearer	`401` `authentication_required`
Llave mal formada, desconocida o revocada	`401` `invalid_api_key`
La cuenta está suspendida	`403` `account_suspended`
La IP del cliente no está en la lista de la llave	`403` `ip_not_allowed`
Una llave de un emisor en otro emisor o en una ruta de toda la cuenta	`403` `key_scope_mismatch`
Una llave `read_only` en una ruta que escribe	`403` `key_read_only`

Las dos respuestas 401 traen WWW-Authenticate: Bearer realm="flashpi", con error="invalid_token" además en invalid_api_key. Una llave mal formada, una desconocida y una revocada reciben el mismo código a propósito, para que la respuesta nunca revele qué llaves existen. Todos los cuerpos de error siguen el formato de Errores.

Mantén tus llaves seguras

Guarda las llaves en tus servidores. Nunca pongas una llave en una página web, una app móvil, una app de escritorio que distribuyas ni un repositorio público. Quien tenga la llave puede emitir comprobantes a tu nombre.
Guárdalas como secretos. Lee la llave de una variable de entorno o de un gestor de secretos, no de tu código fuente. Mantén las llaves de producción fuera de las máquinas de desarrollo y de la integración continua.
Una llave por sistema y por ambiente. Una llave distinta para cada servicio (tu tienda, tu ERP, un proceso de reportes) te permite revocar una sin detener las demás, y los request logs muestran cuál llamó.
Dale a cada llave lo mínimo que necesita. Usa una llave de un emisor para un sistema que solo emite para un RUC, y una llave read_only para reportes y conciliación.
Agrega una lista de IP cuando tus servidores tengan direcciones públicas fijas.
Nunca registres la llave en logs. Deja el encabezado Authorization fuera de tus logs y reportes de errores. Para identificar una llave, usa su ID público.
Rótalas sin cortes. Crea la llave nueva, despliégala, revisa en los request logs de la consola que la anterior ya no se usa y luego revócala.
Revoca de inmediato una llave filtrada. La revocación tiene efecto al instante y nunca pide el código de autenticación, así que una llave filtrada se puede detener enseguida. Revocar una llave de producción envía un correo a todos los propietarios de la cuenta.