Documentación oficial · API v1.1.1

Conecta tus aplicaciones con FacturaOne mediante una API REST de solo lectura

Q: ¿La API de FacturaOne puede crear o modificar datos?

No. Esta versión es exclusivamente de lectura, solo admite peticiones GET y no ofrece operaciones POST, PUT, PATCH ni DELETE.

Q: ¿Cómo se autentica una integración con FacturaOne?

Mediante un token enviado en la cabecera X-API-Key o en Authorization: Bearer. El token no debe formar parte de la URL.

Q: ¿Qué datos se pueden consultar mediante la API?

Clientes, artículos, proveedores, familias, tipos, series, rutas, usuarios, impuestos, formas de pago, facturas emitidas y líneas de venta.

Q: ¿Cómo se recorren más de 200 registros?

Mediante paginación. Los recursos simples y las facturas usan next_after_id; las ventas utilizan un next_cursor opaco.

Consulta clientes, artículos, proveedores, facturas, ventas y catálogos auxiliares en formato JSON, con autenticación segura, filtros, paginación y respuestas documentadas.

Solo lectura HTTPS + JSON X-API-Key o Bearer Paginación estable

Empezar la integración Ver recursos disponibles

Última revisión: 26 de julio de 2026 · URL base: https://api.facturaone.com/v1/

FACTURAONE API

GET /v1/?resource=invoices X-API-Key: ••••••••••••••••

{ "ok": true, "resource": "invoices", "returned": 50, "has_more": true }

Activar la API y generar el token no tiene coste adicional.

El uso efectivo se factura según el consumo realizado y las tarifas vigentes. FacturaOne registra el volumen de peticiones y permite consultar el uso del mes actual y de meses anteriores desde el ERP.

URL basehttps://api.facturaone.com/v1/Todos los recursos se consultan mediante parámetros GET.

Versión1.1.1La versión también se devuelve en el JSON y en X-API-Version.

MétodoGETNo existen operaciones POST, PUT, PATCH ni DELETE.

AutenticaciónX-API-Key o BearerEl token debe viajar en una cabecera HTTP.

Formatoapplication/jsonContenido UTF-8 y estructura uniforme de errores.

Límite predeterminado50 registrosSe modifica con el parámetro limit.

Límite máximo200 registrosLos valores fuera de 1–200 se rechazan.

Periodo máximo366 díasProtección aplicada a facturas y ventas.

01 · Integración

Inicio rápido

La primera llamada recomendada consulta cinco clientes activos. El token se obtiene dentro de FacturaOne y debe guardarse como un secreto del servidor.

Primera petición

Utilice la cabecera X-API-Key y sustituya TU_TOKEN_API por el valor generado en su instalación.

curl -sS \
  -H "X-API-Key: TU_TOKEN_API" \
  -H "Accept: application/json" \
  "https://api.facturaone.com/v1/?resource=clients&active=1&limit=5&fields=client_id,client_name,client_nif,client_email"

Más ejemplos de autenticación y códigoBearer, PHP y Node.js

Authorization Bearer

Alternativa estándar para clientes que ya trabajan con autenticación Bearer.

curl -sS \
  -H "Authorization: Bearer TU_TOKEN_API" \
  -H "Accept: application/json" \
  "https://api.facturaone.com/v1/?resource=resources"

Cabecera directa

La opción recomendada en Postman, PHP, Node.js y procesos de servidor.

X-API-Key: TU_TOKEN_API

PHP con cURL

<?php
$url = 'https://api.facturaone.com/v1/?resource=clients&active=1&limit=5';
$token = getenv('FACTURAONE_API_TOKEN');

$ch = curl_init($url);
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 20,
    CURLOPT_HTTPHEADER => [
        'X-API-Key: ' . $token,
        'Accept: application/json',
    ],
]);

$body = curl_exec($ch);
if ($body === false) {
    throw new RuntimeException(curl_error($ch));
}

$status = (int) curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);
$payload = json_decode($body, true, 512, JSON_THROW_ON_ERROR);

if ($status < 200 || $status >= 300 || empty($payload['ok'])) {
    $message = $payload['message'] ?? ('Error HTTP ' . $status);
    $requestId = $payload['request_id'] ?? 'sin request_id';
    throw new RuntimeException($message . ' [' . $requestId . ']');
}

foreach ($payload['data'] as $client) {
    echo $client['client_id'] . ' - ' . $client['client_name'] . PHP_EOL;
}

Node.js 18+ con fetch

// Node.js 18+ — utilícelo en backend, nunca en JavaScript público.
const url = 'https://api.facturaone.com/v1/?resource=clients&active=1&limit=5';
const token = process.env.FACTURAONE_API_TOKEN;

const response = await fetch(url, {
  method: 'GET',
  headers: {
    'X-API-Key': token,
    'Accept': 'application/json'
  }
});

const payload = await response.json();

if (!response.ok || payload.ok !== true) {
  throw new Error(
    `${payload.message || `Error HTTP ${response.status}`} ` +
    `[${payload.request_id || 'sin request_id'}]`
  );
}

for (const client of payload.data) {
  console.log(client.client_id, client.client_name);
}

No coloque el token en la URL

La API exige una cabecera HTTP. Use cURL, Postman, Insomnia o código de servidor. Enviar el token como parámetro lo expondría en historiales, analítica y registros.

02 · Convenciones

Reglas globales de consulta

Todos los recursos comparten una estructura coherente de autenticación, filtros, límites y errores.

Parámetro	Alias	Formato	Comportamiento
`resource`	`recurso`	Nombre de recurso	Selecciona el recurso. Si se omite, se devuelve `resources`.
`limit`	`limite`	Entero de 1 a 200	Por defecto devuelve 50 registros. Se combina con `after_id` o `cursor`.
`search`	`buscar`	Texto de hasta 100 caracteres	Búsqueda parcial en los campos autorizados de cada recurso.
`date_from`	`fecha_desde`, `fechaini`, `desde_fecha`	`YYYY-MM-DD`	Fecha inicial para recursos complejos. Debe enviarse con `date_to`.
`date_to`	`fecha_hasta`, `fechafin`, `hasta_fecha`	`YYYY-MM-DD`	Fecha final inclusiva. El intervalo no puede superar 366 días.

Fechas seguras

Si no se indican fechas en invoices o sales, se consulta desde el primer día del mes actual hasta hoy.

Identificadores

Los filtros de ID usan enteros positivos. El valor 0 o la ausencia del parámetro suele equivaler a no filtrar.

Un solo valor

Cada parámetro debe contener un valor escalar. Formatos como id[]=1 generan BAD_PARAMETER.

Estructura común de una respuesta correcta

ok: true cuando la consulta se ha completado.
read_only: Siempre true.
version: Versión de la API que respondió.
account: Cuenta o instalación identificada por el token.
resource: Nombre canónico del recurso consultado.
filters: Filtros normalizados y realmente aplicados.
pagination: Estado de la página y clave de continuación.
data: Registros devueltos.
request_id: Identificador de diagnóstico, también enviado en X-Request-ID.

La instalación se identifica mediante el token

El consumidor no envía el nombre de la base de datos ni un identificador de empresa. La API localiza la instalación asociada y devuelve su nombre en account. Las fechas predeterminadas se calculan con la zona horaria Europe/Madrid.

03 · Datos disponibles

Recursos y catálogos

La API expone maestros de clientes, artículos y proveedores; catálogos auxiliares; facturas emitidas; y líneas de venta procedentes de facturas y albaranes.

Descubrimiento automático: `resource=resources`

Esta llamada devuelve los recursos autorizados, su clave primaria, campos, filtros, paginación y límites. Es la primera consulta recomendada para un conector.

curl -sS \
  -H "X-API-Key: TU_TOKEN_API" \
  -H "Accept: application/json" \
  "https://api.facturaone.com/v1/?resource=resources"

Resumen de recursos

Recurso	Alias	Clave primaria	active	Finalidad
`clients`	clientes	`client_id`	Sí	Maestro de clientes, datos fiscales y comerciales actuales.
`items`	articulos	`item_lookup_id`	Sí	Catálogo actual de artículos, descripción, precios, stock y clasificación.
`suppliers`	proveedores	`proveedor_id`	Sí	Maestro de proveedores y sus datos fiscales, de contacto y contables.
`families`	familias	`familia_id`	No	Catálogo de familias utilizado por los artículos y por el filtro family_id de ventas.
`item_types`	tipos_articulo	`tipo_articulo_id`	Sí	Clasificación por tipo de artículo utilizada por item_type_id.
`invoice_series`	series_facturaseries	`invoice_group_id`	Sí	Series o grupos de facturación utilizados por series_id.
`invoice_types`	tipos_factura	`tipo_factura_id`	Sí	Catálogo de tipos de factura utilizado por invoice_type_id.
`routes`	rutas	`ruta_id`	Sí	Rutas comerciales o de reparto utilizadas por route_id.
`users`	usuarios	`user_id`	No	Usuarios disponibles para filtros comerciales. Excluye usuarios configurados como solo catálogo.
`tax_rates`	impuestos	`tax_rate_id`	Sí	Tipos impositivos utilizados por artículos, facturas y el filtro tax_rate_id.
`payment_methods`	formas_pago	`payment_method_id`	No	Catálogo de formas de pago utilizado por facturas y pagos.
`invoices`	issued_invoicesfacturasfacturas_emitidas	`invoice_id`	No	Facturas emitidas con importes, impuestos, validez y pagos opcionales.
`sales`	sales_linesitem_salesventasventas_articulossalida_articulos	`cursor compuesto`	No	Líneas vendidas desde facturas y/o albaranes, con coste, beneficio y margen históricos.

