¿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.

¿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.

Documentación oficial · API v1.1.2 · Webhooks v1.1.1

Conecta tus aplicaciones con FacturaOne mediante API REST y webhooks

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.

Q: ¿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.

Consulta clientes, artículos, proveedores, facturas, pagos, cobros, ventas y catálogos auxiliares mediante una API REST de solo lectura, y recibe cambios relevantes en tiempo real mediante webhooks salientes en formato JSON.

API de solo lectura HTTPS + JSON X-API-Key o Bearer Paginación estable Webhooks salientes

Empezar la integración Ver recursos disponibles

Última revisión: 30 de julio de 2026 · API: https://api.facturaone.com/v1/ · Webhooks: URL configurable

FACTURAONE API

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

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

Activar la API, generar el token y configurar la URL de webhooks no tiene coste adicional.

El uso efectivo se factura según el consumo realizado y las tarifas vigentes. FacturaOne registra tanto las consultas de lectura como los intentos de entrega de webhooks, y permite revisar el mes actual y periodos anteriores desde el ERP.

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

Versión API1.1.2Se devuelve en el JSON y en X-API-Version. Los webhooks conservan su esquema 1.1.1.

MétodoGET API · POST webhookLa API de lectura usa GET; FacturaOne entrega los eventos salientes mediante POST JSON.

Autenticación APIX-API-Key o BearerPara consultas API; el receptor webhook usa un secreto propio.

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, pagos y ventas.

Novedad de la API v1.1.2: consulta independiente de pagos

El nuevo recurso resource=payments permite consultar pagos y cobros por fecha, factura, albarán, cliente, usuario, forma de pago, banco, remesa y estado. La ampliación es aditiva: invoices&include_payments=1 conserva exactamente su estructura compacta anterior.

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 de lectura de la API 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, invoices, sales y los listados generales de payments consultan desde el primer día del mes actual hasta hoy. En payments, las búsquedas por id, invoice_id, aquote_id o remittance_id no aplican ese periodo predeterminado.

Identificadores

Los filtros de ID usan normalmente enteros positivos. El valor 0 o la ausencia del parámetro suele equivaler a no filtrar; payments.user_id también admite -1 para registros automáticos o especiales.

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; pagos y cobros; 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.
`payments`	paymentpagospagocobroscobro	`payment_id`	No	Pagos y cobros vinculados a facturas, albaranes o clientes, con trazabilidad del documento de origen y del saldo actual.
`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, payments 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`
`payment_id`	`payments`	`payment_id`

No fije los IDs de las formas de pago en el código

Obtenga siempre payment_method_id mediante resource=payment_methods. Una instalación puede contener nombres personalizados o incluso etiquetas repetidas con identificadores distintos; el recurso payments devuelve tanto el ID como el nombre real almacenado.

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.2",
  "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.2",
  "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. Para filtros, albaranes, remesas y trazabilidad completa use resource=payments.

Dos formas compatibles de leer pagos

invoices&include_payments=1 añade una colección compacta a cada factura devuelta y mantiene su esquema anterior. resource=payments es el recurso completo para sincronizar pagos, localizar cobros de albaranes, consultar devueltos o conservar la trazabilidad cuando un albarán se transforma en factura.

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.2",
  "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 · Cobros

Pagos y cobros — `resource=payments`

Consulta independiente de los registros de fi_payments, con forma de pago, banco, remesa, usuario, cliente y documentos relacionados. El recurso identifica dónde está aplicado actualmente cada pago y conserva el albarán de origen cuando posteriormente se factura.

Alias aceptados

paymentspaymentpagospagocobroscobro

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

Periodo predeterminado

Un listado general sin fechas consulta el mes actual. Las búsquedas por id, invoice_id, aquote_id o remittance_id recorren todo el historial sin exigir fechas.

Aplicación actual

Cuando invoice_id > 0, el pago está aplicado a la factura. Si además existe aquote_id, ese albarán se conserva como origen.

Paginación

Orden ascendente por payment_id, mediante after_id, con un máximo de 200 registros por petición.

Un pago transferido no se duplica

Si un pago se registró inicialmente en un albarán y después ese albarán se facturó, el recurso devuelve un único registro. allocation.current_document_type será invoice, allocation.origin_document_type será delivery_note y allocation.transferred_from_delivery_note será true.

La forma de pago se resuelve desde el catálogo real

El nombre se obtiene mediante fi_payment_methods. No se presupone que un ID concreto signifique siempre EFECTIVO, VISA, BIZUM o DOMICILIADO; consulte antes resource=payment_methods.

Filtros disponibles

