API pública de HolaERP

API REST de lectura para conectar tus sistemas con HolaERP: facturas emitidas y recibidas, clientes, proveedores, artículos y tesorería.

Dirección base: https://api.holaerp.com/v1. Descripción OpenAPI 3.1: /v1/openapi.json, para generar un cliente en tu lenguaje.

Primeros pasos

  1. Tu empresa tiene que tener contratado el acceso por API. Pídeselo a HolaSoft si en Configuración → Integraciones y API no aparece activo.
  2. En Configuración → Integraciones y API → Cuentas y claves, crea una cuenta de integración con el rol que deba tener (lo que el rol no permite, la clave tampoco) y emite una clave de API. La clave se muestra una sola vez: guárdala en un gestor de secretos.
  3. Haz tu primera llamada:
curl https://api.holaerp.com/v1/customers?limit=10 \
  -H "Authorization: Bearer hoe_live_…"

Autenticación

Cada petición lleva la clave en la cabecera Authorization: Bearer <clave>, siempre por HTTPS. Nunca en la URL.

Peticiones y respuestas

Paginación

Los listados se recorren por cursor:

  1. Pide la primera página con los filtros y, si quieres, limit (por defecto 50 o el máximo del listado si es menor).
  2. Si page.nextCursor no es null, pide la siguiente con ?cursor=<nextCursor> y los mismos filtros y limit.
  3. Cuando nextCursor es null, has llegado al final.

El cursor es opaco: no lo construyas ni lo guardes más de 24 horas. Solo vale con la clave que lo recibió; con otros filtros, otro limit o caducado responde 400 PUBLIC_API_INVALID_CURSOR.

Errores

Un error responde con su estado HTTP y este cuerpo. Compara siempre error.code: es estable. El texto es para personas y puede cambiar.

{
  "error": {
    "code": "PERMISSION_DENIED",
    "message": "…",
    "details": { "requestId": "…" }
  }
}
Errores habituales
EstadoCódigoCuándo
400VALIDATION_FAILEDUn parámetro no existe o no es válido. error.errors[] dice cuál.
400PUBLIC_API_INVALID_LIMIT, PUBLIC_API_INVALID_CURSORlimit fuera de rango; cursor manipulado, caducado o de otra consulta.
401UNAUTHORIZED, EXTERNAL_ACCESS_CREDENTIAL_INVALID, EXTERNAL_ACCESS_CREDENTIAL_EXPIREDSin clave, o clave inválida, revocada o caducada.
403PERMISSION_DENIED, MODULE_NOT_CONTRACTEDLa clave no tiene el permiso, o tu empresa no tiene ese módulo.
403EXTERNAL_ACCESS_NOT_ENABLED, EXTERNAL_ACCESS_CHANNEL_DISABLED, EXTERNAL_ACCESS_IP_NOT_ALLOWEDEl acceso por API no está activo para tu empresa o en este momento, o la IP no está en la lista de la clave.
404NOT_FOUND, PUBLIC_API_ROUTE_NOT_FOUNDEl recurso no existe en tu empresa, o la ruta no existe.
429RATE_LIMITEDCuota agotada. Espera los segundos de Retry-After.
503SERVICE_UNAVAILABLENo disponible temporalmente. Reintenta con espera creciente.

Límites

Cada llamada gasta cuota de su clase, por clave y por empresa, en ventanas de un minuto. Estos son los valores por defecto; tu empresa puede tenerlos más bajos.

Llamadas por minuto
ClaseQuéPor clavePor empresa
readFichas y agregados120600
listListados60300

Las cabeceras RateLimit-Limit, RateLimit-Remaining y RateLimit-Reset dicen cuánto queda. Al agotarla, 429 con Retry-After. Las peticiones sin clave válida tienen un límite de 20 por minuto y por IP.

Versionado

Entorno de pruebas

Para desarrollar tu integración sin tocar datos reales, usa el entorno de pruebas: https://api-dev.holaerp.com/v1, con una empresa de demostración y datos ficticios.

Referencia

Generada del registro de capacidades, igual que el OpenAPI.

Clientes

GET /v1/customers

Clientes

Lista los clientes de la empresa con los filtros de la pantalla «Clientes»: texto, archivados, rol comercial, población, régimen fiscal y país del NIF. Por cliente: id, nombre, razón social, país del NIF, rol, régimen fiscal, estado VIES, población, forma y plazo de pago por defecto y fechas. Sin NIF, email ni teléfono.

Respuesta
Listado paginado: { "data": [ … ], "page": { "nextCursor": … } }. limit por defecto 50, máximo 100.
Permiso
facturacion.clientes.read
Cuota
list
Capacidad
facturacion_clientes_listar, versión 1
Parámetros de /v1/customers
NombreDóndeTipoObligatorioDescripción
q consulta texto (hasta 255) No Texto libre: nombre, razón social, NIF o contacto principal, sin acentos.
includeArchived consulta true o false No true para incluir los archivados, que por defecto no salen.
commercialRole consulta uno de: customer, supplier, both No Rol efectivo: both = cliente y proveedor; customer o supplier = solo ese.
city consulta texto (hasta 120) No Población, contiene.
taxRegime consulta uno de: general, equivalence_surcharge, simplified, agricultural, recc, rebu, not_applicable No Régimen fiscal.
taxIdCountry consulta texto No País del NIF (ISO 3166-1 alfa-2).
sortBy consulta uno de: name, legalName, createdAt No Orden. Por defecto name.
sortOrder consulta uno de: asc, desc No Sentido del orden.
limit consulta entero de 1 a 100 No Elementos por página, de 1 al máximo del listado. Se fija en la primera página: con cursor, el mismo o ninguno.
cursor consulta texto No Cursor opaco de page.nextCursor para pedir la página siguiente, con los mismos filtros y la misma clave. Caduca en 24 horas.
Campos de cada elemento de data
CampoTipoDescripción
entityId identificador Id
name texto Nombre
legalName texto Razón social
taxIdCountry código País del NIF
commercialRole código Rol comercial
isCustomer código Es cliente
isSupplier código Es proveedor
taxRegime código Régimen fiscal
viesStatus código Estado VIES
city texto Población
defaultPaymentMethodId identificador Id de la forma de pago
defaultPaymentTermsId identificador Id del plazo de pago
archivedAt fecha y hora ISO 8601 Archivado el
createdAt fecha y hora ISO 8601 Alta
updatedAt fecha y hora ISO 8601 Modificado el