Filtros de los recursos simples

Filtro	Valores	Descripción
`id`	Entero > 0	Devuelve un registro concreto por la clave primaria.
`active` / `activo`	`0`, `1`, `all`	Solo está disponible en recursos con una columna activa configurada.
`search` / `buscar`	Texto ≤ 100	Búsqueda parcial sobre los campos documentados de cada recurso.
`fields` / `campos`	Lista separada por comas	Reduce la respuesta. La clave primaria se añade automáticamente.
`after_id` / `desde_id`	Entero ≥ 0	Continúa después de la última clave. No puede combinarse con `id`.
`limit` / `limite`	1–200	Por defecto 50. La API consulta un registro adicional para calcular `has_more`.

fields solo existe en recursos simples

invoices y sales devuelven siempre una estructura fija y documentada.

Cómo obtener los identificadores usados por los filtros

Filtro	Recurso que debe consultar	Campo a utilizar
`client_id`	`clients`	`client_id`
`user_id`, `owner_user_id`	`users`	`user_id`
`route_id`	`routes`	`ruta_id`
`series_id`	`invoice_series`	`invoice_group_id`
`invoice_type_id`	`invoice_types`	`tipo_factura_id`
`family_id`	`families`	`familia_id`
`item_id`	`items`	`item_lookup_id`
`item_type_id`	`item_types`	`tipo_articulo_id`
`tax_rate_id`	`tax_rates`	`tax_rate_id`
`payment_method_id`	`payment_methods`	`payment_method_id`

Descripción actual e histórica del artículo

items.item_description devuelve la descripción actual del catálogo. En cambio, sales.item.description conserva la descripción guardada en la línea del documento.

Diccionario completo de recursos simples

Abra cada recurso para ver alias, búsqueda, llamada recomendada y campos autorizados.

Clientes — clients24 campos autorizados

Maestro de clientes, datos fiscales y comerciales actuales.

Recurso: clients
Alias: clientes
Clave primaria: client_id
Filtro active: 0, 1, all o todos

Campos usados por search

client_nameclient_name_comercialclient_nifclient_email

Ejemplo recomendado

curl -sS \
  -H "X-API-Key: TU_TOKEN_API" \
  -H "Accept: application/json" \
  "https://api.facturaone.com/v1/?resource=clients&active=1&limit=5&fields=client_id,client_name,client_nif,client_email,client_active"

Campos permitidos en fields

Campo	Significado
`client_id`	Identificador interno del cliente.
`client_date_created`	Fecha de creación del cliente.
`client_date_modified`	Fecha de la última modificación.
`client_numid`	Número o código interno asignado al cliente.
`client_name`	Nombre fiscal o razón social.
`client_name_comercial`	Nombre comercial.
`client_nif`	NIF, CIF o identificador fiscal.
`client_address_1`	Primera línea de dirección.
`client_address_2`	Segunda línea de dirección.
`client_city`	Población.
`client_state`	Provincia, estado o región.
`client_zip`	Código postal.
`client_country`	País.
`client_contacto`	Persona de contacto.
`client_phone`	Teléfono principal.
`client_mobile`	Teléfono móvil.
`client_email`	Correo electrónico.
`client_web`	Sitio web.
`client_active`	Indicador de cliente activo.
`client_tarifa`	Tarifa de precios asignada.
`client_ruta_id`	Identificador de la ruta actual del cliente.
`user_id`	Identificador del propietario actual del cliente.
`recargoequivalencia`	Configuración de recargo de equivalencia.
`retencionprofesional`	Configuración de retención profesional.

Artículos — items29 campos autorizados

Catálogo actual de artículos, descripción, precios, stock y clasificación.

Recurso: items
Alias: articulos
Clave primaria: item_lookup_id
Filtro active: 0, 1, all o todos

Campos usados por search

item_nameitem_skuitem_barcode

Ejemplo recomendado

curl -sS \
  -H "X-API-Key: TU_TOKEN_API" \
  -H "Accept: application/json" \
  "https://api.facturaone.com/v1/?resource=items&active=1&limit=5&fields=item_lookup_id,item_name,item_description,item_sku,item_barcode,item_stock,item_price,item_familia"

Campos permitidos en fields

Campo	Significado
`item_lookup_id`	Identificador interno del artículo.
`item_create_date`	Fecha de creación del artículo.
`item_date_ultima_compra`	Fecha de la última compra registrada.
`item_date_ultima_venta`	Fecha de la última venta registrada.
`item_active`	Indicador de artículo activo.
`item_web_activate`	Indicador de publicación o uso web.
`item_erp_activate`	Indicador de disponibilidad en el ERP.
`item_pos_activate`	Indicador de disponibilidad en el punto de venta.
`item_nosale`	Indicador de artículo no vendible.
`item_is_stock`	Indica si el artículo se controla por stock.
`item_stock`	Stock actual almacenado en el catálogo.
`item_name`	Nombre actual del artículo; en algunas cuentas se utiliza como código interno.
`item_description`	Descripción actual de la ficha del artículo; se diferencia de la descripción histórica guardada en cada línea de venta.
`item_sku`	Referencia o SKU.
`item_barcode`	Código de barras.
`item_unidad`	Unidad de medida.
`item_cost_price`	Precio de coste actual.
`item_price`	Precio principal de venta.
`item_tarifa2`	Precio de la tarifa 2.
`item_tarifa3`	Precio de la tarifa 3.
`item_tarifa4`	Precio de la tarifa 4.
`item_tarifa5`	Precio de la tarifa 5.
`item_tax_rate_id`	Identificador del impuesto asignado.
`item_familia`	Identificador de la familia actual.
`item_subfamilia`	Identificador de la subfamilia actual.
`item_tipoarticuloid`	Identificador del tipo de artículo actual.
`item_formato_id`	Identificador del formato predeterminado.
`image`	Nombre o referencia de imagen guardada.
`item_imageurl`	URL de imagen asociada.

Proveedores — suppliers23 campos autorizados

Maestro de proveedores y sus datos fiscales, de contacto y contables.

Recurso: suppliers
Alias: proveedores
Clave primaria: proveedor_id
Filtro active: 0, 1, all o todos

Campos usados por search

client_nameclient_name_comercialclient_nifclient_email

Ejemplo recomendado

curl -sS \
  -H "X-API-Key: TU_TOKEN_API" \
  -H "Accept: application/json" \
  "https://api.facturaone.com/v1/?resource=suppliers&active=1&limit=5&fields=proveedor_id,client_name,client_nif,client_email,client_active"

Campos permitidos en fields

Campo	Significado
`proveedor_id`	Identificador interno del proveedor.
`client_date_created`	Fecha de creación.
`client_date_modified`	Fecha de la última modificación.
`client_numid`	Número o código interno.
`client_name`	Nombre fiscal o razón social.
`client_name_comercial`	Nombre comercial.
`client_nif`	NIF, CIF o identificador fiscal.
`client_address_1`	Primera línea de dirección.
`client_address_2`	Segunda línea de dirección.
`client_city`	Población.
`client_state`	Provincia, estado o región.
`client_zip`	Código postal.
`client_country`	País.
`client_contacto`	Persona de contacto.
`client_phone`	Teléfono principal.
`client_mobile`	Teléfono móvil.
`client_email`	Correo electrónico.
`client_web`	Sitio web.
`client_active`	Indicador de proveedor activo.
`client_compras`	Indicador de uso del proveedor en compras.
`client_gastos`	Indicador de uso del proveedor en gastos.
`client_contable`	Indicador de uso contable del proveedor.
`recargoequivalencia`	Configuración de recargo de equivalencia.

Familias de artículos — families4 campos autorizados

Catálogo de familias utilizado por los artículos y por el filtro family_id de ventas.

Recurso: families
Alias: familias
Clave primaria: familia_id
Filtro active: No admitido

Campos usados por search

familia_name

Filtro active no disponible

Enviar active=0 o active=1 en este recurso produce FILTER_NOT_SUPPORTED.

Ejemplo recomendado

curl -sS \
  -H "X-API-Key: TU_TOKEN_API" \
  -H "Accept: application/json" \
  "https://api.facturaone.com/v1/?resource=families&limit=100&fields=familia_id,familia_name,familia_web_activate"

Campos permitidos en fields

Campo	Significado
`familia_id`	Identificador de la familia.
`familia_web_activate`	Indicador de publicación o uso web.
`familia_name`	Nombre interno de la familia.
`familia_name_tienda`	Nombre de la familia mostrado en tienda.

Tipos de artículo — item_types4 campos autorizados

Clasificación por tipo de artículo utilizada por item_type_id.

Recurso: item_types
Alias: tipos_articulo
Clave primaria: tipo_articulo_id
Filtro active: 0, 1, all o todos

Campos usados por search

tipo_articulo_nametipo_articulo_descripcion

Ejemplo recomendado

curl -sS \
  -H "X-API-Key: TU_TOKEN_API" \
  -H "Accept: application/json" \
  "https://api.facturaone.com/v1/?resource=item_types&active=1&limit=100"

Campos permitidos en fields

Campo	Significado
`tipo_articulo_id`	Identificador del tipo de artículo.
`tipo_articulo_activate`	Indicador de tipo activo.
`tipo_articulo_name`	Nombre del tipo.
`tipo_articulo_descripcion`	Descripción del tipo.