Parámetro	Alias	Formato	Predeterminado	Descripción
`id`	`payment_id`	Entero mayor que 0	Sin filtro	Obtiene un pago concreto. No aplica el periodo predeterminado y no puede combinarse con `after_id`.
`after_id`	`desde_id`	Entero igual o mayor que 0	0	Continúa después del último `payment_id` procesado.
`date_from`	`fecha_desde` `fechaini` `desde_fecha`	`YYYY-MM-DD`	Primer día del mes actual en listados generales	Fecha inicial del pago, inclusiva. Debe enviarse junto con `date_to`.
`date_to`	`fecha_hasta` `fechafin` `hasta_fecha`	`YYYY-MM-DD`	Fecha actual en listados generales	Fecha final del pago, inclusiva. El intervalo máximo es de 366 días.
`invoice_id`	`factura_id`	Entero mayor que 0	Sin filtro	Devuelve los pagos aplicados a una factura. Sin fechas, consulta todo el historial de esa factura.
`aquote_id`	`delivery_note_id` `albaran_id` `albarán_id`	Entero mayor que 0	Sin filtro	Devuelve los pagos relacionados con un albarán, incluidos los que después quedaron aplicados a una factura.
`client_id`	`cliente`	Entero mayor que 0	Sin filtro	Filtra por el cliente resuelto desde la factura, el albarán o, en último lugar, `payment_client_id`.
`user_id`	`usuario`	Entero igual o mayor que `-1`	0, sin filtro	Filtra por el usuario que registró el pago. El valor `-1` permite consultar registros automáticos o especiales.
`payment_method_id`	`forma_pago_id`	Entero mayor que 0	Sin filtro	Filtra por la forma de pago. Obtenga el ID mediante `resource=payment_methods`.
`bank_method_id`	`banc_method_id` `banco_id`	Entero mayor que 0	Sin filtro	Filtra por la cuenta o método bancario asociado.
`remittance_id`	`payment_remesa_id` `remesa_id`	Entero mayor que 0	Sin filtro	Filtra por remesa. Sin fechas, consulta todo el historial de esa remesa.
`document_type`	`tipo_documento`	Enum	`all`	`all`, `invoice`, `delivery_note`, `client` o `unassigned`.
`paid`	`pagado`	`all`, `0` o `1`	`all`	Filtra por `payment_pagado`. También admite true/false, yes/no y si/sí.
`returned`	`devuelto`	`all`, `0` o `1`	`all`	Filtra por `payment_devuelto`. También admite true/false, yes/no y si/sí.
`search`	`buscar`	Texto, máximo 100 caracteres	Sin búsqueda	Busca en número, banco, nota, forma de pago, factura, albarán, cliente, NIF y usuario.
`limit`	`limite`	Entero de 1 a 200	50	Número máximo de pagos por página.

Valores de document_type

Valor	Pago seleccionado
`all`	No aplica filtro de asignación documental.
`invoice`	`invoice_id > 0`. Incluye pagos transferidos desde albaranes.
`delivery_note`	`invoice_id = 0` y `aquote_id > 0`: el pago sigue actualmente en el albarán.
`client`	Sin factura ni albarán, pero con `payment_client_id > 0`.
`unassigned`	Sin factura, albarán ni cliente auxiliar.

Valores de paid y returned

Valor	Comportamiento
`all`, `todos`, `todo` o `*`	No filtra ese indicador.
`1`, `true`, `yes`, `si` o `sí`	Exige indicador verdadero.
`0`, `false` o `no`	Exige indicador falso.

Alias de document_type por compatibilidad

invoice admite invoices, factura y facturas; delivery_note admite delivery_notes, aquote, aquotes, albaran, albarán y albaranes; client admite clients, cliente y clientes; unassigned admite none, sin_asignar y sin-asignar.

delivery_note significa asignación actual, no origen histórico

Un pago con invoice_id > 0 y aquote_id > 0 pertenece actualmente a la factura y, por tanto, no aparece con document_type=delivery_note. Para localizarlo por su albarán de origen utilice aquote_id=ID_ALBARAN.

Ejemplos de consulta

Consultas habituales de pagosPeriodo, factura, albarán, forma de pago, devueltos y página siguiente

Pagos de un periodo

Devuelve hasta 100 pagos registrados entre dos fechas.

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

Historial de una factura

No necesita fechas y devuelve todos los pagos vinculados a la factura.

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

Pagos originados en un albarán

Incluye el pago aunque después haya sido transferido a una factura.

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

Pagos cobrados por una forma de pago

El ID 4 es meramente ilustrativo; consulte antes payment_methods.

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

Pagos que siguen en albaranes

Excluye los que ya están aplicados a una factura.

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