GET /v1/customers/{customerId}

El cliente

Devuelve la ficha de UN cliente: nombre, razón social, país del NIF, rol, régimen fiscal, estado VIES, población y valores por defecto de facturación (forma y plazo de pago, moneda, impuesto, tarifa, idioma, límite de crédito). No devuelve el NIF, el email, el teléfono, las direcciones ni las cuentas bancarias.

Respuesta
Un recurso: { "data": { … } }.
Permiso
facturacion.clientes.read
Cuota
read
Capacidad
facturacion_cliente_ver, versión 1
Parámetros de /v1/customers/{customerId}
NombreDóndeTipoObligatorioDescripción
customerId ruta texto (uuid) Sí Id del cliente (campo entityId del listado).
Campos de data
CampoTipoDescripción
entityId identificador Id
name texto Nombre
legalName texto Razón social
taxIdCountry código País del NIF
commercialRole código Rol comercial
isCustomer código Es cliente
isSupplier código Es proveedor
taxRegime código Régimen fiscal
viesStatus código Estado VIES
city texto Población
defaultPaymentMethodId identificador Id de la forma de pago
defaultPaymentTermsId identificador Id del plazo de pago
archivedAt fecha y hora ISO 8601 Archivado el
createdAt fecha y hora ISO 8601 Alta
updatedAt fecha y hora ISO 8601 Modificado el
defaultCurrencyCode código Moneda
defaultDueDays entero Días de vencimiento
defaultTaxCodeId identificador Id del impuesto
defaultPriceListId identificador Id de la tarifa
documentLanguage código Idioma de los documentos
creditLimit importe (cadena decimal), 2 decimales Límite de crédito
isExportDefault código Exportación
isIntracomDefault código Intracomunitario
internalReference texto Referencia interna

Facturas emitidas

GET /v1/invoices

Facturas emitidas

Lista las facturas de venta (emitidas) de la empresa con los mismos filtros que la pantalla «Facturas emitidas». Úsala para preguntas sobre facturas concretas o sobre qué se ha facturado: por estado, cliente, serie, fechas de emisión, cobro, o estado de FACe, SII o Veri*Factu. Devuelve un conjunto de datos (datasetId, total, muestra de hasta 20 filas y las columnas) con, por factura: id, número, tipo, estado, fechas de emisión y vencimiento, cliente, moneda, total, cobrado y estados fiscales. Hasta 2.000 filas, las más recientes primero. Para sumar, agrupar por mes o por cliente o sacar rankings NO calcules tú: llama después a estadisticas_calcular con el datasetId. Con status vacío salen también los borradores, que no están facturados: para importes facturados filtra por estado. Las rectificativas (invoiceKind = rectifying) corrigen facturas anteriores y vienen en el mismo listado. No devuelve las líneas ni el desglose de impuestos (para eso, facturacion_factura_emitida_ver) ni las facturas recibidas de proveedores.

Respuesta
Listado paginado: { "data": [ … ], "page": { "nextCursor": … } }. limit por defecto 50, máximo 200.
Permiso
facturacion.invoices.view
Cuota
list
Capacidad
facturacion_facturas_emitidas_listar, versión 1
Parámetros de /v1/invoices
NombreDóndeTipoObligatorioDescripción
q consulta texto (hasta 255) No Texto libre: busca en el número de factura y en el nombre del cliente.
status consulta lista (repite el parámetro) de uno de: draft, issued, partially_paid, paid, overdue, rectified No Estados a incluir. Sin este filtro salen también los borradores (sin número ni fecha): para lo ya facturado usa issued, partially_paid, paid y overdue.
invoiceKind consulta uno de: normal, rectifying, simplified No normal, rectifying (rectificativa) o simplified (simplificada).
customerEntityId consulta texto (uuid) No Id de un cliente (campo customerEntityId o entityId de otra consulta).
seriesId consulta texto (uuid) No Id de una serie de facturación.
issueDateFrom consulta fecha AAAA-MM-DD No Fecha de emisión desde, inclusive (AAAA-MM-DD). Excluye los borradores.
issueDateTo consulta fecha AAAA-MM-DD No Fecha de emisión hasta, inclusive (AAAA-MM-DD).
faceStatus consulta lista (repite el parámetro) de uno de: not_applicable, pending, presented, accepted, paid, rejected, cancelled, error No Estados de presentación en FACe (facturas a Administraciones Públicas).
siiStatus consulta lista (repite el parámetro) de uno de: not_applicable, pending, accepted, accepted_with_errors, rejected No Estados del envío al SII de la AEAT.
siiOverdue consulta true o false No true: solo las facturas del SII en cola con el plazo legal ya vencido.
verifactuStatus consulta lista (repite el parámetro) de uno de: not_applicable, pending, accepted, accepted_with_warnings, rejected, recorded No Estados del envío a Veri*Factu.
includeArchived consulta true o false No true para incluir las archivadas, que por defecto no salen.
archivedOnly consulta true o false No true para listar SOLO las archivadas (la vista «Archivadas» de la pantalla). Gana a includeArchived.
sortBy consulta uno de: issueDate, invoiceNumber, total, createdAt No Orden del listado. Por defecto issueDate.
sortOrder consulta uno de: asc, desc No Por defecto desc (lo último primero).
limit consulta entero de 1 a 200 No Elementos por página, de 1 al máximo del listado. Se fija en la primera página: con cursor, el mismo o ninguno.
cursor consulta texto No Cursor opaco de page.nextCursor para pedir la página siguiente, con los mismos filtros y la misma clave. Caduca en 24 horas.
Campos de cada elemento de data
CampoTipoDescripción
id identificador Id de la factura
invoiceNumber texto Número
invoiceKind código Tipo de factura. Valores conocidos: normal Normal, rectifying Rectificativa, simplified Simplificada.
status código Estado. Valores conocidos: draft Borrador, issued Emitida, partially_paid Cobro parcial, paid Cobrada, overdue Vencida, rectified Rectificada.
issueDate fecha ISO 8601 Fecha de emisión
dueDate fecha ISO 8601 Fecha de vencimiento
customerEntityId identificador Id del cliente
customerDisplayName texto Cliente
currencyCode código Moneda
total importe (cadena decimal), 2 decimales Total
amountPaid importe (cadena decimal), 2 decimales Cobrado
verifactuStatus código Estado Veri*Factu. Valores conocidos: not_applicable No aplica, pending Pendiente, accepted Aceptada, accepted_with_warnings Aceptada con avisos, rejected Rechazada, recorded Registrada sin envío.
siiStatus código Estado SII. Valores conocidos: not_applicable No aplica, pending Pendiente, accepted Aceptada, accepted_with_errors Aceptada con errores, rejected Rechazada.
faceStatus código Estado FACe. Valores conocidos: not_applicable No aplica, pending Pendiente de presentar, presented Presentada en FACe, accepted Obligación reconocida, paid Pagada, rejected Rechazada por la Administración, cancelled Anulada, error Error al presentar.