Series de factura — invoice_series7 campos autorizados

Series o grupos de facturación utilizados por series_id.

Recurso: invoice_series
Alias: series_facturaseries
Clave primaria: invoice_group_id
Filtro active: 0, 1, all o todos

Campos usados por search

invoice_group_nameinvoice_group_name_menuinvoice_group_prefix

Ejemplo recomendado

curl -sS \
  -H "X-API-Key: TU_TOKEN_API" \
  -H "Accept: application/json" \
  "https://api.facturaone.com/v1/?resource=invoice_series&active=1&limit=100"

Campos permitidos en fields

Campo	Significado
`invoice_group_id`	Identificador de la serie o grupo.
`invoice_group_activate`	Indicador de serie activa.
`invoice_group_name`	Nombre de la serie.
`invoice_group_name_menu`	Nombre corto o mostrado en menús.
`invoice_group_prefix`	Prefijo de numeración.
`invoice_group_prefix_year`	Configuración de inclusión del año en el prefijo.
`invoice_group_prefix_month`	Configuración de inclusión del mes en el prefijo.

Tipos de factura — invoice_types4 campos autorizados

Catálogo de tipos de factura utilizado por invoice_type_id.

Recurso: invoice_types
Alias: tipos_factura
Clave primaria: tipo_factura_id
Filtro active: 0, 1, all o todos

Campos usados por search

tipo_factura_nametipo_factura_descripcion

Ejemplo recomendado

curl -sS \
  -H "X-API-Key: TU_TOKEN_API" \
  -H "Accept: application/json" \
  "https://api.facturaone.com/v1/?resource=invoice_types&active=1&limit=100"

Campos permitidos en fields

Campo	Significado
`tipo_factura_id`	Identificador del tipo de factura.
`tipo_factura_activate`	Indicador de tipo activo.
`tipo_factura_name`	Nombre del tipo de factura.
`tipo_factura_descripcion`	Descripción del tipo.

Rutas — routes3 campos autorizados

Rutas comerciales o de reparto utilizadas por route_id.

Recurso: routes
Alias: rutas
Clave primaria: ruta_id
Filtro active: 0, 1, all o todos

Campos usados por search

ruta_name

Ejemplo recomendado

curl -sS \
  -H "X-API-Key: TU_TOKEN_API" \
  -H "Accept: application/json" \
  "https://api.facturaone.com/v1/?resource=routes&active=1&limit=100"

Campos permitidos en fields

Campo	Significado
`ruta_id`	Identificador de la ruta.
`ruta_active`	Indicador de ruta activa.
`ruta_name`	Nombre de la ruta.

Usuarios y comerciales — users4 campos autorizados

Usuarios disponibles para filtros comerciales. Excluye usuarios configurados como solo catálogo.

Recurso: users
Alias: usuarios
Clave primaria: user_id
Filtro active: No admitido

Campos usados por search

user_nameuser_company

Filtro active no disponible

Enviar active=0 o active=1 en este recurso produce FILTER_NOT_SUPPORTED.

Usuarios solo catálogo excluidos

El recurso aplica internamente acceso_solo_catalogo = 0.

Ejemplo recomendado

curl -sS \
  -H "X-API-Key: TU_TOKEN_API" \
  -H "Accept: application/json" \
  "https://api.facturaone.com/v1/?resource=users&limit=100&fields=user_id,user_name,user_company,user_type"

Campos permitidos en fields

Campo	Significado
`user_id`	Identificador del usuario.
`user_name`	Nombre del usuario o comercial.
`user_company`	Empresa asociada al usuario.
`user_type`	Tipo de usuario.

Impuestos — tax_rates6 campos autorizados

Tipos impositivos utilizados por artículos, facturas y el filtro tax_rate_id.

Recurso: tax_rates
Alias: impuestos
Clave primaria: tax_rate_id
Filtro active: 0, 1, all o todos

Campos usados por search

tax_rate_name

Ejemplo recomendado

curl -sS \
  -H "X-API-Key: TU_TOKEN_API" \
  -H "Accept: application/json" \
  "https://api.facturaone.com/v1/?resource=tax_rates&active=1&limit=100"

Campos permitidos en fields

Campo	Significado
`tax_rate_id`	Identificador del tipo impositivo.
`tax_rate_active`	Indicador de impuesto activo.
`tax_rate_name`	Nombre del impuesto.
`tax_rate_tipo`	Clasificación interna del impuesto.
`tax_rate_percent`	Porcentaje impositivo.
`recargoequivalencia`	Porcentaje de recargo de equivalencia asociado.

Formas de pago — payment_methods2 campos autorizados

Catálogo de formas de pago utilizado por facturas y pagos.

Recurso: payment_methods
Alias: formas_pago
Clave primaria: payment_method_id
Filtro active: No admitido

Campos usados por search

payment_method_name

Filtro active no disponible

Enviar active=0 o active=1 en este recurso produce FILTER_NOT_SUPPORTED.

Ejemplo recomendado

curl -sS \
  -H "X-API-Key: TU_TOKEN_API" \
  -H "Accept: application/json" \
  "https://api.facturaone.com/v1/?resource=payment_methods&limit=100"

Campos permitidos en fields

Campo	Significado
`payment_method_id`	Identificador de la forma de pago.
`payment_method_name`	Nombre de la forma de pago.

Ejemplo de respuesta de resourcesFragmento ilustrativo

{
  "ok": true,
  "read_only": true,
  "version": "1.1.1",
  "account": "Empresa de ejemplo",
  "defaults": {
    "limit": 50,
    "maximum_limit": 200,
    "complex_date_range": "mes_actual",
    "maximum_date_range_days": 366
  },
  "resources": [
    {
      "resource": "clients",
      "nombre": "clientes",
      "description": "Maestro de clientes.",
      "primary_key": "client_id",
      "fields": ["client_id", "client_name", "..."],
      "filters": ["id", "active", "search", "after_id", "limit", "fields"],
      "pagination": "after_id",
      "maximum_limit": 200
    }
  ],
  "request_id": "a1b2c3d4e5f60708"
}

Ejemplo de respuesta de un recurso simpleclients con fields y paginación

{
  "ok": true,
  "read_only": true,
  "version": "1.1.1",
  "account": "Empresa de ejemplo",
  "resource": "clients",
  "nombre": "clientes",
  "filters": {
    "id": null,
    "active": "1",
    "search": null,
    "after_id": 0,
    "limit": 1,
    "fields": ["client_id", "client_name", "client_nif", "client_email"]
  },
  "pagination": {
    "returned": 1,
    "has_more": true,
    "next_after_id": 12
  },
  "data": [
    {
      "client_id": 12,
      "client_name": "CLIENTE DE EJEMPLO, S.L.",
      "client_nif": "B12345678",
      "client_email": "[email protected]"
    }
  ],
  "request_id": "a1b2c3d4e5f60708"

}

04 · Documentos

Facturas emitidas — `resource=invoices`

Consulta estructurada de cabeceras de factura, cliente, serie, estado, validez, importes, impuestos y pagos opcionales.

Alias aceptados

invoicesissued_invoicesfacturasfacturas_emitidas

Para nuevas integraciones use preferentemente el nombre canónico invoices.

Periodo predeterminado

Sin fechas y sin id: desde el primer día del mes actual hasta hoy.

Impuestos

Siempre se devuelven en data[].taxes como colección estructurada.

Pagos

Solo aparecen con include_payments=1 para evitar carga innecesaria.

Filtros disponibles

Parámetro	Alias	Formato	Predeterminado	Descripción
`id`	`invoice_id`	Entero mayor que 0	Sin filtro	Obtiene una factura concreta. Cuando se usa, no se aplica el periodo predeterminado.
`after_id`	`desde_id`	Entero igual o mayor que 0	0	Paginación ascendente por invoice_id. No puede combinarse con id.
`date_from`	`fecha_desde` `fechaini` `desde_fecha`	YYYY-MM-DD	Primer día del mes actual	Fecha de emisión inicial, inclusiva. Debe enviarse junto con date_to.
`date_to`	`fecha_hasta` `fechafin` `hasta_fecha`	YYYY-MM-DD	Fecha actual	Fecha de emisión final, inclusiva. El intervalo máximo es de 366 días.
`client_id`	`cliente`	Entero mayor que 0	Sin filtro	Filtra por el cliente de la factura.
`user_id`	`usuario`	Entero mayor que 0	Sin filtro	Filtra por el usuario o comercial guardado en la factura.
`owner_user_id`	`propietario_user_id`	Entero mayor que 0	Sin filtro	Filtra por el propietario actual del cliente.
`route_id`	`ruta_id`	Entero mayor que 0	Sin filtro	Filtra por la ruta actual del cliente.
`series_id`	`serie` `invoice_group_id`	Entero mayor que 0	Sin filtro	Filtra por serie o grupo de facturación.
`invoice_type_id`	`tipo_factura` `tipofactura`	Entero mayor que 0	Sin filtro	Filtra por tipo de factura.
`status`	`estado`	Enum	all	all, draft, sent, viewed, paid o pending. También admite 1 a 6 como alias históricos.
`validity`	`validez`	Enum	all	all, valid, cancelled, substituted o invalid.
`search`	`buscar`	Texto, máximo 100 caracteres	Sin búsqueda	Busca por número, referencia, nombre o NIF del cliente, tanto en la factura como en el maestro actual.
`include_payments`	`incluir_pagos`	Booleano 0/1	0	Añade data[].payments. También acepta true/false, yes/no y si/sí.
`limit`	`limite`	Entero de 1 a 200	50	Número máximo de facturas por página.

