Z-Bombilla API - Finanzas

Resumen

Auth: Bearer Content-Type: application/json Salida: id, rand, referencia

Tip: el campo id_plantillasFactura controla numeraci�n, tipo y validaciones.

Autenticaci�n

Cabecera	Valor	Oblig.
`Authorization`	`Bearer {accessToken}`	S�
`Content-Type`	`application/json`	S�

Requisitos previos

El token debe pertenecer a un usuario v�lido.
La cuenta debe tener facturaci�n activa (FacturacionUsuarioSettings.activo=true).
id_plantillasFactura debe existir y pertenecer al rol.

Body (JSON)

Par�metro	Tipo	Oblig.	Descripci�n
`id_plantillasFactura`	int	S�	ID de la plantilla. Determina numeraci�n, tipo y validaciones.
`fecha`	string	No	Fecha ISO `YYYY-MM-DD`. Si no se env�a, se usa la fecha del d�a.
`razonSocial`	string	No	Raz�n social del cliente.
`cif`	string	No	CIF/NIF.
`email`	string	No	Email.
`telefono`	string	No	Tel�fono.
`direccion`	string	No	Direcci�n.
`codigoPostal`	string	No	C�digo postal.
`poblacion`	string	No	Poblaci�n.
`provincia`	string	No	Provincia.
`pais`	string	No	Pa�s ISO-2. Por defecto `ES`.
`iva`	number	No	IVA % cabecera. Por defecto 21.
`irpf`	number	No	IRPF % (puede ser 0).
`re`	number	No	Recargo equivalencia % (puede ser 0).
`formaPago`	string	No	Texto libre. Si no existe, el sistema puede crearlo autom�ticamente (seg�n reglas del rol).
`ch_pagado`	boolean	No	true = pendiente (NO pagado). false = pagado. Si no se env�a, se asume false.
`observaciones`	string	No	Observaciones del documento.
`comment`	string	No	Comentario interno.
`detalles`	array	No	Listado de l�neas. Si no se env�a, se crea el documento sin l�neas.
`detalles[].id`	int	No	Solo en edici�n: id de l�nea existente.
`detalles[].producto`	string	No	Referencia / SKU (si vac�o, puede normalizar a `-`).
`detalles[].desc`	string	S�*	Descripci�n (obligatoria si hay l�nea).
`detalles[].uds`	number	No	Unidades (por defecto 1).
`detalles[].precio`	number	No	Precio neto (recomendado hasta 3 decimales).
`detalles[].iva`	number	No	IVA % de l�nea.
`detalles[].dto`	number	No	Descuento %.
`detalles[].orden`	number	No	Orden de l�nea (si no, por posici�n).
`totalIva`	number	No	Informativo. El sistema recalcula los totales.
`baseImponible`	number	No	Informativo. El sistema recalcula los totales.

* Importante: si env�as detalles, cada l�nea debe tener al menos desc.

Respuesta esperada (HTTP 200)

{
  "success": true,
  "id": 123,
  "rand": 123456789,
  "referencia": "INV-ES-00001",
  "fecha": "2026-01-01",
  "url": "https://finanzas.z-bombilla.com/...",
  "total": 121,
  "iva": 21,
  "neto": 100,
  "irpf": 0,
  "re": 0,
  "message": "Documento creado correctamente."
}

Notas de edici�n de l�neas

Las l�neas con detalles[].id se actualizan.
Las l�neas sin id se crean.
Las l�neas existentes que no se incluyan en detalles se eliminan.

Errores posibles

400 Bad Request: validaciones fallidas (plantilla, campos requeridos, etc.).
401 Unauthorized: token ausente o inv�lido.
403 Forbidden: facturaci�n no activa.
404 Not Found: documento no encontrado o no pertenece al rol.
500 Internal Server Error: error interno.

{
  "success": false,
  "error": "Falta campo obligatorio: id_plantillasFactura"
}

Notas adicionales

La numeraci�n (referencia) y el rand se generan autom�ticamente al crear.
Se recomienda enviar precio con decimales (hasta 3) para minimizar redondeos.

Autenticaci�n

Cabecera	Valor	Oblig.
`Authorization`	`Bearer {accessToken}`	S�

Resumen

Filtro: tipo, plantilla, year, pagado? Paginaci�n: pageNumber / pageSize Orden: orderField / orderDir

Query params

