API PÚBLICA

Referencia de la API de FactuON

Integra la facturación y gestión de contactos de FactuON directamente en tu aplicación. Crea facturas y gestiona organizaciones mediante programación con nuestra API REST.

URL Basehttps://api.factuon.com/api/v1.0.1/public

Inicio Rápido

Haz tu primera llamada a la API en menos de 5 minutos.

Genera una Clave API

Ve a Configuración → Claves API en tu panel de FactuON. Solo los usuarios con privilegios pueden crear o revocar claves. Copia el secreto completo de inmediato — solo se muestra una vez.

Realiza tu primera solicitud

Envía la clave API en el encabezado X-API-Key y llama al endpoint de health check para verificar la conectividad.

cURL

curl https://api.factuon.com/api/v1.0.1/public \
  -H "X-API-Key: fct_live_xxxxxxxx_yyyyyyyyyyyyyyyyyyyyyyyy"

Crea tu primera factura

Tu clave debe tener el permiso invoice.create. Usa el cuerpo de solicitud indicado en el endpoint Crear Factura.

Gestiona la respuesta

Verifica success: true y lee data.id para el recurso creado. En caso de error, revisa error.code para más detalles.

Autenticación

Cada solicitud a un endpoint protegido debe incluir una clave API válida.

fct_live_xxxxxxxx_yyyyyyyyyyyyyyyyyyyyyyyy

fct_ → prefijo de productolive_ → entornoxxxxxxxx_ → prefijo de búsquedayyy… → secreto aleatorio

🔑

Encabezado X-API-Key

Pasa la clave directamente en el encabezado personalizado:

HTTP

X-API-Key: fct_live_xxxxxxxx_yyyyyyyyyyyyyyyyyyyyyyyy

🛡

Authorization: Bearer

Alternativamente, usa el encabezado estándar Authorization:

HTTP

Authorization: Bearer fct_live_xxxxxxxx_yyyyyyyyyyyyyyyyyyyyyyyy

⚠️

Aviso de seguridad: Nunca expongas tu clave API en código del lado del cliente o en repositorios públicos. La clave en bruto nunca se almacena en FactuON — solo se guarda un hash seguro y un prefijo corto.

Permisos

Las claves API tienen permisos granulares usando notación de puntos.

Permiso	Descripción	Requerido para
◆invoice.create	Permite crear nuevas facturas de ventas	POST /invoice
◆organization.create	Permite crear nuevas organizaciones	POST /organization

✅

Un permiso faltante o insuficiente devuelve HTTP 403 Forbidden con el código de error FORBIDDEN.

IDs de Solicitud

Cada solicitud a la API tiene un identificador único para rastreo y soporte.

HTTP

# Optional: send your own ID
X-Request-Id: req_client_abc123

# If omitted, FactuON generates: req_<uuid>

El ID de solicitud se devuelve en el encabezado X-Request-Id y en el cuerpo bajo meta.requestId. Compártelo siempre con el soporte al reportar un problema.

Formato de Respuesta

Todas las respuestas de la API siguen un sobre JSON consistente.

Éxito

{
  "success": true,
  "message": "...",
  "data": { /* resource */ },
  "meta": {
    "requestId": "req_...",
    "requestTime": "2026-...",
    "apiVersion": "v1",
    "timestamp": "2026-..."
  }
}

Error

{
  "success": false,
  "error": {
    "code": "INVALID_API_KEY",
    "message": "Invalid API key"
  },
  "meta": {
    "requestId": "req_...",
    "apiVersion": "v1"
  }
}

Códigos de Error

Códigos legibles por máquina devueltos en error.code

HTTP	Código	Descripción
400	NAME_REQUIRED	Required field name is missing
400	NAME_FIELDS_REQUIRED	firstName and lastName required when typeCode is F
400	ORG_TYPE_REQUIRED	At least one organization type flag must be true
401	INVALID_API_KEY	API key is missing, invalid, revoked, or expired
403	FORBIDDEN	API key lacks the required scope
409	NAME_CONFLICT	Organization name already exists for this company
429	RATE_LIMITED	Too many requests — back off and retry
500	INTERNAL_SERVER_ERROR	Unexpected server error — contact support with requestId

Endpoints

Health Check

Crear Factura

Crear Organización