Valores de status

Valor	Comportamiento
`all`	Sin filtro de estado.
`draft` / `1`	`invoice_status_id = 1`.
`sent` / `2`	`invoice_status_id = 2`.
`viewed` / `3`	`invoice_status_id = 3`.
`paid` / `4`	Saldo absoluto menor o igual que 0,01.
`pending` / `5` / `6`	Saldo absoluto mayor que 0,01; incluye saldo pendiente y saldo a favor.

Valores de validity

Valor	Comportamiento
`all`	Incluye válidas, anuladas y sustituidas.
`valid`	No anulada y no sustituida.
`cancelled`	Anulada.
`substituted`	Sustituida.
`invalid`	Anulada o sustituida.

Alias de valores por compatibilidad

status: todo, todos, borrador, enviados, vistos, pagados y pendientes. validity: todos, válidas, canceled, anuladas, sustituidas e inválidas. Para integraciones nuevas utilice los valores canónicos en inglés.

status=6 no elimina el límite de fechas

El valor histórico 6 se normaliza a pending. Para pendientes antiguos recorra periodos explícitos de hasta 366 días.

Estado documental y estado de cobro son distintos

status.code representa el estado documental. El cobro se informa en status.payment_status: paid, pending o credit.

Ejemplos de consulta

Consultas habituales de facturasPeriodo, ID, pagos, pendientes, búsqueda y página siguiente

Facturas del periodo

Hasta 100 facturas emitidas entre dos fechas.

curl -sS \
  -H "X-API-Key: TU_TOKEN_API" \
  -H "Accept: application/json" \
  "https://api.facturaone.com/v1/?resource=invoices&date_from=2026-07-01&date_to=2026-07-26&limit=100"

Factura exacta por ID

Permite recuperar una factura antigua sin enviar fechas.

curl -sS \
  -H "X-API-Key: TU_TOKEN_API" \
  -H "Accept: application/json" \
  "https://api.facturaone.com/v1/?resource=invoices&id=12345"

Factura con pagos

Añade la colección payments.

curl -sS \
  -H "X-API-Key: TU_TOKEN_API" \
  -H "Accept: application/json" \
  "https://api.facturaone.com/v1/?resource=invoices&id=12345&include_payments=1"

Facturas válidas y pendientes

Combina saldo pendiente con exclusión de anuladas y sustituidas.

curl -sS \
  -H "X-API-Key: TU_TOKEN_API" \
  -H "Accept: application/json" \
  "https://api.facturaone.com/v1/?resource=invoices&date_from=2026-01-01&date_to=2026-12-31&status=pending&validity=valid&limit=100"

Cliente y serie

Los ID se obtienen desde clients e invoice_series.

curl -sS \
  -H "X-API-Key: TU_TOKEN_API" \
  -H "Accept: application/json" \
  "https://api.facturaone.com/v1/?resource=invoices&date_from=2026-01-01&date_to=2026-12-31&client_id=949&series_id=1"

Búsqueda por texto

Busca por número, referencia, nombre o NIF.

curl -sS \
  -H "X-API-Key: TU_TOKEN_API" \
  -H "Accept: application/json" \
  "https://api.facturaone.com/v1/?resource=invoices&date_from=2026-01-01&date_to=2026-12-31&search=garcia"

Página siguiente

Conserve exactamente los mismos filtros y añada next_after_id.

curl -sS \
  -H "X-API-Key: TU_TOKEN_API" \
  -H "Accept: application/json" \
  "https://api.facturaone.com/v1/?resource=invoices&date_from=2026-01-01&date_to=2026-12-31&status=pending&validity=valid&limit=100&after_id=12345"

Datos históricos y actuales

Nombre, NIF y datos fiscales principales priorizan la instantánea guardada en la factura.
Dirección estructurada, propietario y ruta proceden del maestro actual del cliente.
Importes e impuestos corresponden al documento.
Anuladas y sustituidas no se ocultan por defecto: se identifican en validity.

Origen de impuestos

La fuente principal es fi_invoice_tax_rates. Para facturas históricas sin desglose, la API agrupa las líneas y marca el origen.

source=invoice_tax_ratessource=invoice_items_fallback

Diccionario de campos de data[]

Identificación y fechas11 rutas documentadas

Ruta JSON	Tipo	Significado
`invoice_id`	`integer`	Identificador de la factura.
`number`	`string`	Número completo de factura.
`reference`	`string\|null`	Referencia externa o interna.
`description`	`string\|null`	Descripción de la operación.
`origin`	`string\|null`	Origen indicado en la factura.
`incoterms`	`string\|null`	Incoterm asociado.
`dates.issued`	`date\|null`	Fecha de emisión.
`dates.operation`	`date\|null`	Fecha de operación.
`dates.due`	`date\|null`	Fecha de vencimiento.
`dates.modified_at`	`datetime\|null`	Última modificación.
`dates.confirmed_at`	`datetime\|null`	Fecha y hora de confirmación.

Estado y validez11 rutas documentadas

Ruta JSON	Tipo	Significado
`status.id`	`integer`	Estado interno de la factura.
`status.code`	`string`	draft, sent, viewed o unknown según status.id.
`status.confirmed`	`boolean`	Indica si la factura está confirmada.
`status.payment_status`	`string`	paid, pending o credit según el saldo.
`validity.is_valid`	`boolean`	true cuando no está anulada ni sustituida.
`validity.cancelled`	`boolean`	Indica anulación TicketBAI/VeriFactu u otra anulación registrada.
`validity.cancellation_system`	`string\|null`	verifactu, ticketbai, unspecified o null.
`validity.substituted`	`boolean`	Indica que la factura fue sustituida.
`validity.rectifies_invoice_id`	`integer\|null`	ID de la factura original que este documento rectifica, almacenado en invoice_rec_id.
`validity.rectified_from_invoice_id`	`integer\|null`	ID adicional relacionado con el origen de la rectificación, almacenado en invoice_rec_from_invoice_id.
`validity.rectification_type`	`integer`	Código interno del tipo de rectificación.

Factura electrónica, serie y tipo10 rutas documentadas

Ruta JSON	Tipo	Significado
`electronic_invoice.ticketbai_type`	`string\|null`	Tipo TicketBAI.
`electronic_invoice.ticketbai_number`	`string\|null`	Número o identificador TicketBAI.
`electronic_invoice.verifactu_status`	`string\|null`	Estado VeriFactu almacenado.
`electronic_invoice.verifactu_csv`	`string\|null`	CSV VeriFactu.
`electronic_invoice.verifactu_qr_url`	`string\|null`	URL del QR VeriFactu.
`electronic_invoice.verifactu_validation`	`string\|null`	URL de validación VeriFactu.
`series.invoice_group_id`	`integer`	ID de serie o grupo.
`series.name`	`string\|null`	Nombre de la serie.
`invoice_type.invoice_type_id`	`integer`	ID del tipo de factura.
`invoice_type.name`	`string\|null`	Nombre del tipo de factura.

Participantes y cliente25 rutas documentadas

Ruta JSON	Tipo	Significado
`seller`	`object\|null`	Comercial de la factura.
`seller.user_id`	`integer\|null`	ID del comercial cuando seller no es null.
`seller.name`	`string\|null`	Nombre del comercial.
`owner`	`object\|null`	Propietario actual del cliente.
`owner.user_id`	`integer\|null`	ID del propietario cuando owner no es null.
`owner.name`	`string\|null`	Nombre del propietario actual.
`route`	`object\|null`	Ruta actual del cliente.
`route.route_id`	`integer\|null`	ID de la ruta cuando route no es null.
`route.name`	`string\|null`	Nombre de la ruta actual.
`client.client_id`	`integer`	ID del cliente.
`client.name`	`string\|null`	Nombre guardado en la factura; si falta, nombre actual. En factura simplificada de contado se devuelve una etiqueta genérica.
`client.nif`	`string\|null`	NIF guardado en la factura; si falta, NIF actual. En factura simplificada de contado se devuelve vacío/null.
`client.fiscal_data`	`string\|null`	Datos fiscales textuales guardados en la factura.
`client.address_1`	`string\|null`	Dirección actual del maestro de clientes.
`client.address_2`	`string\|null`	Segunda línea de dirección actual.
`client.postal_code`	`string\|null`	Código postal actual.
`client.city`	`string\|null`	Población actual.
`client.province`	`string\|null`	Provincia o región actual.
`client.country`	`string\|null`	País actual.
`client.phone`	`string\|null`	Teléfono actual.
`client.mobile`	`string\|null`	Móvil actual.
`client.email`	`string\|null`	Email actual.
`issuer.name`	`string\|null`	Nombre del emisor guardado en la factura.
`issuer.nif`	`string\|null`	NIF del emisor guardado en la factura.
`issuer.fiscal_data`	`string\|null`	Datos fiscales del emisor guardados en la factura.

Configuración e importes23 rutas documentadas

