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, su referencia.
  • 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}]'
CampoObligatorioUso
codclienteSíCliente existente.
lineasSí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, horaNoPor defecto, la actual.
codalmacen, coddivisa, codserie, codpagoNoPor defecto, los del cliente o de la empresa.
pagadaNo1 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

MensajeHTTPQué hacer
codcliente field is required / customer-not-found400 / 404Envía un codcliente existente.
lineas field is required / Invalid lines400Envía lineas como texto JSON válido con un array.
Fecha no válida400Usa dd-mm-aaaa y un ejercicio abierto.
record-save-error / error calculando totales422El 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.

Captura ampliada

Abrir en otra pestaña

¿Te ha resultado útil esta página?

¿Aún tienes dudas?

Habla con nuestro equipo y te resolvemos cualquier duda al instante.