GET /v1/invoices/{invoiceId}

La factura

Devuelve la ficha de UNA factura emitida: número, tipo, estado, fechas, cliente, totales (subtotal, descuentos, base imponible, impuestos, retenciones, total y cobrado) y estado en Veri*Factu, SII y FACe. Úsala cuando el usuario pregunta por una factura concreta o tiene una abierta en pantalla; necesita el id de la factura, que sale de facturacion_facturas_emitidas_listar (columna id). No devuelve las líneas (facturacion_factura_emitida_lineas) ni el desglose por tipo de impuesto (facturacion_factura_emitida_impuestos), ni los vencimientos o los cobros uno a uno. Para varias facturas usa el listado.

Respuesta
Un recurso: { "data": { … } }.
Permiso
facturacion.invoices.view
Cuota
read
Capacidad
facturacion_factura_emitida_ver, versión 1
Parámetros de /v1/invoices/{invoiceId}
NombreDóndeTipoObligatorioDescripción
invoiceId ruta texto (uuid) Sí Id de la factura (campo id del listado de facturas emitidas).
Campos de data
CampoTipoDescripción
header.invoiceNumber texto Número
header.invoiceKind código Tipo de factura. Valores conocidos: normal Normal, rectifying Rectificativa, simplified Simplificada.
header.status código Estado. Valores conocidos: draft Borrador, issued Emitida, partially_paid Cobro parcial, paid Cobrada, overdue Vencida, rectified Rectificada.
header.issueDate fecha ISO 8601 Fecha de emisión
header.operationDate fecha ISO 8601 Fecha de la operación
header.dueDate fecha ISO 8601 Primer vencimiento
header.paidAt fecha y hora ISO 8601 Cobrada el
header.customerEntityId identificador Id del cliente
header.customer.legalName texto Cliente
header.customer.countryCode código País del cliente
header.currencyCode código Moneda
header.totals.subtotal importe (cadena decimal), 2 decimales Subtotal
header.totals.totalDiscount importe (cadena decimal), 2 decimales Descuentos
header.totals.taxableBase importe (cadena decimal), 2 decimales Base imponible
header.totals.totalTax importe (cadena decimal), 2 decimales Impuestos
header.totals.totalRetention importe (cadena decimal), 2 decimales Retenciones
header.totals.totalEquivalenceSurcharge importe (cadena decimal), 2 decimales Recargo de equivalencia
header.totals.roundingAdjustment importe (cadena decimal), 2 decimales Ajuste de redondeo
header.totals.total importe (cadena decimal), 2 decimales Total
header.totals.amountPaid importe (cadena decimal), 2 decimales Cobrado
header.verifactu.status código Estado Veri*Factu. Valores conocidos: not_applicable No aplica, pending Pendiente, accepted Aceptada, accepted_with_warnings Aceptada con avisos, rejected Rechazada, recorded Registrada sin envío.
header.sii.status código Estado SII. Valores conocidos: not_applicable No aplica, pending Pendiente, accepted Aceptada, accepted_with_errors Aceptada con errores, rejected Rechazada.
header.face.status código Estado FACe. Valores conocidos: not_applicable No aplica, pending Pendiente de presentar, presented Presentada en FACe, accepted Obligación reconocida, paid Pagada, rejected Rechazada por la Administración, cancelled Anulada, error Error al presentar.
header.rectification.rectificationType código Tipo de rectificación. Valores conocidos: substitution Por sustitución, by_difference Por diferencias.
header.rectification.parentInvoiceId identificador Id de la factura que rectifica
hasIssuedRectification código Tiene una rectificativa emitida

Artículos

GET /v1/items

Artículos