Ruta JSON	Tipo	Significado
`payment_method_id`	`integer`	Forma de pago de la factura.
`bank_method_id`	`integer`	Cuenta o método bancario asociado.
`tax_exemption_cause`	`string\|null`	Causa de exención fiscal.
`display_options.hide_taxes`	`boolean`	Indica que la factura oculta impuestos en su presentación.
`display_options.hide_line_price`	`boolean`	Indica que la factura oculta precios de línea.
`amounts.item_subtotal`	`number`	Subtotal de líneas.
`amounts.item_tax_total`	`number`	Impuesto calculado en líneas.
`amounts.tax_total`	`number`	Total de impuestos de la factura.
`amounts.surcharge_total`	`number`	Recargo de equivalencia.
`amounts.irpf_total`	`number`	Importe de IRPF.
`amounts.irpf_percent`	`number`	Porcentaje de IRPF.
`amounts.retention_total`	`number`	Importe de retención.
`amounts.retention_percent`	`number`	Porcentaje de retención.
`amounts.supplies`	`number`	Suplidos.
`amounts.irpf_on_total`	`number`	IRPF calculado sobre el total.
`amounts.irpf_on_total_percent`	`number`	Porcentaje de IRPF sobre el total.
`amounts.total`	`number`	Total de la factura.
`amounts.paid`	`number`	Importe pagado.
`amounts.balance`	`number`	Saldo pendiente; negativo implica saldo a favor.
`amounts.profit`	`number`	Beneficio almacenado.
`currency.symbol`	`string\|null`	Símbolo de la divisa.
`currency.exchange_rate`	`number\|null`	Tipo de cambio; null cuando no se aplica.
`currency.converted_total`	`number\|null`	Total convertido; null cuando no se aplica.

Impuestos y pagos24 rutas documentadas

Ruta JSON	Tipo	Significado
`taxes[]`	`array`	Desglose fiscal de la factura.
`taxes[].invoice_tax_rate_id`	`integer\|null`	ID del desglose; null en recuperación histórica.
`taxes[].tax_rate_id`	`integer`	ID del tipo impositivo.
`taxes[].name`	`string\|null`	Nombre del impuesto.
`taxes[].percent`	`number`	Porcentaje de impuesto.
`taxes[].base`	`number`	Base del tipo impositivo.
`taxes[].tax_amount`	`number`	Cuota del impuesto.
`taxes[].surcharge_percent`	`number`	Porcentaje de recargo.
`taxes[].surcharge_amount`	`number`	Cuota de recargo.
`taxes[].include_item_tax`	`boolean`	Indicador almacenado en el desglose.
`taxes[].source`	`string`	invoice_tax_rates o invoice_items_fallback.
`payments[]`	`array opcional`	Solo aparece con include_payments=1.
`payments[].payment_id`	`integer`	ID del pago.
`payments[].number`	`string\|null`	Número o referencia del pago.
`payments[].date`	`date\|null`	Fecha del pago.
`payments[].amount`	`number`	Importe del pago.
`payments[].paid`	`boolean`	Indicador de pago realizado.
`payments[].returned`	`boolean`	Indicador de pago devuelto.
`payments[].payment_method_id`	`integer`	ID de forma de pago.
`payments[].payment_method_name`	`string\|null`	Nombre de la forma de pago.
`payments[].bank_method_id`	`integer`	ID del método o cuenta bancaria.
`payments[].bank_method_name`	`string\|null`	Nombre del método bancario.
`payments[].bank_accounting_code`	`string\|null`	Código contable bancario.
`payments[].note`	`string\|null`	Nota del pago, limitada a 1.000 caracteres.

Ejemplo completo de respuesta de una facturaIncluye impuestos y payments

Valores ilustrativos

La colección payments solo aparece con include_payments=1.

{
  "ok": true,
  "read_only": true,
  "version": "1.1.1",
  "account": "Empresa de ejemplo",
  "resource": "invoices",
  "nombre": "facturas_emitidas",
  "filters": {
    "id": 12345,
    "date_from": null,
    "date_to": null,
    "date_defaulted": false,
    "client_id": null,
    "user_id": null,
    "owner_user_id": null,
    "route_id": null,
    "series_id": null,
    "invoice_type_id": null,
    "status": "all",
    "validity": "all",
    "search": null,
    "include_payments": true,
    "after_id": 0,
    "limit": 50
  },
  "pagination": {
    "returned": 1,
    "has_more": false,
    "next_after_id": null
  },
  "data": [
    {
      "invoice_id": 12345,
      "number": "F/2026/00125",
      "reference": "PED-7781",
      "description": "Venta de material",
      "origin": null,
      "incoterms": null,
      "dates": {
        "issued": "2026-07-10",
        "operation": "2026-07-10",
        "due": "2026-08-09",
        "modified_at": "2026-07-10 12:41:03",
        "confirmed_at": "2026-07-10 12:40:55"
      },
      "status": {
        "id": 2,
        "code": "sent",
        "confirmed": true,
        "payment_status": "pending"
      },
      "validity": {
        "is_valid": true,
        "cancelled": false,
        "cancellation_system": null,
        "substituted": false,
        "rectifies_invoice_id": null,
        "rectified_from_invoice_id": null,
        "rectification_type": 0
      },
      "electronic_invoice": {
        "ticketbai_type": null,
        "ticketbai_number": null,
        "verifactu_status": "REGISTRADA",
        "verifactu_csv": "CSV-DE-EJEMPLO",
        "verifactu_qr_url": "https://ejemplo.test/qr",
        "verifactu_validation": "https://ejemplo.test/validar"
      },
      "series": {"invoice_group_id": 1, "name": "FACTURAS"},
      "invoice_type": {"invoice_type_id": 1, "name": "FACTURA COMPLETA"},
      "seller": {"user_id": 3, "name": "ANA COMERCIAL"},
      "owner": {"user_id": 3, "name": "ANA COMERCIAL"},
      "route": {"route_id": 2, "name": "RUTA NORTE"},
      "client": {
        "client_id": 949,
        "name": "CLIENTE DE EJEMPLO, S.L.",
        "nif": "B12345678",
        "fiscal_data": "Calle Ejemplo 1, 28000 Madrid",
        "address_1": "Calle Ejemplo 1",
        "address_2": null,
        "postal_code": "28000",
        "city": "Madrid",
        "province": "Madrid",
        "country": "España",
        "phone": "910000000",
        "mobile": null,
        "email": "[email protected]"
      },
      "issuer": {
        "name": "EMPRESA EMISORA, S.L.",
        "nif": "B87654321",
        "fiscal_data": "Avenida Principal 10, Madrid"
      },
      "payment_method_id": 2,
      "bank_method_id": 1,
      "tax_exemption_cause": null,
      "display_options": {"hide_taxes": false, "hide_line_price": false},
      "amounts": {
        "item_subtotal": 100.0,
        "item_tax_total": 21.0,
        "tax_total": 21.0,
        "surcharge_total": 0.0,
        "irpf_total": 0.0,
        "irpf_percent": 0.0,
        "retention_total": 0.0,
        "retention_percent": 0.0,
        "supplies": 0.0,
        "irpf_on_total": 0.0,
        "irpf_on_total_percent": 0.0,
        "total": 121.0,
        "paid": 50.0,
        "balance": 71.0,
        "profit": 34.5
      },
      "currency": {"symbol": "€", "exchange_rate": null, "converted_total": null},
      "taxes": [
        {
          "invoice_tax_rate_id": 987,
          "tax_rate_id": 1,
          "name": "IVA 21%",
          "percent": 21.0,
          "base": 100.0,
          "tax_amount": 21.0,
          "surcharge_percent": 0.0,
          "surcharge_amount": 0.0,
          "include_item_tax": false,
          "source": "invoice_tax_rates"
        }
      ],
      "payments": [
        {
          "payment_id": 4567,
          "number": "REC-4567",
          "date": "2026-07-12",
          "amount": 50.0,
          "paid": true,
          "returned": false,
          "payment_method_id": 2,
          "payment_method_name": "TRANSFERENCIA",
          "bank_method_id": 1,
          "bank_method_name": "BANCO PRINCIPAL",
          "bank_accounting_code": "572000001",
          "note": null
        }
      ]
    }
  ],
  "request_id": "a1b2c3d4e5f60708"
}

05 · Líneas vendidas

Venta y salida de artículos — `resource=sales`

Consulta líneas de facturas y/o albaranes con documento, cliente, artículo, cantidades, precios, impuestos, coste, beneficio, margen y comisión.

Alias aceptados

salessales_linesitem_salesventasventas_articulossalida_articulos

Fuente predeterminada

source=all: combina facturas y albaranes.

Base predeterminada

basis=invoices: prevalece la factura cuando existe vínculo.

Paginación

Cursor opaco por fecha, fuente, documento y línea.

Filtros disponibles