Recibos devueltos

Puede combinarse con cliente, remesa, banco o forma de pago.

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

Pago exacto

Recupera un registro antiguo sin indicar periodo.

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

Página siguiente

Conserve los 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=payments&date_from=2026-01-01&date_to=2026-12-31&limit=200&after_id=5000"

Resolución del cliente

La API prioriza el cliente de la factura; si no existe, usa el del albarán; y solo después utiliza payment_client_id. Así, un pago transferido conserva el cliente correcto del documento actual.

Importes del documento

invoice.amounts y delivery_note.amounts son resúmenes completos del documento relacionado. No representan únicamente el importe del registro de pago actual.

paid y returned son indicadores independientes

status.counts_towards_balance reproduce exactamente la regla usada por FacturaOne para los saldos y coincide con status.paid. No deduzca ese valor a partir de returned; lea siempre los tres campos.

Compatibilidad con bases antiguas

En instalaciones que todavía no tengan la columna fi_payments.payment_client_id, el recurso sigue funcionando. En ese caso no puede existir una asignación exclusiva de tipo client, pero las relaciones con factura y albarán se mantienen.

Diccionario de campos de data[]

Identificación, estado y nota13 rutas documentadas

Ruta JSON	Tipo	Significado
`payment_id`	`integer`	Identificador interno del pago.
`number`	`string\|null`	Número o referencia del pago.
`date`	`date\|null`	Fecha registrada en `payment_date`.
`amount`	`number`	Importe del pago, con hasta 4 decimales.
`payment_client_id`	`integer\|null`	Cliente auxiliar guardado directamente en el pago; puede diferir del cliente resuelto desde el documento.
`status`	`object`	Indicadores del estado del pago.
`status.paid`	`boolean`	Valor de `payment_pagado`.
`status.returned`	`boolean`	Valor de `payment_devuelto`.
`status.counts_towards_balance`	`boolean`	Indica si el pago interviene en el pagado y el saldo del documento; coincide con `status.paid`.
`maturity_days`	`integer`	Días de vencimiento registrados en `payment_vencimiento`.
`note`	`string\|null`	Nota del pago, limitada a 4.000 caracteres.
`note_truncated`	`boolean`	true cuando la nota original superaba 4.000 caracteres.
`inmov`	`boolean`	Indicador almacenado en `payment_inmov`.

Forma de pago, banco y remesa11 rutas documentadas

Ruta JSON	Tipo	Significado
`payment_method`	`object`	Forma de pago relacionada.
`payment_method.payment_method_id`	`integer`	ID de `fi_payment_methods`.
`payment_method.name`	`string\|null`	Nombre real de la forma de pago.
`bank_method`	`object`	Cuenta o método bancario relacionado.
`bank_method.bank_method_id`	`integer`	ID del método bancario.
`bank_method.name`	`string\|null`	Nombre del método bancario.
`bank_method.accounting_code`	`string\|null`	Código contable bancario.
`bank_method.payment_bank_name`	`string\|null`	Nombre bancario libre guardado directamente en el pago.
`remittance`	`object\|null`	Remesa asociada; null si no hay ID ni fecha.
`remittance.remittance_id`	`integer\|null`	ID de la remesa.
`remittance.date`	`date\|null`	Fecha registrada de la remesa.

Aplicación, usuario y cliente11 rutas documentadas

Ruta JSON	Tipo	Significado
`allocation.current_document_type`	`string`	invoice, delivery_note, client o unassigned según la aplicación actual.
`allocation.origin_document_type`	`string`	delivery_note cuando existe `aquote_id`; en otro caso coincide con el tipo actual.
`allocation.transferred_from_delivery_note`	`boolean`	true cuando coexisten `invoice_id` y `aquote_id`.
`user`	`object\|null`	Usuario que registró el pago.
`user.user_id`	`integer\|null`	ID del usuario; puede ser `-1` en registros especiales.
`user.name`	`string\|null`	Nombre del usuario cuando existe en el maestro.
`client`	`object\|null`	Cliente resuelto por prioridad documental.
`client.client_id`	`integer\|null`	ID del cliente resuelto.
`client.name`	`string\|null`	Nombre fiscal actual del cliente.
`client.commercial_name`	`string\|null`	Nombre comercial actual.
`client.nif`	`string\|null`	NIF o identificador fiscal actual.

Factura relacionada11 rutas documentadas

