Documentación Finanzas

Autenticación

Query params

Respuesta (HTTP 200) — con facturas previas

{
  "success": true,
  "tieneFacturas": true,
  "fecha": "2026-08-31",
  "referencia": 118
}

Respuesta (HTTP 200) — sin facturas todavía en esa plantilla+año

{
  "success": true,
  "tieneFacturas": false
}

Cómo usarla

• Si tieneFacturas es false: cualquier fecha de hoy hacia atrás es válida (sujeto también a la regla general de no facturar en el futuro).
• Si tieneFacturas es true: tu nueva factura debe tener fecha >= fecha (la de esta respuesta). Si va a ser anterior, el POST la rechazará — resuelve la fecha antes de intentarlo.

Errores posibles

• 400 Bad Request: falta idPlantillasFactura.
• 401 Unauthorized: token ausente o inválido.
• 403 Forbidden: facturación no activa.
• 500 Internal Server Error: error interno.

{
  "error": "Falta idPlantillasFactura"
}

Notas

• La numeración es por plantilla+año, compartida entre todos los documentos que uses en esa serie — no es exclusiva de un cliente o envío concreto.
• Es la misma comprobación que usa internamente Shipping antes de lanzar la facturación automática de envíos, para avisar de un posible rechazo antes de esperar a que termine el proceso.

Query params

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

Query params

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

Query params

Respuesta (HTTP 200)

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

Qué id devuelve: motor legacy vs motor V2

Cada cuenta usa uno de los dos motores de plantillas, y el id que devuelve este endpoint es siempre el que hay que enviar como idPlantillasFactura en el resto de endpoints (crear factura, última fecha, listado, años). No hace falta que sepas en qué motor estás: usa el id de aquí y ya está.

• Motor legacy: el id es el de la plantilla clásica. El campo legacyId no aparece.
• Motor V2: el id es el de la plantilla V2, y legacyId trae la plantilla clásica equivalente, o null si esa plantilla V2 se creó ya en V2 y no tiene equivalente.

El legacyId es informativo: sirve para casar documentos antiguos, emitidos antes de la migración, que solo llevan ese identificador. Una serie puede tener documentos guardados de las dos formas, así que cualquier consulta por serie (numeración, años, listado) tiene en cuenta las dos — no hace falta que hagas dos llamadas.

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

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.

Parámetros

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.

Parámetros

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.

Parámetros

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.