Lista los artículos del catálogo con los mismos filtros que la pantalla «Artículos»: texto, tipo, estado, familias, impuestos, fecha de alta, si tienen variantes y si se venden. El tipo (kind) es la naturaleza: product, service, digital o expense. Que un artículo tenga variantes (hasVariants, con variantCount) o sea un pack (bundleExpansionMode: lines, de sueltos; none, empaquetado) va aparte; una variante lleva variantLabel. Devuelve un conjunto de datos (datasetId, total, muestra de hasta 20 filas y las columnas) con, por artículo: id, referencia, nombre, tipo, si tiene variantes, variante, pack, familia, unidad, precio de venta y si se vende, lleva existencias y está activo. Hasta 1.000 filas. Para contar o agrupar (por familia, por tipo) llama después a estadisticas_calcular con el datasetId. Para exportar el listado a un fichero genera el informe facturacion.articulos.catalog con los filtros renombrados: q → q, kind → kind (un solo tipo), hasVariants → has_variants, isPack → is_pack (o catalogType pack_lines / pack_none), categoryId → category_id, isSellable → is_sellable, isActive → is_active, includeArchived → include_archived. Con importJobId (lo importado en una importación de datos), el informe no puede filtrar por la importación: saldría el catálogo entero. Dilo antes de generarlo y ofrece la lista o las cuentas en el chat. No devuelve precios de compra ni existencias por almacén ni ventas del artículo (para eso, facturacion_ventas_por_articulo).

Respuesta
Listado paginado: { "data": [ … ], "page": { "nextCursor": … } }. limit por defecto 50, máximo 100.
Permiso
facturacion.articulos.read
Cuota
list
Capacidad
facturacion_articulos_listar, versión 1
Parámetros de /v1/items
NombreDóndeTipoObligatorioDescripción
q consulta texto (hasta 255) No Texto libre: busca sin tildes en la referencia, el nombre y la variante, y el código de barras exacto.
catalogType consulta lista (repite el parámetro) de uno de: product, service, digital, expense, pack_lines, pack_none No Tipo tal como lo ve la pantalla, varios a la vez: product, service, digital y expense son la naturaleza y no incluyen los packs; pack_lines (pack de artículos sueltos) y pack_none (pack empaquetado), los packs.
kind consulta lista (repite el parámetro) de uno de: product, service, digital, expense No Naturaleza (product, service, digital, expense), packs incluidos.
hasVariants consulta true o false No true: solo las cabeceras de artículos con variantes; false: todo lo demás, variantes incluidas.
isPack consulta true o false No true: solo los packs; false: lo que no es un pack.
groupVariants consulta true o false No true, como la pantalla: las variantes no salen como filas, solo su cabecera (el total es el de la pantalla). Las variantes de una cabecera se piden con parentArticleId.
parentArticleId consulta texto (uuid) No Solo las variantes de esa cabecera (su id).
status consulta lista (repite el parámetro) de uno de: active, inactive, archived No Estados, varios a la vez: active, inactive (sin archivar y apagado) y archived. Si viene, manda sobre isActive e includeArchived.
categoryId consulta texto (uuid) No Id de una familia de artículos.
categoryIds consulta lista (repite el parámetro) de texto (uuid) No Ids de varias familias: casa el artículo que esté en alguna.
taxCodeIds consulta lista (repite el parámetro) de texto (uuid) No Ids de los impuestos de venta por defecto del artículo.
createdFrom consulta fecha AAAA-MM-DD No Dado de alta desde, inclusive (AAAA-MM-DD).
createdTo consulta fecha AAAA-MM-DD No Dado de alta hasta, inclusive (AAAA-MM-DD).
isSellable consulta true o false No true: solo los que se venden; false: solo los que no. Sin él, todos.
isActive consulta true o false No true: solo los activos; false: solo los inactivos. Sin él, todos.
includeArchived consulta true o false No true devuelve SOLO los archivados (no los suma a los vivos).
importJobId consulta texto (uuid) No Solo los artículos que creó o actualizó esa importación de datos (el listado abierto desde «Ver lo importado»).
sortBy consulta uno de: name, code, kind, createdAt No Orden del listado. Por defecto name.
sortOrder consulta uno de: asc, desc No Por defecto asc.
limit consulta entero de 1 a 100 No Elementos por página, de 1 al máximo del listado. Se fija en la primera página: con cursor, el mismo o ninguno.
cursor consulta texto No Cursor opaco de page.nextCursor para pedir la página siguiente, con los mismos filtros y la misma clave. Caduca en 24 horas.
Campos de cada elemento de data
CampoTipoDescripción
id identificador Id del artículo
code texto Referencia
name texto Nombre
kind código Tipo. Valores conocidos: product Producto, service Servicio, digital Digital, expense Gastos.
hasVariants código Con variantes
variantCount entero Variantes
variantLabel texto Variante
bundleExpansionMode código Pack. Valores conocidos: lines Pack de artículos sueltos, none Pack empaquetado.
categoryName texto Familia
unitCode código Unidad
basePrice importe (cadena decimal), 6 decimales Precio de venta
isSellable código Se vende
isStocked código Lleva existencias
isActive código Activo

GET /v1/items/{itemId}

El artículo

Devuelve la ficha de UN artículo: referencia, nombre, descripción, tipo, estructura (variantes o pack), unidad, precio de venta, impuesto de venta por defecto, familia, código de barras y estado. No devuelve el precio de compra, las variantes una a una, la composición ni las existencias.