Ruta JSON	Tipo	Significado
`invoice`	`object\|null`	Factura indicada por `invoice_id`; null cuando el pago no está aplicado a una factura.
`invoice.invoice_id`	`integer`	ID guardado en el pago.
`invoice.exists`	`boolean`	Indica si la fila de factura relacionada existe actualmente.
`invoice.number`	`string\|null`	Número de factura.
`invoice.reference`	`string\|null`	Referencia de la factura.
`invoice.date`	`date\|null`	Fecha de emisión.
`invoice.status_id`	`integer\|null`	Estado interno; null si la factura ya no existe.
`invoice.amounts`	`object\|null`	Resumen completo del documento; null si la factura no existe.
`invoice.amounts.total`	`number`	Total de la factura.
`invoice.amounts.paid`	`number`	Total pagado de la factura.
`invoice.amounts.balance`	`number`	Saldo actual de la factura.

Albarán relacionado12 rutas documentadas

Ruta JSON	Tipo	Significado
`delivery_note`	`object\|null`	Albarán indicado por `aquote_id`; puede coexistir con invoice como origen histórico.
`delivery_note.aquote_id`	`integer`	ID guardado en el pago.
`delivery_note.exists`	`boolean`	Indica si la fila de albarán relacionada existe actualmente.
`delivery_note.number`	`string\|null`	Número del albarán.
`delivery_note.reference`	`string\|null`	Referencia del albarán.
`delivery_note.date`	`date\|null`	Fecha del albarán.
`delivery_note.status_id`	`integer\|null`	Estado interno; null si el albarán ya no existe.
`delivery_note.linked_invoice_id`	`integer\|null`	Factura vinculada actualmente desde la cabecera del albarán.
`delivery_note.amounts`	`object\|null`	Resumen completo del albarán; null si ya no existe.
`delivery_note.amounts.total`	`number`	Total del albarán.
`delivery_note.amounts.paid`	`number`	Total pagado almacenado en el albarán.
`delivery_note.amounts.balance`	`number`	Saldo almacenado en el albarán.

Ejemplo completo de respuesta de un pago transferidoEl albarán se conserva como origen y la factura recibe el saldo

Valores ilustrativos

Los nombres, números e importes son ficticios. Los importes de invoice y delivery_note se leen de sus respectivas tablas de totales.

{
  "ok": true,
  "read_only": true,
  "version": "1.1.2",
  "account": "Empresa de ejemplo",
  "resource": "payments",
  "nombre": "pagos",
  "filters": {
    "id": 4567,
    "date_from": null,
    "date_to": null,
    "date_defaulted": false,
    "invoice_id": null,
    "aquote_id": null,
    "client_id": null,
    "user_id": null,
    "payment_method_id": null,
    "bank_method_id": null,
    "remittance_id": null,
    "document_type": "all",
    "paid": "all",
    "returned": "all",
    "search": null,
    "after_id": 0,
    "limit": 50
  },
  "pagination": {
    "returned": 1,
    "has_more": false,
    "next_after_id": null
  },
  "data": [
    {
      "payment_id": 4567,
      "number": "REC-4567",
      "date": "2026-07-12",
      "amount": 50.0,
      "payment_client_id": null,
      "status": {
        "paid": true,
        "returned": false,
        "counts_towards_balance": true
      },
      "payment_method": {
        "payment_method_id": 2,
        "name": "TRANSFERENCIA"
      },
      "bank_method": {
        "bank_method_id": 1,
        "name": "BANCO PRINCIPAL",
        "accounting_code": "572000001",
        "payment_bank_name": "Cuenta principal"
      },
      "maturity_days": 0,
      "remittance": null,
      "note": "Anticipo registrado originalmente en el albarán",
      "note_truncated": false,
      "inmov": false,
      "allocation": {
        "current_document_type": "invoice",
        "origin_document_type": "delivery_note",
        "transferred_from_delivery_note": true
      },
      "user": {
        "user_id": 3,
        "name": "ANA COMERCIAL"
      },
      "client": {
        "client_id": 949,
        "name": "CLIENTE DE EJEMPLO, S.L.",
        "commercial_name": "CLIENTE EJEMPLO",
        "nif": "B12345678"
      },
      "invoice": {
        "invoice_id": 12345,
        "exists": true,
        "number": "F/2026/00125",
        "reference": "PED-7781",
        "date": "2026-07-15",
        "status_id": 2,
        "amounts": {
          "total": 121.0,
          "paid": 50.0,
          "balance": 71.0
        }
      },
      "delivery_note": {
        "aquote_id": 6789,
        "exists": true,
        "number": "A/2026/00480",
        "reference": "PED-7781",
        "date": "2026-07-10",
        "status_id": 4,
        "linked_invoice_id": 12345,
        "amounts": {
          "total": 121.0,
          "paid": 0.0,
          "balance": 121.0
        }
      }
    }
  ],
  "request_id": "a1b2c3d4e5f60708"
}