Par�metro	Tipo	Oblig.	Descripci�n
`tipo`	string	No	`todos` (por defecto) o un valor de `Plantilla.TipoDocumento`. Ej: `FACTURA`, `RECTIFICACIONES`.
`idPlantillasFactura`	int	No	Filtra por plantilla concreta. Si no se env�a, se usan todas las plantillas del tipo/rol.
`q`	string	No	B�squeda por texto libre (cliente, email, cif...). Si incluye n�meros, se intenta filtrar tambi�n por referencia.
`pagado`	boolean	No	`true` o `false`.
`year`	int	No	A�o del documento (ej. `2026`).
`importeMin`	number	No	Importe m�nimo del total del documento.
`importeMax`	number	No	Importe m�ximo del total del documento.
`pageNumber`	int	No	P�gina (por defecto 1).
`pageSize`	int	No	Tama�o de p�gina (por defecto 50). Recomendado m�ximo 100.
`orderField`	string	No	Campo de ordenaci�n permitido: `id`, `fecha`, `referencia`, `razonSocial`, `chPagado`, `totalGrossAmount`.
`orderDir`	string	No	`ASC` o `DESC` (por defecto ASC si no es DESC).

Respuesta (HTTP 200)

Devuelve filas, total y a�os disponibles para el conjunto actual (tipo/plantilla).

{
  "rows": [
    {
      "id": 123,
      "pagado": false,
      "numero": "INV-ES-00001",
      "fecha": "01/01/2026",
      "cliente": "Cliente SL",
      "total": "121,00 ?",
      "comment": "Revisar",
      "rand": 123456789
    }
  ],
  "total": 1,
  "yearsAvailable": [2026, 2025, 2024]
}

Errores posibles

401 Unauthorized: token ausente o inv�lido.
403 Forbidden: facturaci�n no activa.
400 Bad Request: par�metros inv�lidos.
500 Internal Server Error: error interno.

{
  "error": "Usuario no autenticado"
}

Notas

yearsAvailable est� ordenado de m�s reciente a m�s antiguo.
Los campos total y fecha vienen formateados (human friendly).

Autenticaci�n

Cabecera	Valor	Oblig.
`Authorization`	`Bearer {accessToken}`	S�

Query params

Par�metro	Tipo	Oblig.	Descripci�n
`tipo`	string	No	`todos` (por defecto) o un valor de `Plantilla.TipoDocumento` (ej: `FACTURA`).
`idPlantillasFactura`	int	No	Si se env�a, devuelve los a�os disponibles solo para esa plantilla.

Respuesta (HTTP 200)

{
  "yearsAvailable": [2026, 2025, 2024]
}

Errores posibles

401 Unauthorized: token ausente o inv�lido.
403 Forbidden: facturaci�n no activa.
400 Bad Request: par�metros inv�lidos.
500 Internal Server Error: error interno.

{
  "error": "Usuario no autenticado"
}

Notas

�til para construir selectores de a�o en integraciones/ERP.

Autenticaci�n

Cabecera	Valor	Oblig.
`Authorization`	`Bearer {accessToken}`	S�

Query params

Par�metro	Tipo	Oblig.	Descripci�n
`tipo`	string	No	`todos` (por defecto) o un valor de `Plantilla.TipoDocumento` (ej: `FACTURA`).

Respuesta (HTTP 200)

{
  "success": true,
  "rows": [
    { "id": 12, "nombre": "Factura Nacional" },
    { "id": 13, "nombre": "Factura UE" }
  ]
}

Errores posibles

401 Unauthorized: token ausente o inv�lido.
403 Forbidden: facturaci�n no activa.
400 Bad Request: tipo inv�lido.
500 Internal Server Error: error interno.

{
  "error": "Usuario no autenticado"
}

Notas

�til para construir selectores de plantilla en integraciones.
Si no se env�a tipo, devuelve todas las plantillas activas del rol.

Autenticaci�n

Cabecera	Valor	Oblig.
`Authorization`	`Bearer {accessToken}`	S�

Descripci�n

El resumen se calcula sobre documentos del rol que cumplan la condici�n de pendiente seg�n la l�gica de backend.
Suele limitarse a plantillas de tipo FACTURA activas (seg�n implementaci�n).

Respuesta (HTTP 200)

{
  "count": 5,
  "totalImporte": 1234.56
}

Errores posibles

401 Unauthorized: token ausente o inv�lido.
403 Forbidden: facturaci�n no activa.
500 Internal Server Error: error interno.

{
  "error": "Cuenta de facturaci�n no activa"
}

Notas

totalImporte es num�rico (no formateado). �til para dashboards/KPIs.

Resumen

Auth: Bearer Par�metro: id (query) Acci�n: toggle pagado/pendiente

Comportamiento: si estaba pagado ? pasa a pendiente; si estaba pendiente ? pasa a pagado.

Autenticaci�n

Cabecera	Valor	Oblig.
`Authorization`	`Bearer {accessToken}`	S�

Par�metros