Respuesta
Un recurso: { "data": { … } }.
Permiso
facturacion.articulos.read
Cuota
read
Capacidad
facturacion_articulo_ver, versión 1
Parámetros de /v1/items/{itemId}
NombreDóndeTipoObligatorioDescripción
itemId ruta texto (uuid) Sí Id del artículo (campo id del listado de artículos).
Campos de data
CampoTipoDescripción
id identificador Id del artículo
code texto Referencia
name texto Nombre
description texto Descripción
kind código Tipo
hasVariants código Con variantes
parentArticleId identificador Id de la cabecera
variantLabel texto Variante
variantCount entero Variantes
bundleExpansionMode código Pack
componentCount entero Componentes
unitCode código Unidad
unitName texto Nombre de la unidad
basePrice importe (cadena decimal), 6 decimales Precio de venta
priceStrategy código Estrategia de precio
defaultTaxCode.code texto Impuesto
defaultTaxCode.name texto Nombre del impuesto
defaultTaxCode.rate porcentaje (cadena decimal) Tipo del impuesto
categoryId identificador Id de la familia
categoryName texto Familia
barcode texto Código de barras
isSellable código Se vende
isStocked código Lleva existencias
isActive código Activo
archivedAt fecha y hora ISO 8601 Archivado el
createdAt fecha y hora ISO 8601 Alta
updatedAt fecha y hora ISO 8601 Modificado el

Facturas recibidas

GET /v1/purchase-invoices

Facturas recibidas

Lista las facturas recibidas de proveedores con los filtros de la pantalla «Facturas recibidas»: texto, estado, tipo, proveedor y fechas. Por factura: id, número y serie del proveedor, tipo, estado, fechas, proveedor, moneda, totales, pagado, cotejo y estado SII. Sin NIF ni dirección del proveedor.

Respuesta
Listado paginado: { "data": [ … ], "page": { "nextCursor": … } }. limit por defecto 50, máximo 100.
Permiso
facturacion.purchase_invoices.view
Cuota
list
Capacidad
facturacion_facturas_recibidas_listar, versión 1
Parámetros de /v1/purchase-invoices
NombreDóndeTipoObligatorioDescripción
q consulta texto (hasta 255) No Texto libre: número, serie, referencia o proveedor.
status consulta lista (repite el parámetro) de uno de: draft, recorded, partially_paid, paid, disputed, rectified No Estados a incluir. Sin este filtro salen también los borradores.
invoiceKind consulta uno de: normal, rectifying, simplified, import No Tipo de factura recibida.
supplierEntityId consulta texto (uuid) No Id de un proveedor.
dateFrom consulta fecha AAAA-MM-DD No Fecha de la factura desde, inclusive (AAAA-MM-DD).
dateTo consulta fecha AAAA-MM-DD No Fecha de la factura hasta, inclusive (AAAA-MM-DD).
includeArchived consulta true o false No true para incluir las archivadas, que por defecto no salen.
sortBy consulta uno de: issueDate, receivedDate, accountingDate, supplierInvoiceNumber, total, createdAt No Orden. Por defecto createdAt.
sortOrder consulta uno de: asc, desc No Sentido del orden.
limit consulta entero de 1 a 100 No Elementos por página, de 1 al máximo del listado. Se fija en la primera página: con cursor, el mismo o ninguno.
cursor consulta texto No Cursor opaco de page.nextCursor para pedir la página siguiente, con los mismos filtros y la misma clave. Caduca en 24 horas.
Campos de cada elemento de data
CampoTipoDescripción
id identificador Id de la factura
supplierInvoiceNumber texto Número del proveedor
supplierSeries texto Serie del proveedor
internalReference texto Referencia interna
invoiceKind código Tipo de factura
status código Estado
issueDate fecha ISO 8601 Fecha de la factura
operationDate fecha ISO 8601 Fecha de la operación
receivedDate fecha ISO 8601 Fecha de recepción
accountingDate fecha ISO 8601 Fecha contable
dueDate fecha ISO 8601 Primer vencimiento
supplierEntityId identificador Id del proveedor
supplierCountryCode código País del proveedor
currencyCode código Moneda
amountPaid importe (cadena decimal), 2 decimales Pagado
paidAt fecha y hora ISO 8601 Pagada el
matchingStatus código Cotejo
sii.status código Estado SII
parentPurchaseInvoiceId identificador Id de la factura que rectifica
archivedAt fecha y hora ISO 8601 Archivada el
createdAt fecha y hora ISO 8601 Creada el
updatedAt fecha y hora ISO 8601 Modificada el
supplierName texto Proveedor
totals.subtotal importe (cadena decimal), 2 decimales Subtotal
totals.totalDiscount importe (cadena decimal), 2 decimales Descuentos
totals.taxableBase importe (cadena decimal), 2 decimales Base imponible
totals.totalTax importe (cadena decimal), 2 decimales Impuestos
totals.totalRetention importe (cadena decimal), 2 decimales Retenciones
totals.totalEquivalenceSurcharge importe (cadena decimal), 2 decimales Recargo de equivalencia
totals.total importe (cadena decimal), 2 decimales Total

GET /v1/purchase-invoices/{purchaseInvoiceId}

La factura recibida

Devuelve la cabecera de UNA factura recibida: número y serie del proveedor, tipo, estado, fechas, proveedor, moneda, totales, pagado, cotejo y estado SII. No devuelve las líneas, el desglose de impuestos, los vencimientos ni el NIF o la dirección del proveedor.