06 · 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.2",
  "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"
}

07 · Eventos salientes

Webhooks — cambios en tiempo real

FacturaOne puede enviar automáticamente un POST JSON a una URL de su servidor cuando se emite una factura, se crea o modifica un cliente, o se guarda la ficha de un artículo nuevo o existente. Los webhooks complementan la API de lectura: la API permite consultar, mientras que el webhook avisa de que acaba de producirse un cambio relevante.

Una única URL

Todos los eventos se entregan en la misma dirección configurada en Configuración → API externa. El receptor distingue el tipo mediante X-FacturaOne-Event y event.

Proceso en segundo plano

La emisión de la factura y el guardado del cliente o del artículo no esperan al servidor receptor. La entrega, los reintentos y la auditoría se ejecutan fuera de la petición principal del ERP.

Campos públicos

Los objetos enviados utilizan exclusivamente nombres ya documentados en esta API. No se incluyen XML o JSON fiscales, claves, notas privadas ni columnas internas no publicadas.

API y webhooks son mecanismos independientes

El token X-API-Key sirve únicamente para consultar la API. No se envía dentro del webhook. Para proteger el receptor use HTTPS y un secreto propio, distinto del token de la API, en la URL configurada o en la lógica de su servidor.

Versionado independiente

La API de lectura se encuentra en la versión 1.1.2. La incorporación de resource=payments no modifica la envoltura de webhooks, cuya cabecera X-FacturaOne-Webhook-Version continúa siendo 1.1.1.

Activación y selección de eventos

Abra Configuración → API externa.
Introduzca una URL pública HTTP o, preferentemente, HTTPS.
Seleccione las familias Facturas emitidas, Clientes y/o Artículos.
Guarde la configuración.

Las tres familias aparecen activadas por defecto cuando todavía no existe una preferencia guardada. Dejar la URL vacía desactiva todos los webhooks; desmarcar una familia desactiva únicamente sus eventos.

Eventos disponibles

Evento	Recurso	Se produce cuando	ID principal	Objeto enviado
`invoice.confirmed`	`invoices`	Una factura queda confirmada y emitida.	`invoice_id`	`data.invoice`
`client.created`	`clients`	Se crea una nueva ficha de cliente.	`client_id`	`data.client`
`client.updated`	`clients`	Se guarda o actualiza la ficha de cliente mediante los flujos integrados, incluida su activación o desactivación.	`client_id`	`data.client`
`item.created`	`items`	Se guarda por primera vez una nueva ficha de artículo.	`item_lookup_id`	`data.item`
`item.updated`	`items`	Se pulsa guardar en la ficha de un artículo existente.	`item_lookup_id`	`data.item`

Los cambios de stock no generan webhooks

item.created y item.updated se producen únicamente al guardar la ficha del artículo. Ventas, compras, albaranes, traspasos, recálculos, refrescos y demás modificaciones automáticas de existencias no generan eventos. El campo item_stock incluido en data.item es solo una fotografía del valor existente al guardar; para obtener el stock vigente consulte expresamente resource=items&id=ID_ARTICULO&fields=item_lookup_id,item_stock.

Entrega HTTP

Propiedad	Valor	Comportamiento
Método	`POST`	FacturaOne envía el evento al endpoint configurado.
Contenido	`application/json; charset=utf-8`	El cuerpo contiene un único evento JSON.
Conexión	5 segundos	Tiempo máximo para establecer la conexión.
Respuesta	15 segundos	El receptor debe responder rápidamente; para tareas pesadas conviene guardar el evento en una cola propia.
Confirmación	Cualquier `2xx`	Se considera recibido y no vuelve a intentarse. Se recomienda `204 No Content`.
Reintentos	Máximo 3 intentos	Primer intento inmediato; segundo tras 2 segundos; tercero tras 5 segundos adicionales.
Redirecciones	No se siguen	Configure directamente la URL final del receptor.
Destino	HTTP/HTTPS público	Se bloquean localhost y redes privadas o reservadas.

Cuándo se reintenta

Error de conexión, DNS, timeout o ausencia de respuesta HTTP.
HTTP 408, 425 o 429.
Cualquier respuesta HTTP 5xx.

Cuándo no se reintenta

Cualquier respuesta 2xx.
Errores 4xx distintos de 408, 425 y 429.
URL inválida, destino privado o respuesta que supera el límite permitido.

Cabeceras enviadas