Parámetro	Alias	Formato	Predeterminado	Descripción
`date_from`	`fecha_desde` `fechaini` `desde_fecha`	YYYY-MM-DD	Primer día del mes actual	Fecha inicial del documento, inclusiva. Debe enviarse junto con date_to.
`date_to`	`fecha_hasta` `fechafin` `hasta_fecha`	YYYY-MM-DD	Fecha actual	Fecha final del documento, inclusiva. El intervalo máximo es de 366 días.
`source`	`origen`	Enum	all	all, invoices o delivery_notes. Decide qué fuentes se consultan.
`basis`	`desde`	Enum	invoices	invoices o delivery_notes. Decide qué documento prevalece al deduplicar; solo afecta a source=all.
`movement`	`ver`	Enum	all	all, sales o returns. sales exige cantidad > 0; returns exige cantidad < 0.
`document_id`	`documento_id`	Entero mayor que 0	Sin filtro	ID de factura o albarán. Con source=all puede coincidir en ambas tablas.
`client_id`	`cliente`	Entero mayor que 0	Sin filtro	Filtra por cliente.
`user_id`	`usuario`	Entero mayor que 0	Sin filtro	Filtra por el usuario o comercial del documento.
`owner_user_id`	`propietario_user_id`	Entero mayor que 0	Sin filtro	Filtra por el propietario actual del cliente.
`route_id`	`ruta_id`	Entero mayor que 0	Sin filtro	Filtra por la ruta actual del cliente.
`family_id`	`familia`	Entero mayor que 0	Sin filtro	Filtra por la familia actual del artículo.
`item_id`	`articulo`	Entero mayor que 0	Sin filtro	Filtra por item_lookup_id.
`item_type_id`	`tipo`	Entero mayor que 0	Sin filtro	Filtra por el tipo actual del artículo.
`tax_rate_id`	`impuesto_id`	Entero mayor que 0	Sin filtro	Filtra por tipo impositivo. El valor 0 equivale a no filtrar, por lo que no selecciona exclusivamente líneas exentas.
`search`	`buscar`	Texto, máximo 100 caracteres	Sin búsqueda	Busca en documento, cliente, línea, artículo, SKU y código de barras.
`cursor`	—	Texto opaco	Sin cursor	Cursor devuelto por pagination.next_cursor. No debe modificarse ni reutilizarse con otros filtros; longitud máxima admitida: 1.024 caracteres.
`limit`	`limite`	Entero de 1 a 200	50	Número máximo de líneas por página.

Cómo interactúan source y basis

source	basis	Resultado
`all`	`invoices`	Incluye facturas válidas y albaranes aún no vinculados a una factura existente. Es la combinación predeterminada.
`all`	`delivery_notes`	Incluye albaranes y omite facturas procedentes de un albarán vinculado.
`invoices`	Cualquier valor válido	Consulta únicamente líneas de factura. basis no realiza deduplicación.
`delivery_notes`	Cualquier valor válido	Consulta únicamente líneas de albarán. basis no realiza deduplicación.

Alias de valores admitidos

source: both, todos, invoice, factura, delivery_note y albaranes. basis: invoice, factura, delivery_note y albaranes. movement: todos, ventas, sale, return y devoluciones. Se recomiendan los valores canónicos en inglés.

Facturas incluidas

La rama de facturas excluye documentos anulados y sustituidos, además de líneas técnicas cuyo nombre contiene ALB-.

Movimiento

sales exige cantidad positiva; returns, cantidad negativa. all no aplica condición de signo.

Ejemplos de consulta

Consultas habituales de ventasPeriodo, familia, devoluciones, fuentes, búsqueda y cursor

Ventas del periodo

Aplica source=all, basis=invoices y movement=all.

curl -sS \
  -H "X-API-Key: TU_TOKEN_API" \
  -H "Accept: application/json" \
  "https://api.facturaone.com/v1/?resource=sales&date_from=2026-07-01&date_to=2026-07-26&limit=100"

Ventas positivas de una familia

La familia procede del catálogo actual.

curl -sS \
  -H "X-API-Key: TU_TOKEN_API" \
  -H "Accept: application/json" \
  "https://api.facturaone.com/v1/?resource=sales&date_from=2026-01-01&date_to=2026-12-31&family_id=4&movement=sales&limit=100"

Devoluciones de un artículo

Filtra cantidades negativas del artículo.

curl -sS \
  -H "X-API-Key: TU_TOKEN_API" \
  -H "Accept: application/json" \
  "https://api.facturaone.com/v1/?resource=sales&date_from=2026-01-01&date_to=2026-12-31&item_id=57248&movement=returns"

Solo facturas

Consulta únicamente líneas de factura.

curl -sS \
  -H "X-API-Key: TU_TOKEN_API" \
  -H "Accept: application/json" \
  "https://api.facturaone.com/v1/?resource=sales&date_from=2026-07-01&date_to=2026-07-26&source=invoices"

Vista basada en albaranes

Los albaranes prevalecen al deduplicar.

curl -sS \
  -H "X-API-Key: TU_TOKEN_API" \
  -H "Accept: application/json" \
  "https://api.facturaone.com/v1/?resource=sales&date_from=2026-07-01&date_to=2026-07-26&source=all&basis=delivery_notes"

Búsqueda por documento o artículo

Busca en documento, cliente, artículo, SKU y código de barras.

curl -sS \
  -H "X-API-Key: TU_TOKEN_API" \
  -H "Accept: application/json" \
  "https://api.facturaone.com/v1/?resource=sales&date_from=2026-01-01&date_to=2026-12-31&search=SKU-100"

Página siguiente

Sustituya CURSOR_DEVUELTO por pagination.next_cursor y conserve los filtros.

curl -sS \
  -H "X-API-Key: TU_TOKEN_API" \
  -H "Accept: application/json" \
  "https://api.facturaone.com/v1/?resource=sales&date_from=2026-07-01&date_to=2026-07-26&source=all&basis=invoices&limit=100&cursor=CURSOR_DEVUELTO"

Datos históricos y actuales en cada línea

Históricos: nombre y descripción de línea, lote, unidad, formato, cantidad, precio, coste, beneficio, margen, descuento e importes.
Actuales: SKU, código de barras, familia, tipo, nombre de la unidad de formato y porcentaje de comisión.
pricing.unit_cost, unit_profit y margin_percent se leen de la línea histórica; no se recalculan con el coste actual.
Si el artículo cambia de familia, una consulta histórica por family_id refleja la familia actual.
Propietario y ruta proceden del maestro actual del cliente.

page_totals no representa todo el periodo

Solo suma las líneas de la página actual. Para el total completo debe recorrer todas las páginas y acumular los resultados.

Diccionario de campos de data[]

Fuente y documento8 rutas documentadas

Ruta JSON	Tipo	Significado
`source`	`string`	invoice o delivery_note.
`document.document_id`	`integer`	ID de factura o albarán según source.
`document.line_id`	`integer`	ID de la línea.
`document.linked_invoice_id`	`integer\|null`	Factura vinculada al albarán; en facturas es null.
`document.status_id`	`integer`	Estado interno del documento.
`document.date`	`date\|null`	Fecha del documento.
`document.number`	`string`	Número del documento.
`document.reference`	`string\|null`	Referencia del documento.

Cliente y responsables12 rutas documentadas

Ruta JSON	Tipo	Significado
`client.client_id`	`integer`	ID del cliente.
`client.name`	`string\|null`	Nombre del cliente.
`client.nif`	`string\|null`	NIF del cliente.
`seller`	`object\|null`	Comercial del documento.
`seller.user_id`	`integer\|null`	ID del comercial cuando seller no es null.
`seller.name`	`string\|null`	Nombre del comercial.
`owner`	`object\|null`	Propietario actual del cliente.
`owner.user_id`	`integer\|null`	ID del propietario cuando owner no es null.
`owner.name`	`string\|null`	Nombre del propietario actual.
`route`	`object\|null`	Ruta actual del cliente.
`route.route_id`	`integer\|null`	ID de la ruta cuando route no es null.
`route.name`	`string\|null`	Nombre de la ruta actual.

Artículo y clasificación18 rutas documentadas

Ruta JSON	Tipo	Significado
`item.item_lookup_id`	`integer`	ID del artículo del catálogo; puede ser 0 si la línea es libre.
`item.sku`	`string\|null`	SKU actual del catálogo.
`item.barcode`	`string\|null`	Código de barras actual.
`item.name`	`string\|null`	Nombre histórico guardado en la línea, limitado a 500 caracteres.
`item.description`	`string\|null`	Descripción histórica guardada en la línea, limitada a 2.000 caracteres.
`item.lot`	`string\|null`	Lote de la línea.
`item.unit`	`string\|null`	Unidad guardada en la línea.
`item.family`	`object\|null`	Familia actual del artículo.
`item.family.family_id`	`integer\|null`	ID de la familia cuando family no es null.
`item.family.name`	`string\|null`	Nombre actual de la familia.
`item.type`	`object\|null`	Tipo actual del artículo.
`item.type.item_type_id`	`integer\|null`	ID del tipo cuando type no es null.
`item.type.name`	`string\|null`	Nombre actual del tipo.
`item.format`	`object\|null`	Formato asociado a la línea.
`item.format.format_id`	`integer\|null`	ID de formato guardado en la línea.
`item.format.units`	`number`	Unidades de formato guardadas en la línea.
`item.format.unit`	`string\|null`	Nombre actual de la unidad del catálogo de formatos.
`quantity`	`number`	Cantidad de la línea, con hasta 4 decimales.

Precio, coste, margen, impuesto y comisión15 rutas documentadas

Ruta JSON	Tipo	Significado
`pricing.unit_price`	`number`	Precio unitario histórico guardado en la línea.
`pricing.unit_cost`	`number`	Coste unitario histórico guardado en item_cost_price de la línea de factura o albarán.
`pricing.unit_profit`	`number`	Beneficio unitario histórico guardado en item_beneficio de la línea de factura o albarán.
`pricing.margin_percent`	`number`	Margen histórico guardado en item_margen de la línea de factura o albarán.
`pricing.discount_percent`	`number`	Porcentaje de descuento.
`pricing.discount_amount`	`number`	Importe calculado del descuento.
`pricing.subtotal`	`number`	Subtotal de la línea.
`pricing.tax.tax_rate_id`	`integer`	ID del impuesto de la línea.
`pricing.tax.name`	`string\|null`	Nombre del impuesto.
`pricing.tax.percent`	`number`	Porcentaje efectivo del impuesto.
`pricing.tax.amount`	`number`	Cuota de impuesto.
`pricing.tax.surcharge_amount`	`number`	Cuota de recargo de equivalencia.
`pricing.total`	`number`	Total de la línea.
`commission.percent`	`number`	Porcentaje actual de comisión del artículo.
`commission.amount`	`number`	Comisión calculada sobre el subtotal.