Respuesta
Un recurso: { "data": { … } }.
Permiso
facturacion.purchase_invoices.view
Cuota
read
Capacidad
facturacion_factura_recibida_ver, versión 1
Parámetros de /v1/purchase-invoices/{purchaseInvoiceId}
NombreDóndeTipoObligatorioDescripción
purchaseInvoiceId ruta texto (uuid) Sí Id de la factura recibida (campo id del listado de facturas recibidas).
Campos de data
CampoTipoDescripción
header.id identificador Id de la factura
header.supplierInvoiceNumber texto Número del proveedor
header.supplierSeries texto Serie del proveedor
header.internalReference texto Referencia interna
header.invoiceKind código Tipo de factura
header.status código Estado
header.issueDate fecha ISO 8601 Fecha de la factura
header.operationDate fecha ISO 8601 Fecha de la operación
header.receivedDate fecha ISO 8601 Fecha de recepción
header.accountingDate fecha ISO 8601 Fecha contable
header.dueDate fecha ISO 8601 Primer vencimiento
header.supplierEntityId identificador Id del proveedor
header.supplierCountryCode código País del proveedor
header.currencyCode código Moneda
header.amountPaid importe (cadena decimal), 2 decimales Pagado
header.paidAt fecha y hora ISO 8601 Pagada el
header.matchingStatus código Cotejo
header.sii.status código Estado SII
header.parentPurchaseInvoiceId identificador Id de la factura que rectifica
header.archivedAt fecha y hora ISO 8601 Archivada el
header.createdAt fecha y hora ISO 8601 Creada el
header.updatedAt fecha y hora ISO 8601 Modificada el
header.supplierLegalName texto Proveedor (razón social)
totals.subtotal importe (cadena decimal), 2 decimales Subtotal
totals.totalDiscount importe (cadena decimal), 2 decimales Descuentos
totals.taxableBase importe (cadena decimal), 2 decimales Base imponible
totals.totalTax importe (cadena decimal), 2 decimales Impuestos
totals.totalRetention importe (cadena decimal), 2 decimales Retenciones
totals.totalEquivalenceSurcharge importe (cadena decimal), 2 decimales Recargo de equivalencia
totals.total importe (cadena decimal), 2 decimales Total

Proveedores

GET /v1/suppliers

Proveedores

Lista los proveedores de la empresa con los filtros de la pantalla «Proveedores»: texto, archivados, rol comercial, población, régimen fiscal y país del NIF. Por proveedor: id, nombre, razón social, país del NIF, rol, régimen fiscal, estado VIES, población, forma y plazo de pago por defecto y fechas. Sin NIF, email, teléfono ni IBAN.

Respuesta
Listado paginado: { "data": [ … ], "page": { "nextCursor": … } }. limit por defecto 50, máximo 100.
Permiso
facturacion.proveedores.read
Cuota
list
Capacidad
facturacion_proveedores_listar, versión 1
Parámetros de /v1/suppliers
NombreDóndeTipoObligatorioDescripción
q consulta texto (hasta 255) No Texto libre: nombre, razón social, NIF o contacto principal, sin acentos.
includeArchived consulta true o false No true para incluir los archivados, que por defecto no salen.
commercialRole consulta uno de: customer, supplier, both No Rol efectivo: both = cliente y proveedor; customer o supplier = solo ese.
city consulta texto (hasta 120) No Población, contiene.
taxRegime consulta uno de: general, equivalence_surcharge, simplified, agricultural, recc, rebu, not_applicable No Régimen fiscal.
taxIdCountry consulta texto No País del NIF (ISO 3166-1 alfa-2).
sortBy consulta uno de: name, legalName, createdAt No Orden. Por defecto name.
sortOrder consulta uno de: asc, desc No Sentido del orden.
limit consulta entero de 1 a 100 No Elementos por página, de 1 al máximo del listado. Se fija en la primera página: con cursor, el mismo o ninguno.
cursor consulta texto No Cursor opaco de page.nextCursor para pedir la página siguiente, con los mismos filtros y la misma clave. Caduca en 24 horas.
Campos de cada elemento de data
CampoTipoDescripción
entityId identificador Id
name texto Nombre
legalName texto Razón social
taxIdCountry código País del NIF
commercialRole código Rol comercial
isCustomer código Es cliente
isSupplier código Es proveedor
taxRegime código Régimen fiscal
viesStatus código Estado VIES
city texto Población
defaultPaymentMethodId identificador Id de la forma de pago
defaultPaymentTermsId identificador Id del plazo de pago
archivedAt fecha y hora ISO 8601 Archivado el
createdAt fecha y hora ISO 8601 Alta
updatedAt fecha y hora ISO 8601 Modificado el

GET /v1/suppliers/{supplierId}

El proveedor

Devuelve la ficha de UN proveedor: nombre, razón social, país del NIF, rol, régimen fiscal, estado VIES, población y valores por defecto de facturación (forma y plazo de pago, moneda, impuesto, tarifa, idioma). No devuelve el NIF, el email, el teléfono, las direcciones ni las cuentas bancarias.

Respuesta
Un recurso: { "data": { … } }.
Permiso
facturacion.proveedores.read
Cuota
read
Capacidad
facturacion_proveedor_ver, versión 1
Parámetros de /v1/suppliers/{supplierId}
NombreDóndeTipoObligatorioDescripción
supplierId ruta texto (uuid) Sí Id del proveedor (campo entityId del listado).
Campos de data
CampoTipoDescripción
entityId identificador Id
name texto Nombre
legalName texto Razón social
taxIdCountry código País del NIF
commercialRole código Rol comercial
isCustomer código Es cliente
isSupplier código Es proveedor
taxRegime código Régimen fiscal
viesStatus código Estado VIES
city texto Población
defaultPaymentMethodId identificador Id de la forma de pago
defaultPaymentTermsId identificador Id del plazo de pago
archivedAt fecha y hora ISO 8601 Archivado el
createdAt fecha y hora ISO 8601 Alta
updatedAt fecha y hora ISO 8601 Modificado el
defaultCurrencyCode código Moneda
defaultDueDays entero Días de vencimiento
defaultTaxCodeId identificador Id del impuesto
defaultPriceListId identificador Id de la tarifa
documentLanguage código Idioma de los documentos
creditLimit importe (cadena decimal), 2 decimales Límite de crédito
isExportDefault código Exportación
isIntracomDefault código Intracomunitario
internalReference texto Referencia interna