Cabecera	Ejemplo	Uso recomendado
`X-FacturaOne-Event`	`item.updated`	Seleccionar el procesador correspondiente.
`X-FacturaOne-Delivery`	`evt_item_321_...`	Clave de idempotencia. Permanece igual durante los reintentos de la misma entrega.
`X-FacturaOne-Timestamp`	`1785141300`	Instante Unix en el que se inicia el intento HTTP.
`X-FacturaOne-Attempt`	`1`	Número de intento, de 1 a 3.
`X-FacturaOne-Webhook-Version`	`1.1.1`	Versión de la envoltura y del esquema enviado.

El receptor debe ser idempotente

Una interrupción de red puede hacer que FacturaOne reenvíe una entrega ya procesada. Guarde X-FacturaOne-Delivery en una columna con índice UNIQUE antes de aplicar cambios. Si el identificador ya existe, responda igualmente con un código 2xx.

Envoltura común del JSON

Ruta	Tipo	Significado
`id`	`string`	Identificador de entrega; coincide con `X-FacturaOne-Delivery`.
`event`	`string`	Nombre canónico del evento.
`version`	`string`	Versión del payload.
`resource`	`string`	`invoices`, `clients` o `items`.
`occurred_at`	`datetime`	Momento asociado a la confirmación, creación o guardado.
`object_id`	`integer`	ID genérico del objeto afectado.
`invoice_id` / `client_id` / `item_lookup_id`	`integer`	ID específico del recurso.
`data.invoice` / `data.client` / `data.item`	`object`	Datos públicos del objeto afectado.

Contenido de `data.invoice`

Incluye un subconjunto estable de los campos documentados en Facturas emitidas: identificación, fechas, estado, validez, serie, tipo, cliente, emisor, forma de pago, causa de exención, importes e impuestos.

No incluye: líneas de venta, pagos individuales, datos bancarios, beneficio, XML/JSON fiscal, QR, CSV, claves ni notas privadas. Las líneas deben consultarse mediante resource=sales.

Contenido de `data.client`

Incluye exactamente los 24 campos autorizados por resource=clients, desde client_id hasta retencionprofesional. El diccionario completo se encuentra en Recursos y catálogos → Clientes.

Contenido de `data.item`

Incluye exactamente los 29 campos autorizados por resource=items: identificación, fechas, activación, descripción, referencias, precios, impuesto, clasificación e imagen. El diccionario completo se encuentra en Recursos y catálogos → Artículos.

Stock: item_stock representa el valor disponible al guardar la ficha, pero sus cambios posteriores no generan eventos.

Ejemplos abreviados de payload

invoice.confirmedCabecera, cliente, importes e impuestos

Ejemplo abreviado

El evento real contiene todos los campos del subconjunto documentado anteriormente.

{
  "id": "evt_invoice_12345_...",
  "event": "invoice.confirmed",
  "version": "1.1.1",
  "resource": "invoices",
  "occurred_at": "2026-07-27 10:30:00",
  "object_id": 12345,
  "invoice_id": 12345,
  "data": {
    "invoice": {
      "invoice_id": 12345,
      "number": "F/2026/00125",
      "dates": {
        "issued": "2026-07-27",
        "confirmed_at": "2026-07-27 10:30:00"
      },
      "client": {
        "client_id": 949,
        "name": "CLIENTE DE EJEMPLO, S.L.",
        "nif": "B12345678"
      },
      "amounts": {
        "item_subtotal": 100.0,
        "tax_total": 21.0,
        "total": 121.0,
        "balance": 121.0
      },
      "taxes": [
        {
          "tax_rate_id": 1,
          "name": "IVA 21%",
          "percent": 21.0,
          "base": 100.0,
          "tax_amount": 21.0
        }
      ]
    }
  }
}

client.updatedMisma estructura para client.created

Ejemplo abreviado

El evento real contiene los 24 campos autorizados del recurso clients.

{
  "id": "evt_client_949_...",
  "event": "client.updated",
  "version": "1.1.1",
  "resource": "clients",
  "occurred_at": "2026-07-27 10:35:00",
  "object_id": 949,
  "client_id": 949,
  "data": {
    "client": {
      "client_id": 949,
      "client_date_created": "2026-01-15 09:00:00",
      "client_date_modified": "2026-07-27 10:35:00",
      "client_name": "CLIENTE DE EJEMPLO, S.L.",
      "client_name_comercial": "CLIENTE EJEMPLO",
      "client_nif": "B12345678",
      "client_address_1": "Calle Ejemplo 1",
      "client_city": "Madrid",
      "client_zip": "28000",
      "client_country": "España",
      "client_email": "[email protected]",
      "client_active": 1
    }
  }
}

item.updatedMisma estructura para item.created

Ejemplo abreviado

