Autenticación

Toda llamada a la API lleva una API key. La key identifica una empresa dentro de tu organización y, por su prefijo, el ambiente de la DGII contra el que trabajas.

Como enviar la key

Dos formas, equivalentes. Elige una:

X-API-Key: ffs_live_ejemplodeclavenoreal000000000000000000

Authorization: Bearer ffs_live_ejemplodeclavenoreal000000000000000000

curl -H "X-API-Key: ffs_test_ejemplodeclavenoreal000000000000000000" \
  https://api.fiscalflowsupport.com/api/v1/ping

import requests

r = requests.get(
    "https://api.fiscalflowsupport.com/api/v1/ping",
    headers={"X-API-Key": "ffs_test_ejemplodeclavenoreal000000000000000000"},
)
print(r.json()["data"]["environment"])

const r = await fetch("https://api.fiscalflowsupport.com/api/v1/ping", {
  headers: { "X-API-Key": "ffs_test_ejemplodeclavenoreal000000000000000000" },
});
const { data } = await r.json();
console.log(data.environment);

{
  "success": true,
  "data": {
    "pong": true,
    "server_time": "2026-08-14T15:04:10+00:00",
    "versión": "1.0.0",
    "environment": "testecf",
    "organization": { "slug": "mi-organizacion", "name": "Mi Organización SRL" },
    "company": {
      "uuid": "9f1c2d3e-4b5a-6c7d-8e9f-0a1b2c3d4e5f",
      "rnc": "101000000",
      "legal_name": "Mi Empresa SRL"
    },
    "api_key": { "prefix": "ffs_test_abc", "name": "Integración ERP" }
  }
}

GET /api/v1/ping es la forma más rápida de confirmar que la key funciona y, sobre todo, en qué ambiente estás. Vale la pena llamarlo al arrancar tu integración y registrar el environment que devuelve.

El prefijo elige el ambiente

No hay hosts distintos por ambiente ni un parámetro que lo indique. Lo decide el prefijo de la key:

El ambiente que devuelve ping y el que queda grabado en cada documento (environment) salen de ese prefijo.

Alcance de una key

Una key pertenece a una empresa, no a la organización completa. Si administras varios RNC, necesitas una key por empresa y por ambiente. Los endpoints que listan documentos filtran por la empresa de la key; unos pocos de solo lectura, como GET /api/v1/inbox y GET /api/v1/webhooks, abarcan todas las empresas de la organización.

Crear y rotar keys

Las keys se emiten desde el panel de FiscalFlow, en la pantalla Integraciones de cada empresa. La clave completa se muestra una sola vez: copiala en ese momento. Despues solo verás su prefijo.

Rotar emite una clave nueva y revoca la anterior en el acto. No hay periodo de gracia, así que despliega la clave nueva antes de rotar, o asume una ventana de fallos.

Limites de peticiones

El límite se cuenta por empresa y por minuto, según el plan:

Al excederlo:

HTTP/1.1 429 Too Many Requests
Retry-After: 37
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
Content-Type: application/json

{
  "message": "Too Many Attempts."
}

Respeta Retry-After. Ese cuerpo es el de Laravel y no lleva el sobre success/error del resto de la API: si tu cliente asume siempre la misma forma, aquí se rompe. Ver Errores y rechazos.

Lista blanca de IP

Una key puede restringirse a direcciones IP o rangos CIDR concretos, algo recomendable para producción. Una petición desde una IP no autorizada recibe 403 aunque la key sea valida:

{
  "success": false,
  "message": "IP not whitelisted",
  "ip": "203.0.113.10"
}

Si sales por una IP dinámica, o por un balanceador con varias salidas, incluye el rango completo o deja la restricción desactivada: una IP que rota deja tu integración fuera sin aviso.

Key inválida o ausente

{
  "success": false,
  "message": "Invalid API key"
}

Recibes lo mismo si no mandas key, si la mandaste mal, si fue revocada, o si la envías como Authorization: Bearer sin uno de los tres prefijos reconocidos. Si estás seguro de la clave, revisa que el header llegue: algunos proxies eliminan cabeceras personalizadas como X-API-Key.