Tesorería

GET /v1/treasury/bank-position

El saldo de los bancos

Devuelve la posición de Tesorería: una fila por banco propio con su saldo (el contable y, si el banco no lo da, el disponible; balanceKind dice cuál) y su saldo disponible, la fecha y el origen del saldo (banco conectado o último extracto importado), los movimientos pendientes de conciliar y el estado de la conexión bancaria. Úsala para preguntas del tipo «¿cuánto tengo en bancos?», «¿cuánto hay en BBVA?», «¿qué cuentas tengo conectadas?» o «¿cuándo caduca la conexión?». Para el total, suma balanceBooked con estadisticas_calcular y agrupa por currencyCode: no mezcles monedas. Si balanceKind es «available», ese saldo es el disponible del banco y no el contable (hay bancos que no dan el contable): dilo así al responder. Un balanceBooked vacío significa que NO se conoce el saldo de esa cuenta (no hay extracto ni lectura del banco): no es cero, no lo sumes ni lo cuentes como cero, y dilo. Los saldos son los del último dato: mira siempre balanceReferenceDate antes de decir «hoy». No devuelve movimientos (para eso, tesoreria_movimientos_por_conciliar), no concilia ni conecta bancos, y no incluye el IBAN.

Respuesta
Una sola página: { "data": [ … ], "page": { "nextCursor": null } }.
Permiso
uno de facturacion.treasury.bank_connections.view, facturacion.treasury.bank_statements.view
Cuota
read
Capacidad
tesoreria_posicion_bancaria, versión 1
Parámetros de /v1/treasury/bank-position
NombreDóndeTipoObligatorioDescripción
companyId consulta texto (uuid) No Id de una empresa emisora. Sin él salen los bancos de todas.
Campos de cada elemento de data
CampoTipoDescripción
bankAccountId identificador Id del banco propio
alias texto Cuenta
currencyCode código Moneda
balanceBooked importe (cadena decimal), 2 decimales Saldo de la cuenta (contable o, si el banco no lo da, disponible)
balanceKind código Tipo de saldo. Valores conocidos: booked Contable, available Disponible (el banco no da el contable).
balanceAvailable importe (cadena decimal), 2 decimales Saldo disponible
balanceReferenceDate fecha ISO 8601 Fecha del saldo
balanceSource código Origen del saldo. Valores conocidos: api Banco conectado, statement Extracto importado.
unreconciledCount entero Movimientos sin conciliar
unreconciledAmount importe (cadena decimal), 2 decimales Importe sin conciliar
institutionName texto Banco conectado
connectionStatus código Estado de la conexión. Valores conocidos: pending_authorization Pendiente de autorizar, linked Conectada, expired Caducada, suspended Suspendida, rejected Rechazada, cancelled Cancelada, revoked Revocada, disconnected Desconectada, suspended_unlicensed Suspendida por falta de licencia.
connectionHealth código Estado de la sincronización. Valores conocidos: ok Sincronizando con normalidad, processing Sincronizando ahora, rate_limited Límite del banco alcanzado, failing Con errores, suspended Suspendida, revoked Revocada, expired Caducada.
lastSyncedDate fecha ISO 8601 Última sincronización
accessExpiresDate fecha ISO 8601 La conexión caduca

GET /v1/treasury/cash-forecast

La previsión de tesorería

Devuelve la previsión de tesorería a 30, 60 o 90 días: el saldo de hoy de los bancos, los cobros y pagos previstos según los vencimientos de las facturas pendientes, el saldo previsto al final del horizonte y el punto más bajo (el día y el saldo en que menos dinero habrá). Una sola fila. Úsala para preguntas del tipo «¿me va a faltar dinero este mes?», «¿cuál es mi saldo previsto a 60 días?» o «¿cuándo estaré más justo de caja?». Si lowestPointBalance es negativo, falta dinero ese día: dilo con la fecha. Elige el horizonte que pide el usuario (30 por defecto). Parte del saldo conocido de los bancos: si accountsWithoutBalance es mayor que cero, esas cuentas no están incluidas y la previsión es incompleta; avísalo en la respuesta. Lo vencido sin cobrar ni pagar sale aparte (overdueCollections y overduePayments) salvo que se pida includeOverdue. Es una proyección con los vencimientos tal como están, no una garantía de cobro. Va en una sola moneda y no la convierte. No devuelve el desglose por días ni por factura: para eso, la pantalla Panel financiero de Finanzas. Mínimo de seguridad: con companyId devuelve minimumBalance (vacío si la empresa no lo tiene), minimumBreachDate y minimumBreachBalance (el primer día en que el saldo previsto baja del mínimo y el saldo de ese día) y, hasta tres, los pagos más grandes hasta ese día (paymentBeforeBreach1…3: tipo, concepto o número, proveedor, fecha e importe). Para explicar «¿por qué me avisa del mínimo?» pide horizonDays 90 sin includeOverdue, que es como se calcula el aviso, y nombra la fecha y los pagos que coinciden. Si minimumBreachDate está vacío, la previsión no baja del mínimo en el horizonte.

