04 — Facturas

Las facturas son el recurso más usado de la API. Beply expone tanto operaciones genéricas REST (GET, POST, PUT, DELETE sobre /facturaclientes o /facturaproveedores) como endpoints especializados para los flujos completos (crear factura con líneas, marcar como pagada, rectificativa, exportar PDF).

Todas las facturas emitidas vía API se procesan en VeriFactu (o TicketBAI/SII según domicilio fiscal): hash, encadenado, QR y envío a Hacienda son automáticos.

Crear una factura de cliente

Endpoint dedicado que crea cabecera y líneas en una sola llamada.

Petición

POST https://<tu-instancia>.beply.es/api/3/crearFacturaCliente
Content-Type: application/x-www-form-urlencoded
Token: <tu-api-key>

Campos del body

Campo	Tipo	Requerido	Descripción
`codcliente`	string	✅	Código del cliente al que se factura
`lineas`	JSON string	✅	Array JSON con las líneas (ver abajo)
`pagada`	int	–	`1` si está cobrada al emitir, `0` (default) si pendiente
`fecha`	date	–	Fecha de emisión, por defecto hoy. Envío: `YYYY-MM-DD` (ej. `2026-05-20`).
`hora`	time (HH:MM:SS)	–	Hora de emisión
`codpago`	string	–	Forma de pago (`TRANSF`, `EFECT`, `TARJETA`…)
`codserie`	string	–	Serie de facturación
`direccion`, `ciudad`, `provincia`, `codpostal`	string	–	Datos del destinatario si difieren del cliente

Estructura de cada línea

Campo	Tipo	Requerido	Descripción
`referencia`	string	✅ (o `descripcion`)	Referencia de un producto del catálogo
`descripcion`	string	✅ (o `referencia`)	Texto libre si la línea no es un producto
`cantidad`	number	–	Por defecto `1`
`pvpunitario`	number	–	Precio por unidad. Si la línea referencia un producto, se toma del catálogo
`dtopor`	number	–	Descuento %
`dtopor2`	number	–	Segundo descuento % (en cascada)
`codimpuesto`	string	–	Código del IVA aplicable (`IVA21`, `IVA10`…)
`irpf`	number	–	% de retención IRPF

Ejemplo con cURL

curl https://miempresa.beply.es/api/3/crearFacturaCliente \
  -H "Token: a1b2c3d4..." \
  -d "codcliente=1" \
  -d 'lineas=[{"referencia":"PROD-001","cantidad":2},{"descripcion":"Mano de obra","cantidad":1,"pvpunitario":35.00,"codimpuesto":"IVA21"}]' \
  -d "pagada=0" \
  -d "codpago=TRANSF"

Ejemplo con JavaScript

const params = new URLSearchParams()
params.set('codcliente', '1')
params.set('lineas', JSON.stringify([
  { referencia: 'PROD-001', cantidad: 2 },
  { descripcion: 'Mano de obra', cantidad: 1, pvpunitario: 35.00, codimpuesto: 'IVA21' },
]))
params.set('pagada', '0')
params.set('codpago', 'TRANSF')

const res = await fetch('https://miempresa.beply.es/api/3/crearFacturaCliente', {
  method: 'POST',
  headers: { 'Token': 'a1b2c3d4...' },
  body: params,
})
const factura = await res.json()

Respuesta de éxito (HTTP 200)

crearFacturaCliente devuelve la factura y sus líneas en dos campos separados:

{
  "doc": {
    "idfactura": "1",
    "codigo": "FAC2026A1",
    "codcliente": "1",
    "codejercicio": "2026",
    "codserie": "A",
    "numero": "1",
    "fecha": "20-05-2026",
    "hora": "14:27:16",
    "neto": 85,
    "totaliva": 17.85,
    "total": 102.85,
    "pagada": false,
    "vencida": true,
    "editable": true,
    "codpago": "TRANSF",
    "codalmacen": "ALG",
    "coddivisa": "EUR"
  },
  "lines": [
    {
      "idlinea": 1,
      "idfactura": 1,
      "referencia": "PROD-001",
      "descripcion": "Producto del catálogo",
      "cantidad": 2,
      "pvpunitario": 25,
      "pvptotal": 50,
      "iva": 21,
      "codimpuesto": "IVA21"
    },
    {
      "idlinea": 2,
      "idfactura": 1,
      "descripcion": "Mano de obra",
      "cantidad": 1,
      "pvpunitario": 35,
      "pvptotal": 35,
      "iva": 21,
      "codimpuesto": "IVA21"
    }
  ]
}

📋 Notas sobre la respuesta:

Tipos: idfactura viene como string ("1") dentro de doc, pero como int (1) dentro de cada línea. Es asimetría heredada — si compilas en TypeScript estricto, normaliza al recibir (Number(doc.idfactura)).

Formato de fechas: envías en YYYY-MM-DD (ISO), pero las respuestas vienen en DD-MM-YYYY. Si tu integración necesita un formato concreto, conviértelo al recibir. Ver README — Formato de fechas.

Código de factura: sigue el patrón FAC{año}{serie}{numero} (ej. FAC2026A1).

IVA: se calcula automáticamente al aplicar codimpuesto.

VeriFactu: si la cuenta lo tiene activado, los campos hash, qr_url y datos de envío a la AEAT se devuelven dentro de doc.