El evento real contiene los 29 campos autorizados del recurso items. item_stock es una fotografía del momento del guardado y no implica suscripción a movimientos de stock.

{
  "id": "evt_item_321_...",
  "event": "item.updated",
  "version": "1.1.1",
  "resource": "items",
  "occurred_at": "2026-07-27T10:40:00+02:00",
  "object_id": 321,
  "item_lookup_id": 321,
  "data": {
    "item": {
      "item_lookup_id": 321,
      "item_create_date": "2026-01-20 11:15:00",
      "item_active": 1,
      "item_is_stock": 1,
      "item_stock": 24.0,
      "item_name": "ARTÍCULO DE EJEMPLO",
      "item_description": "Descripción actual del artículo",
      "item_sku": "SKU-321",
      "item_barcode": "8437000000321",
      "item_unidad": "Ud.",
      "item_price": 12.5,
      "item_tax_rate_id": 1,
      "item_familia": 4
    }
  }
}

Receptor mínimo en PHP

Este ejemplo valida un secreto propio, comprueba el evento y el identificador de entrega, extrae data.invoice, data.client o data.item, lo añade a un log y responde con HTTP 204.

<?php

date_default_timezone_set('Europe/Madrid');

// URL configurada en FacturaOne:
// https://tu-dominio.com/receptor_webhook.php?token=TU_SECRETO_WEBHOOK

$secret = 'CAMBIAR_POR_UN_SECRETO_LARGO_Y_ALEATORIO';
$token  = isset($_GET['token']) ? trim((string)$_GET['token']) : '';

$token_valido = function_exists('hash_equals')
    ? hash_equals($secret, $token)
    : ($secret === $token);

if (!$token_valido) {
    http_response_code(401);
    exit;
}

if (!isset($_SERVER['REQUEST_METHOD']) || $_SERVER['REQUEST_METHOD'] !== 'POST') {
    http_response_code(405);
    exit;
}

$event = isset($_SERVER['HTTP_X_FACTURAONE_EVENT'])
    ? trim((string)$_SERVER['HTTP_X_FACTURAONE_EVENT'])
    : '';
$delivery_id = isset($_SERVER['HTTP_X_FACTURAONE_DELIVERY'])
    ? trim((string)$_SERVER['HTTP_X_FACTURAONE_DELIVERY'])
    : '';

$eventos = array(
    'invoice.confirmed' => 'invoice',
    'client.created'    => 'client',
    'client.updated'    => 'client',
    'item.created'      => 'item',
    'item.updated'      => 'item'
);

$raw = file_get_contents('php://input');
$payload = json_decode($raw, true);

if (
    $delivery_id === ''
    || !isset($eventos[$event])
    || !is_array($payload)
    || !isset($payload['id'])
    || (string)$payload['id'] !== $delivery_id
    || !isset($payload['event'])
    || (string)$payload['event'] !== $event
) {
    http_response_code(400);
    exit;
}

$data_key = $eventos[$event];
$objeto = isset($payload['data'][$data_key])
    ? $payload['data'][$data_key]
    : null;

if (!is_array($objeto)) {
    http_response_code(400);
    exit;
}

// En producción, guarde $delivery_id en una columna UNIQUE antes de procesar.
$linea = date('Y-m-d H:i:s') . ' | ' . $delivery_id . ' | ' . $event . ' | '
       . json_encode($objeto, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES)
       . PHP_EOL;

if (file_put_contents(__DIR__ . '/webhooks_facturaone.log', $linea, FILE_APPEND | LOCK_EX) === false) {
    http_response_code(500);
    exit;
}

// Cualquier 2xx confirma la recepción. 204 evita enviar cuerpo de respuesta.
http_response_code(204);
exit;

No reutilice el token de la API como secreto del webhook

Use un secreto largo y distinto, proteja siempre el endpoint con HTTPS y no deje el archivo de log accesible desde la web. El ejemplo escribe un fichero únicamente para facilitar la primera prueba; en producción conviene registrar la entrega en una base de datos o cola.

Auditoría y consumo

Cada intento de entrega se registra en el mismo sistema de medición de la API. Las facturas aparecen como webhook_invoices, los clientes como webhook_clients y los artículos como webhook_items. Un evento que necesita tres intentos genera tres registros de auditoría y tres consumos de transporte.

08 · Recorrido

Paginación correcta

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

Recursos simples, invoices y payments

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

Añada after_id=12345 y mantenga los demás filtros. En payments, el valor corresponde siempre al último payment_id.

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.