Respuesta
Una sola página: { "data": [ … ], "page": { "nextCursor": null } }.
Permiso
facturacion.treasury.forecast.view
Cuota
read
Capacidad
tesoreria_prevision, versión 1
Parámetros de /v1/treasury/cash-forecast
NombreDóndeTipoObligatorioDescripción
horizonDays consulta uno de: 30, 60, 90 No Días a mirar hacia delante: 30, 60 o 90. Por defecto 30.
currency consulta texto No Moneda de la previsión, de tres letras. Por defecto EUR. No se convierten monedas.
includeOverdue consulta true o false No true para sumar a la previsión lo vencido sin cobrar ni pagar. Por defecto no se suma y sale aparte.
companyId consulta texto (uuid) No Id de la empresa emisora. Con él la previsión es solo de esa empresa y trae su mínimo de seguridad, el día en que el saldo previsto baja de él y los pagos más grandes hasta ese día. Sin él, todas las empresas y sin mínimo.
Campos de cada elemento de data
CampoTipoDescripción
currencyCode código Moneda
horizonDays entero Horizonte (días)
startingBalance importe (cadena decimal), 2 decimales Saldo de hoy
accountsWithoutBalance entero Cuentas sin saldo conocido
expectedCollections importe (cadena decimal), 2 decimales Cobros previstos
expectedPayments importe (cadena decimal), 2 decimales Pagos previstos
endingBalance importe (cadena decimal), 2 decimales Saldo previsto al final
lowestPointDate fecha ISO 8601 Día del saldo más bajo
lowestPointBalance importe (cadena decimal), 2 decimales Saldo más bajo previsto
overdueCollections importe (cadena decimal), 2 decimales Cobros vencidos
overduePayments importe (cadena decimal), 2 decimales Pagos vencidos
overdueIncluded código Vencidos incluidos
minimumBalance importe (cadena decimal), 2 decimales Mínimo de seguridad
minimumBreachDate fecha ISO 8601 Día en que baja del mínimo
minimumBreachBalance importe (cadena decimal), 2 decimales Saldo previsto ese día
paymentBeforeBreach1Kind texto Pago 1 antes del cruce: tipo
paymentBeforeBreach1Concept texto Pago 1 antes del cruce: concepto o número
paymentBeforeBreach1ThirdParty texto Pago 1 antes del cruce: proveedor
paymentBeforeBreach1Date fecha ISO 8601 Pago 1 antes del cruce: fecha
paymentBeforeBreach1Amount importe (cadena decimal), 2 decimales Pago 1 antes del cruce: importe
paymentBeforeBreach2Kind texto Pago 2 antes del cruce: tipo
paymentBeforeBreach2Concept texto Pago 2 antes del cruce: concepto o número
paymentBeforeBreach2ThirdParty texto Pago 2 antes del cruce: proveedor
paymentBeforeBreach2Date fecha ISO 8601 Pago 2 antes del cruce: fecha
paymentBeforeBreach2Amount importe (cadena decimal), 2 decimales Pago 2 antes del cruce: importe
paymentBeforeBreach3Kind texto Pago 3 antes del cruce: tipo
paymentBeforeBreach3Concept texto Pago 3 antes del cruce: concepto o número
paymentBeforeBreach3ThirdParty texto Pago 3 antes del cruce: proveedor
paymentBeforeBreach3Date fecha ISO 8601 Pago 3 antes del cruce: fecha
paymentBeforeBreach3Amount importe (cadena decimal), 2 decimales Pago 3 antes del cruce: importe

GET /v1/treasury/unreconciled-bank-lines

Movimientos bancarios sin conciliar

Lista los movimientos bancarios que todavía no están conciliados con una factura, un cobro o un pago, como la cola de la pantalla de Conciliación de Tesorería: por movimiento, la fecha, el importe con signo (negativo es un cargo o salida, positivo un ingreso), la moneda, la contraparte y el origen (banco conectado o fichero importado). Úsala para preguntas del tipo «¿qué movimientos me faltan por conciliar?», «¿cuántos cargos sin conciliar hay?» o «¿qué ingresos sin conciliar tiene BBVA?». Filtra por banco propio (bankAccountId) y por fechas. Devuelve un conjunto de datos (hasta 1.000 filas, las más recientes primero): para contar, sumar, agrupar o filtrar por importe (por ejemplo los cargos de más de 1.000 €, que son los de amount menor o igual a -1000) llama después a estadisticas_calcular con el datasetId; no calcules tú. Solo salen los que están sin conciliar, no los conciliados en parte ni los ignorados. No concilia, no clasifica ni registra cobros o pagos: si el usuario quiere hacerlo, indícale la pantalla de Conciliación.

Respuesta
Listado paginado: { "data": [ … ], "page": { "nextCursor": … } }. limit por defecto 50, máximo 100.
Permiso
facturacion.treasury.bank_statements.view
Cuota
list
Capacidad
tesoreria_movimientos_por_conciliar, versión 1
Parámetros de /v1/treasury/unreconciled-bank-lines
NombreDóndeTipoObligatorioDescripción
bankAccountId consulta texto (uuid) No Id de un banco propio (campo bankAccountId de tesoreria_posicion_bancaria).
dateFrom consulta fecha AAAA-MM-DD No Movimientos desde esta fecha, inclusive (AAAA-MM-DD).
dateTo consulta fecha AAAA-MM-DD No Movimientos hasta esta fecha, inclusive (AAAA-MM-DD).
limit consulta entero de 1 a 100 No Elementos por página, de 1 al máximo del listado. Se fija en la primera página: con cursor, el mismo o ninguno.
cursor consulta texto No Cursor opaco de page.nextCursor para pedir la página siguiente, con los mismos filtros y la misma clave. Caduca en 24 horas.
Campos de cada elemento de data
CampoTipoDescripción
id identificador Id del movimiento
transactionDate fecha ISO 8601 Fecha
amount importe (cadena decimal), 2 decimales Importe
amountRemaining importe (cadena decimal), 2 decimales Pendiente de conciliar
currencyCode código Moneda
counterpartyName texto Contraparte
origin código Origen. Valores conocidos: api Banco conectado, file Fichero importado.
status código Estado. Valores conocidos: unreconciled Sin conciliar, partially_reconciled Conciliado en parte, reconciled Conciliado, ignored Ignorado.