Marcar una factura como pagada

POST https://<tu-instancia>.beply.es/api/3/pagarFacturaCliente/<idfactura>

Body

Campo	Tipo	Requerido	Descripción
`fechapago`	date	✅	Fecha en la que se cobró. Envío: `YYYY-MM-DD`.
`codpago`	string	✅	Forma de pago (`TRANSF`, `EFECT`, `TARJETA`…)
`pagada`	int	✅	`1` para marcar pagada, `0` para revertir

Ejemplo

curl https://miempresa.beply.es/api/3/pagarFacturaCliente/5821 \
  -H "Token: a1b2c3d4..." \
  -d "fechapago=2026-05-25" \
  -d "codpago=TRANSF" \
  -d "pagada=1"

Para facturas de proveedor usa pagarFacturaProveedor/<id> con los mismos campos.

Crear factura rectificativa

POST https://<tu-instancia>.beply.es/api/3/crearFacturaRectificativaCliente

Body

Campo	Tipo	Requerido	Descripción
`idfactura`	int	✅	ID de la factura original a rectificar
`fecha`	date	–	Fecha de la rectificación
`hora`	time	–	Hora
`refund_<idlinea>`	number	–	Cantidad a devolver de la línea con ID `<idlinea>`

Ejemplo: devolver 2 unidades de la línea 1782

curl https://miempresa.beply.es/api/3/crearFacturaRectificativaCliente \
  -H "Token: a1b2c3d4..." \
  -d "idfactura=5821" \
  -d "fecha=2026-05-22" \
  -d "refund_1782=2"

La rectificativa se enlaza automáticamente con la original mediante el campo idfacturarect.

ℹ️ Sobre las líneas: solo se incluyen en la rectificativa las líneas que indiques con refund_<idlinea>. Las líneas de la factura original que NO referencias quedan como están (no se rectifican). Para una rectificación total, envía un refund_<idlinea> por cada línea de la factura original con la cantidad completa.

Comprobar si una factura ya fue rectificada

curl "https://miempresa.beply.es/api/3/facturaclientes?filter[idfacturarect]=5821" \
  -H "Token: a1b2c3d4..."

Si la respuesta es una lista vacía, no ha sido rectificada.

Exportar el PDF de una factura

GET https://<tu-instancia>.beply.es/api/3/exportarFacturaCliente/<idfactura>

Parámetros opcionales (query string)

Param	Default	Descripción
`type`	`PDF`	Formato: `PDF`, `XLS`, `CSV`
`lang`	configurado	Código de idioma (`es_ES`, `en_EN`…)
`format`	predeterminado	ID numérico de un formato de impresión personalizado

Ejemplo

curl https://miempresa.beply.es/api/3/exportarFacturaCliente/5821?type=PDF \
  -H "Token: a1b2c3d4..." \
  -o factura.pdf

La respuesta es un binario (el archivo en sí), no JSON.

Endpoints análogos para otros documentos:

exportarAlbaranCliente/<id>
exportarPedidoCliente/<id>
exportarPresupuestoCliente/<id>
exportarFacturaProveedor/<id>

Disponible desde la versión 2024.5 del motor.

Listar y filtrar facturas

Usa la operación genérica GET /api/3/facturaclientes con los parámetros de 02 — Listar, filtrar y ordenar.

Ejemplos útiles

Facturas pendientes de cobro de los últimos 30 días:

GET /api/3/facturaclientes?filter[pagada]=0&filter[fecha_gte]=2026-04-20

Facturas de un cliente concreto ordenadas por fecha desc:

GET /api/3/facturaclientes?filter[codcliente]=1&sort[fecha]=DESC

Facturas con importe superior a 1.000 €:

GET /api/3/facturaclientes?filter[total_gt]=1000

Facturas de proveedor

Todos los endpoints anteriores tienen su equivalente para proveedores:

Cliente	Proveedor
`crearFacturaCliente`	`crearFacturaProveedor`
`pagarFacturaCliente/<id>`	`pagarFacturaProveedor/<id>`
`crearFacturaRectificativaCliente`	`crearFacturaRectificativaProveedor`
`exportarFacturaCliente/<id>`	`exportarFacturaProveedor/<id>`
`/api/3/facturaclientes`	`/api/3/facturaproveedores`

El campo de cliente (codcliente) se reemplaza por codproveedor.

Próximos pasos

05 — Otros documentos: albaranes, pedidos, presupuestos
06 — Archivos adjuntos: subir PDFs/imágenes y vincularlos a facturas
07 — Errores y validaciones: qué pasa cuando algo va mal

04 — Facturas

Crear una factura de cliente

Petición

Campos del body

Estructura de cada línea

Ejemplo con cURL

Ejemplo con JavaScript

Respuesta de éxito (HTTP 200)

Marcar una factura como pagada

Body

Ejemplo

Crear factura rectificativa

Body

Ejemplo: devolver 2 unidades de la línea 1782

Comprobar si una factura ya fue rectificada

Exportar el PDF de una factura

Parámetros opcionales (query string)

Ejemplo

Listar y filtrar facturas

Ejemplos útiles

Facturas de proveedor

Próximos pasos

¿Te ha resultado útil esta página?

¿Aún tienes dudas?