Campos de page_totals

Campo	Tipo	Significado en la página actual
`quantity`	`number`	Suma de cantidades, incluidas negativas cuando hay devoluciones.
`discount_amount`	`number`	Importe de descuento de las líneas.
`subtotal`	`number`	Suma de bases o subtotales.
`tax_amount`	`number`	Suma de cuotas de impuesto.
`surcharge_amount`	`number`	Suma de cuotas de recargo de equivalencia.
`total`	`number`	Suma del total de las líneas.
`commission_amount`	`number`	Suma de la comisión calculada.

Ejemplo completo de respuesta de ventasLínea de factura, cursor y totales de página

Valores ilustrativos

Cuando source sea delivery_note, document.document_id será el ID del albarán.

{
  "ok": true,
  "read_only": true,
  "version": "1.1.1",
  "account": "Empresa de ejemplo",
  "resource": "sales",
  "nombre": "salida_articulos",
  "filters": {
    "date_from": "2026-07-01",
    "date_to": "2026-07-15",
    "date_defaulted": false,
    "source": "all",
    "basis": "invoices",
    "movement": "sales",
    "document_id": null,
    "client_id": null,
    "user_id": null,
    "owner_user_id": null,
    "route_id": null,
    "family_id": 4,
    "item_id": null,
    "item_type_id": null,
    "tax_rate_id": null,
    "search": null,
    "limit": 1
  },
  "pagination": {
    "returned": 1,
    "has_more": true,
    "next_cursor": "eyJ2IjoxLCJmIjoiLi4uIn0"
  },
  "page_totals": {
    "quantity": 2.0,
    "discount_amount": 10.0,
    "subtotal": 90.0,
    "tax_amount": 18.9,
    "surcharge_amount": 0.0,
    "total": 108.9,
    "commission_amount": 1.8
  },
  "data": [
    {
      "source": "invoice",
      "document": {
        "document_id": 12345,
        "line_id": 67890,
        "linked_invoice_id": null,
        "status_id": 2,
        "date": "2026-07-10",
        "number": "F/2026/00125",
        "reference": "PED-7781"
      },
      "client": {
        "client_id": 949,
        "name": "CLIENTE DE EJEMPLO, S.L.",
        "nif": "B12345678"
      },
      "seller": {"user_id": 3, "name": "ANA COMERCIAL"},
      "owner": {"user_id": 3, "name": "ANA COMERCIAL"},
      "route": {"route_id": 2, "name": "RUTA NORTE"},
      "item": {
        "item_lookup_id": 57248,
        "sku": "SKU-100",
        "barcode": "8400000000100",
        "name": "ARTÍCULO DE EJEMPLO",
        "description": "Descripción guardada en la línea",
        "lot": "L-2026-07",
        "unit": "ud",
        "family": {"family_id": 4, "name": "CONSUMIBLES"},
        "type": {"item_type_id": 2, "name": "PRODUCTO"},
        "format": {"format_id": 1, "units": 1.0, "unit": "ud"}
      },
      "quantity": 2.0,
      "pricing": {
        "unit_price": 50.0,
        "unit_cost": 30.0,
        "unit_profit": 15.0,
        "margin_percent": 33.33,
        "discount_percent": 10.0,
        "discount_amount": 10.0,
        "subtotal": 90.0,
        "tax": {
          "tax_rate_id": 1,
          "name": "IVA 21%",
          "percent": 21.0,
          "amount": 18.9,
          "surcharge_amount": 0.0
        },
        "total": 108.9
      },
      "commission": {"percent": 2.0, "amount": 1.8}
    }
  ],
  "request_id": "a1b2c3d4e5f60708"
}

06 · Recorrido

Paginación correcta

La API no utiliza offset. Emplea paginación por clave en catálogos y facturas, y cursor compuesto en ventas.

Recursos simples e invoices

{
  "pagination": {
    "returned": 100,
    "has_more": true,
    "next_after_id": 12345
  }
}

Añada after_id=12345 y mantenga los demás filtros.

sales

{
  "pagination": {
    "returned": 100,
    "has_more": true,
    "next_cursor": "eyJ2IjoxLC..."
  }
}

Envíe el valor completo como cursor. No lo modifique.

No cambie filtros entre páginas

En ventas, el cursor contiene una huella de los filtros y se rechazará con CURSOR_FILTER_MISMATCH cuando detecte otra combinación.

Patrón recomendado

Realice la primera petición sin after_id ni cursor.
Procese todos los elementos de data.
Si has_more es true, guarde la clave de continuación.
Repita la misma URL añadiendo únicamente esa clave.
Finalice cuando has_more sea false.

07 · Diagnóstico

Errores y códigos HTTP

Los errores no exponen SQL, rutas internas ni credenciales. Guarde siempre el request_id cuando necesite soporte.

Respuesta de error

{
  "ok": false,
  "read_only": true,
  "error": "BAD_DATE_RANGE",
  "message": "date_from no puede ser posterior a date_to.",
  "request_id": "a1b2c3d4e5f60708"
}

Cabeceras útiles

X-Request-ID: Identificador de diagnóstico.
X-API-Version: Versión que respondió.
X-API-Read-Only: Siempre true.
Allow: En un 405 indica que solo se admite GET.

HTTP	Código	Significado
400	`BAD_PARAMETER`	Un parámetro no tiene el tipo, rango o formato esperado.
400	`BAD_DATE`	Una fecha no tiene formato YYYY-MM-DD o no es una fecha real.
400	`INCOMPLETE_DATE_RANGE`	Se ha enviado solo date_from o solo date_to.
400	`BAD_DATE_RANGE`	date_from es posterior a date_to.
400	`DATE_RANGE_TOO_LARGE`	El intervalo supera 366 días.
400	`SEARCH_TOO_LONG`	search supera 100 caracteres.
400	`BAD_FIELDS`	fields está vacío o no contiene campos válidos.
400	`FIELD_NOT_ALLOWED`	Se ha solicitado un campo no autorizado.
400	`CONFLICTING_PAGINATION`	Se han combinado id y after_id.
400	`FILTER_NOT_SUPPORTED`	Se ha usado active en un recurso que no lo admite.
400	`BAD_ACTIVE_FILTER`	active no es 0, 1 o all.
400	`BAD_STATUS_FILTER`	status no pertenece a los valores admitidos.
400	`BAD_VALIDITY_FILTER`	validity no pertenece a los valores admitidos.
400	`BAD_SOURCE_FILTER`	source no es all, invoices o delivery_notes.
400	`BAD_BASIS_FILTER`	basis no es invoices o delivery_notes.
400	`BAD_MOVEMENT_FILTER`	movement no es all, sales o returns.
400	`BAD_CURSOR`	El cursor está dañado, tiene formato incorrecto o supera el tamaño permitido.
400	`CURSOR_FILTER_MISMATCH`	El cursor pertenece a otra combinación de filtros.
401	`MISSING_TOKEN`	No se ha enviado Authorization Bearer ni X-API-Key.
401	`INVALID_TOKEN`	El token es incorrecto, está revocado o la API está desactivada.
404	`RESOURCE_NOT_FOUND`	El recurso solicitado no existe.
405	`METHOD_NOT_ALLOWED`	Se ha usado un método distinto de GET.
500	`AUTH_DATABASE_ERROR`	No se ha podido validar el token en la base maestra.
500	`INVALID_DATABASE_CONFIG`	La instalación asociada no tiene una configuración válida.
500	`DATABASE_ERROR`	No se ha podido completar la consulta de lectura.
500	`JSON_ENCODE_ERROR`	La respuesta no se ha podido codificar como JSON.
501	`RESOURCE_NOT_IMPLEMENTED`	El recurso existe en el enrutador pero no está implementado.

Tratamiento recomendado

400: no reintentar sin corregir filtros, fechas, campos o cursor.
401: revisar el token y sustituirlo si fue regenerado.
404/405: corregir recurso o método.
500: registrar request_id y aplicar reintentos limitados con espera progresiva.
501: revisar versión o recurso; no reintentar automáticamente.

08 · Control económico

Consumo, medición y facturación

FacturaOne registra cada petición para que la empresa pueda conocer de dónde procede su consumo y revisar la evolución mensual antes de valorar el coste económico.

Solicitudes

Número de llamadas ejecutadas, recurso consultado, estado HTTP y tiempo de respuesta.

Volumen

Filas devueltas y tamaño de entrada y salida generado por cada petición.

Consumo estimado

Estimación reproducible de tokens de entrada, salida y total para comparar periodos y tipos de consulta.

Consulta mensual dentro de FacturaOne

Desde Configuración → API externa → Mostrar uso puede abrir la pantalla de consumo, consultar el mes actual por defecto y seleccionar meses y años anteriores. La gráfica desglosa el uso por recurso para detectar qué integración o tipo de consulta genera el mayor consumo.