Par�metro	Ubicaci�n	Tipo	Oblig.	Descripci�n
`id`	query	int	S�	ID del documento (Factura) a modificar.

Respuesta (HTTP 200)

{
  "success": true,
  "pagado": true
}

Errores posibles

400 Bad Request: id inv�lido o ausente.
401 Unauthorized: token ausente o inv�lido.
403 Forbidden: facturaci�n no activa.
404 Not Found: documento no encontrado o fuera del rol.
500 Internal Server Error: error interno.

{
  "error": "Factura no encontrada"
}

Notas

Se registra la acci�n en el log del sistema.

Resumen

Auth: Bearer Par�metros: id, comment (query) Uso: notas internas / seguimiento

Nota: el comentario es interno (no necesariamente visible al cliente final).

Autenticaci�n

Cabecera	Valor	Oblig.
`Authorization`	`Bearer {accessToken}`	S�

Par�metros

Par�metro	Ubicaci�n	Tipo	Oblig.	Descripci�n
`id`	query	int	S�	ID del documento.
`comment`	query	string	No	Nuevo comentario (texto libre). Si no se env�a o viene vac�o, se guarda vac�o/null seg�n implementaci�n.

Respuesta (HTTP 200)

{
  "success": true
}

Errores posibles

400 Bad Request: id inv�lido o ausente.
401 Unauthorized: token ausente o inv�lido.
403 Forbidden: facturaci�n no activa.
404 Not Found: documento no encontrado o fuera del rol.
500 Internal Server Error: error interno.

{
  "error": "Factura no encontrada"
}

Notas

Se registra la acci�n en el log del sistema.

Resumen

Auth: Bearer Par�metro: id (query) Acci�n: borra cabecera + l�neas

Atenci�n: puede devolver 409 Conflict si aplica reglas de negocio (presentado o numeraci�n posterior).

Autenticaci�n

Cabecera	Valor	Oblig.
`Authorization`	`Bearer {accessToken}`	S�

Par�metros

Par�metro	Ubicaci�n	Tipo	Oblig.	Descripci�n
`id`	query	int	S�	ID del documento a eliminar.

Validaciones (resumen)

El documento debe existir y pertenecer al rol del token.
Si el documento es de tipo FACTURA o RECTIFICACIONES:
- No puede estar presentado (seg�n periodoFin en backend).
- No puede haber documentos posteriores con numeraci�n mayor en el mismo a�o/plantilla.

Respuesta (HTTP 200)

{
  "success": true
}

Errores posibles

400 Bad Request: id inv�lido o ausente.
401 Unauthorized: token ausente o inv�lido.
403 Forbidden: facturaci�n no activa.
404 Not Found: documento no encontrado o fuera del rol.
409 Conflict: no se puede eliminar por reglas de negocio (presentado o numeraci�n posterior).
500 Internal Server Error: error interno.

Ejemplo de error 409

{
  "error": "No se puede eliminar esta factura porque existen facturas con numeraci�n posterior en 2026."
}

Notas

Se registra la acci�n en el log del sistema cuando la eliminaci�n es correcta.
Este endpoint elimina tambi�n las l�neas asociadas al documento.

Documentaci�n Finanzas

/apiV2/documentos/facturas Crear factura / documento

Resumen

Autenticaci�n

Requisitos previos

Body (JSON)

Respuesta esperada (HTTP 200)

/apiV2/documentos/facturas?id={id} Editar documento existente

Notas de edici�n de l�neas

Errores posibles

Notas adicionales

/apiV2/documentos Listado paginado de documentos

Autenticaci�n

Resumen

Query params

Respuesta (HTTP 200)

Errores posibles

Notas

/apiV2/documentos/years A�os disponibles

Autenticaci�n

Query params

Respuesta (HTTP 200)

Errores posibles

Notas

/apiV2/documentos/plantillas Plantillas disponibles

Autenticaci�n

Query params

Respuesta (HTTP 200)

Errores posibles

Notas

/apiV2/documentos/pendientes/summary Pendientes: resumen

Autenticaci�n

Descripci�n

Respuesta (HTTP 200)

Errores posibles

Notas

/apiV2/documentos/togglePagado Cambiar estado pagado

Resumen

Autenticaci�n

Par�metros

Respuesta (HTTP 200)

Errores posibles

Notas

/apiV2/documentos/updateComment Actualizar comentario

Resumen

Autenticaci�n

Par�metros

Respuesta (HTTP 200)

Errores posibles

Notas

/apiV2/documentos/delete Eliminar documento

Resumen

Autenticaci�n

Par�metros

Validaciones (resumen)

Respuesta (HTTP 200)

Errores posibles

Ejemplo de error 409

Notas