09 · 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_DOCUMENT_TYPE_FILTER`	document_type no es all, invoice, delivery_note, client o unassigned.
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.

10 · Control económico

Consumo, medición y facturación

FacturaOne registra cada consulta de lectura y cada intento de entrega de webhook 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 y entregas

Número de consultas API e intentos de webhook, recurso asociado, 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, incluido payments y las series webhook_invoices, webhook_clients y webhook_items, para detectar qué integración genera el mayor consumo.

El uso efectivo puede generar costes

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

11 · Producción

Seguridad y comprobaciones

Recomendaciones para consultar la API y recibir webhooks sin exponer secretos, duplicar operaciones ni sobrecargar una instalación.

Buenas prácticas

No coloque el token de lectura de la API 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 facturas pagadas, pendientes, anuladas y sustituidas; además de pagos en factura, pagos que siguen en albarán, pagos transferidos desde albarán, devueltos y no asignados.
En webhooks, validar event, id y X-FacturaOne-Delivery, y guardar este último con un índice único.
Responder rápidamente con 2xx y trasladar el trabajo pesado a una cola propia.

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.

12 · Ayuda

Preguntas frecuentes sobre la API y los webhooks 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. La API pública es exclusivamente de lectura y solo admite peticiones GET. Los POST descritos en la sección de webhooks son notificaciones que FacturaOne envía hacia su servidor; no permiten escribir datos en el ERP.

¿Cómo se autentica una integración?

Las consultas API se autentican mediante un token enviado en X-API-Key o Authorization: Bearer; ese token no debe formar parte de la URL. El receptor de webhooks utiliza un secreto independiente definido por la integración.

¿Qué diferencia hay entre la API y los webhooks?

La API se consulta cuando su aplicación necesita leer datos. El webhook se recibe automáticamente cuando FacturaOne emite una factura, crea o modifica un cliente, o guarda la ficha de un artículo. Es habitual usar el webhook como aviso y la API para sincronizaciones completas, recuperaciones y consultas de stock vigente.

¿Qué eventos de webhook están disponibles?

invoice.confirmed, client.created, client.updated, item.created e item.updated. Todos se envían a una única URL y cada familia puede activarse o desactivarse desde Configuración.

¿Se envía un webhook cada vez que cambia el stock?

No. Los eventos de artículos se generan solamente al guardar una ficha nueva o existente. Los movimientos y recálculos de stock no generan webhooks. Para conocer las existencias vigentes consulte resource=items por item_lookup_id y solicite el campo item_stock.

¿Qué debe responder mi receptor?

Cualquier código HTTP 2xx confirma la recepción; se recomienda 204. Los errores de conexión, 408, 425, 429 y 5xx pueden provocar hasta tres intentos con el mismo X-FacturaOne-Delivery.

¿Qué datos puedo consultar?

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

¿Qué diferencia hay entre include_payments=1 y resource=payments?

include_payments=1 añade a cada factura una colección compacta de sus pagos y es útil cuando ya está consultando invoices. resource=payments devuelve una estructura más completa y permite filtrar directamente por albarán, cliente, usuario, forma de pago, banco, remesa, pagado, devuelto y tipo de asignación.

¿Cómo consulto un pago hecho en un albarán que después se facturó?

Consulte resource=payments&aquote_id=ID_ALBARAN. El pago seguirá apareciendo una sola vez. Si ya fue transferido, allocation.current_document_type será invoice, origin_document_type será delivery_note y se devolverán tanto invoice como delivery_note.

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

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

¿Activar la API o los webhooks tiene coste?

Activar la API, generar el token y configurar la URL de webhooks no tiene coste adicional. El uso efectivo de consultas e intentos de entrega 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?

Para una consulta API, envíe el request_id, el recurso y la hora aproximada. Para un webhook, envíe X-FacturaOne-Delivery, X-FacturaOne-Event y la hora aproximada. Nunca envíe secretos 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. Para tiempo real, añada un receptor idempotente que guarde X-FacturaOne-Delivery. Con estas reglas, el conector podrá sincronizar datos y pagos, reaccionar a eventos y controlar su consumo.

Documentación correspondiente a FacturaOne API v1.1.2 y Webhooks v1.1.1. Los ejemplos contienen datos ficticios y los marcadores TU_TOKEN_API y TU_SECRETO_WEBHOOK; nunca publique credenciales reales.

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 API REST y webhooks

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[]

Pagos y cobros — resource=payments

Alias aceptados

Periodo predeterminado

Aplicación actual

Paginación

Filtros disponibles

Valores de document_type

Valores de paid y returned

Ejemplos de consulta

Descubrimiento automático: `resource=resources`

Facturas emitidas — `resource=invoices`

Pagos y cobros — `resource=payments`

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

Contenido de `data.invoice`

Contenido de `data.client`

Contenido de `data.item`