El uso efectivo puede generar costes

La activación y la generación del token no añaden coste por sí mismas. La facturación se calcula según el consumo real y las tarifas vigentes; por ese motivo conviene paginar correctamente, limitar campos y evitar consultas repetitivas innecesarias.

09 · Producción

Seguridad y comprobaciones

Recomendaciones para consumir la API sin exponer el token ni sobrecargar una instalación.

Buenas prácticas

No coloque el token en la URL, archivos públicos, repositorios ni JavaScript del navegador.
Guárdelo como secreto del servidor o variable de entorno.
Envíelo únicamente por HTTPS.
Regénere el token si sospecha que se ha expuesto.
No registre cabeceras completas de autenticación.
Use el menor limit razonable y periodos acotados.

Probar con Postman

Cree una petición GET.
Use https://api.facturaone.com/v1/?resource=resources.
Añada la cabecera X-API-Key.
Coloque el token guardado como valor.
Añada opcionalmente Accept: application/json.
Compruebe que la respuesta contiene ok=true.

Lista de comprobación para un conector nuevo

Validar primero resource=resources y guardar la versión recibida.
Sincronizar catálogos auxiliares antes de filtrar por ID.
Implementar paginación hasta has_more=false.
Guardar request_id en errores y no mostrar el token.
Tratar campos null y objetos opcionales.
No asumir que page_totals representa todas las páginas.
Diferenciar datos históricos del documento y datos actuales del maestro.
Probar pagadas, pendientes, anuladas, sustituidas, devoluciones y albaranes facturados.

Regenerar invalida el token anterior inmediatamente

Antes de regenerar en producción, coordine el cambio con todos los conectores. No existe un periodo de convivencia entre el token antiguo y el nuevo.

10 · Ayuda

Preguntas frecuentes sobre la API de FacturaOne

Respuestas rápidas a las dudas más habituales antes de iniciar una integración.

¿La API puede crear o modificar datos?

No. Esta versión es exclusivamente de lectura. Solo admite peticiones GET y no ofrece operaciones POST, PUT, PATCH ni DELETE.

¿Cómo se autentica una integración?

Mediante un token enviado en la cabecera X-API-Key o en Authorization: Bearer. El token no debe formar parte de la URL.

¿Qué datos puedo consultar?

Clientes, artículos, proveedores, familias, tipos, series, rutas, usuarios, impuestos, formas de pago, facturas emitidas y líneas de venta.

¿Cómo se recorren más de 200 registros?

Con paginación. Los recursos simples y las facturas usan next_after_id; las ventas utilizan un next_cursor opaco.

¿La activación de la API tiene coste?

Activar la API y generar el token no tiene coste adicional. El uso efectivo se factura según el consumo y las tarifas vigentes.

¿Dónde puedo ver el consumo?

En FacturaOne, dentro de Configuración → API externa → Mostrar uso. Puede consultar el mes actual y periodos anteriores.

¿Qué debo enviar a soporte cuando falla una llamada?

El request_id devuelto en el JSON o en la cabecera X-Request-ID, junto con el recurso y la hora aproximada. Nunca envíe el token en claro.

Una integración predecible, segura y medible

Empiece consultando resource=resources, implemente la paginación y conserve el request_id de cualquier error. Con estas tres reglas, el conector podrá adaptarse a los recursos disponibles y controlar su consumo.

Documentación correspondiente a FacturaOne API v1.1.1. Los ejemplos contienen datos ficticios y el marcador TU_TOKEN_API; nunca publique un token real.

Cookie	Duración	Descripción
cookielawinfo-checkbox-analisis	1 year	Set by the GDPR Cookie Consent plugin to store the user consent for cookies in the category "Analytics".
cookielawinfo-checkbox-funcional	1 year	Establecido por el complemento de consentimiento de cookies del RGPD para almacenar el consentimiento del usuario para las cookies en la categoría "Funcional".
cookielawinfo-checkbox-necessary	11 months	Esta cookie está configurada por el complemento de consentimiento de cookies de GDPR. Las cookies se utilizan para almacenar el consentimiento del usuario para las cookies en la categoría "Necesarias".
cookielawinfo-checkbox-publicidad	1 year	Establecido por el complemento de consentimiento de cookies del RGPD para almacenar el consentimiento del usuario para las cookies en la categoría "Publicidad".
cookielawinfo-checkbox-rendimiento	1 year	Establecido por el complemento de consentimiento de cookies de GDPR para registrar el consentimiento del usuario para las cookies en la categoría "Rendimiento".

Cookie	Duración	Descripción
_ga	2 years	La cookie _ga, instalada por Google Analytics, calcula los datos de visitantes, sesiones y campañas y también realiza un seguimiento del uso del sitio para el informe de análisis del sitio. La cookie almacena información de forma anónima y asigna un número generado aleatoriamente para reconocer visitantes únicos.
_ga_4PKKNNHJJP	2 years	Esta cookie es instalada por Google Analytics.
_ga_devsite	2 years	Esta cookie es instalada por Google Analytics.
_gat_gtag_UA_44646387_3	1 minute	Establecido por Google para distinguir a los usuarios.
_gcl_au	3 months	Proporcionado por Google Tag Manager para experimentar la eficiencia publicitaria de los sitios web que utilizan sus servicios.
_gid	1 day	Instalada por Google Analytics, la cookie _gid almacena información sobre cómo los visitantes usan un sitio web, al mismo tiempo que crea un informe analítico del rendimiento del sitio web. Algunos de los datos que se recopilan incluyen el número de visitantes, su fuente y las páginas que visitan de forma anónima.
CONSENT	2 years	YouTube establece esta cookie a través de videos de youtube incrustados y registra datos estadísticos anónimos.
cookielawinfo-checkbox-analytics	11 months	Esta cookie está configurada por el complemento de consentimiento de cookies de GDPR. La cookie se utiliza para almacenar el consentimiento del usuario para las cookies en la categoría "Análisis".

Cookie	Duración	Descripción
IDE	1 year 24 days	Las cookies de Google DoubleClick IDE se utilizan para almacenar información sobre cómo el usuario utiliza el sitio web para presentarle anuncios relevantes y de acuerdo con el perfil del usuario.
test_cookie	15 minutes	Test_cookie lo establece doubleclick.net y se utiliza para determinar si el navegador del usuario admite cookies.
VISITOR_INFO1_LIVE	5 months 27 days	Una cookie establecida por YouTube para medir el ancho de banda que determina si el usuario obtiene la interfaz del reproductor nueva o antigua.
YSC	session	Youtube establece la cookie YSC y se utiliza para rastrear las vistas de videos incrustados en las páginas de Youtube.
yt-remote-connected-devices	never	YouTube establece esta cookie para almacenar las preferencias de video del usuario que usa el video incrustado de YouTube.
yt-remote-device-id	never	YouTube establece esta cookie para almacenar las preferencias de video del usuario que usa el video incrustado de YouTube.

Cookie	Duración	Descripción
cookielawinfo-checkbox-necesarias	1 year	No description
cookielawinfo-checkbox-others	11 months	Esta cookie está configurada por el complemento de consentimiento de cookies de GDPR. La cookie se utiliza para almacenar el consentimiento del usuario para las cookies en la categoría "Otro".
cookielawinfo-checkbox-otras	1 year	No description

FacturaONE

Conecta tus aplicaciones con FacturaOne mediante una API REST de solo lectura

Inicio rápido

Primera petición

Authorization Bearer

Cabecera directa

PHP con cURL

Node.js 18+ con fetch

Reglas globales de consulta

Fechas seguras

Identificadores

Un solo valor

Estructura común de una respuesta correcta

Recursos y catálogos

Descubrimiento automático: resource=resources

Resumen de recursos

Filtros de los recursos simples

Cómo obtener los identificadores usados por los filtros

Diccionario completo de recursos simples

Campos usados por search

Ejemplo recomendado

Campos permitidos en fields

Campos usados por search

Ejemplo recomendado

Campos permitidos en fields

Campos usados por search

Ejemplo recomendado

Campos permitidos en fields

Campos usados por search

Ejemplo recomendado

Campos permitidos en fields

Campos usados por search

Ejemplo recomendado

Campos permitidos en fields

Campos usados por search

Ejemplo recomendado

Campos permitidos en fields

Campos usados por search

Ejemplo recomendado

Campos permitidos en fields

Campos usados por search

Ejemplo recomendado

Campos permitidos en fields

Campos usados por search

Ejemplo recomendado

Campos permitidos en fields

Campos usados por search

Ejemplo recomendado

Campos permitidos en fields

Campos usados por search

Ejemplo recomendado

Campos permitidos en fields

Facturas emitidas — resource=invoices

Alias aceptados

Periodo predeterminado

Impuestos

Pagos

Filtros disponibles

Valores de status

Valores de validity

Ejemplos de consulta

Facturas del periodo

Factura exacta por ID

Factura con pagos

Facturas válidas y pendientes

Cliente y serie

Búsqueda por texto

Página siguiente

Datos históricos y actuales

Origen de impuestos

Diccionario de campos de data[]

Venta y salida de artículos — resource=sales

Alias aceptados

Fuente predeterminada

Base predeterminada

Paginación

Filtros disponibles

Cómo interactúan source y basis

Facturas incluidas

Movimiento

Descubrimiento automático: `resource=resources`

Facturas emitidas — `resource=invoices`

Venta y salida de artículos — `resource=sales`