Desarrolladores: integrar tu software con la API de Beply
Facturas
Uso de la API para trabajar con facturas y documentos de venta.
Actualizado el 22 de octubre de 2026
Crear, cobrar, rectificar y exportar facturas con la API
Para facturas con líneas usa las funciones: calculan totales e impuestos con la misma lógica que la pantalla. Esta guía crea una factura de venta, la marca como cobrada, la rectifica y descarga su PDF.
Aplicabilidad: API versión 3 · Plan Profesional, con la API activada en el servicio.
Antes de empezar
- Clave con permiso POST sobre
crearFacturaCliente(y sobre las demás funciones que uses). - El código del cliente (
codcliente) y, si usas productos del catálogo, sureferencia. - Un ejercicio abierto para la fecha de la factura.
1. Crear la factura
lineas es un texto JSON dentro del formulario:
curl -s -X POST "$BEPLY_URL/api/3/crearFacturaCliente" -H "Token: $BEPLY_TOKEN" \
--data-urlencode "codcliente=<CODCLIENTE>" \
--data-urlencode "fecha=15-01-2026" \
--data-urlencode 'lineas=[{"referencia":"SERV-MES","cantidad":1},{"descripcion":"Desplazamiento","cantidad":1,"pvpunitario":25}]'
| Campo | Obligatorio | Uso |
|---|---|---|
codcliente | Sí | Cliente existente. |
lineas | Sí | Array JSON. Por línea: referencia (opcional, toma descripción y precio del producto), descripcion, cantidad (1 si falta), pvpunitario, dtopor, dtopor2, codimpuesto, excepcioniva. |
fecha, hora | No | Por defecto, la actual. |
codalmacen, coddivisa, codserie, codpago | No | Por defecto, los del cliente o de la empresa. |
pagada | No | 1 marca como pagados todos los recibos al crear. |
Respuesta correcta (HTTP 200): {"doc": {… "idfactura": 123, "codigo": "…"}, "lines": [ … ]}. Guarda doc.idfactura: lo necesitas para el resto de operaciones.
2. Marcar como cobrada
curl -s -X POST "$BEPLY_URL/api/3/pagarFacturaCliente/<IDFACTURA>" -H "Token: $BEPLY_TOKEN" \
--data-urlencode "pagada=1" --data-urlencode "fechapago=20-01-2026"
Marca como pagados todos sus recibos (opcionalmente con fechapago y codpago). Con pagada=0 los deja pendientes. Repetir la misma petición es seguro: si no hay cambios responde «ok» sin modificar nada. Para cobros parciales usa el programa (Registrar un cobro parcial).
3. Rectificar
curl -s -X POST "$BEPLY_URL/api/3/crearFacturaRectificativaCliente" -H "Token: $BEPLY_TOKEN" \
--data-urlencode "idfactura=<IDFACTURA>" --data-urlencode "fecha=25-01-2026"
idfactura y fecha son obligatorios. Sin más campos se devuelven todas las cantidades; para devolver parte de una línea envía refund_<idlinea>=<cantidad>.
4. Descargar el PDF
curl -s -o factura.pdf "$BEPLY_URL/api/3/exportarFacturaCliente/<IDFACTURA>" -H "Token: $BEPLY_TOKEN"
Devuelve el archivo, no JSON. Parámetros opcionales: type (por defecto PDF), format (formato de impresión) y lang. Los errores (registro inexistente, método distinto de GET) sí llegan en JSON.
Comprueba el resultado
En el programa, Ventas → Facturas muestra la factura con el mismo total que doc.total; tras el paso 2, su recibo aparece pagado.
Si algo falla
| Mensaje | HTTP | Qué hacer |
|---|---|---|
codcliente field is required / customer-not-found | 400 / 404 | Envía un codcliente existente. |
lineas field is required / Invalid lines | 400 | Envía lineas como texto JSON válido con un array. |
| Fecha no válida | 400 | Usa dd-mm-aaaa y un ejercicio abierto. |
record-save-error / error calculando totales | 422 | El programa rechazó el documento: no se ha creado nada (la operación es atómica). Corrige el dato y repite. |
Evita duplicados: crearFacturaCliente crea una factura nueva en cada llamada. Si una petición se corta sin respuesta, busca antes la factura (por ejemplo GET /api/3/facturaclientes?filter[codcliente]=…&filter[fecha]=…) y repite solo si no existe. Una factura emitida no se borra para «deshacer»: se rectifica.