La API española para facturar con VeriFactu desde tu software.

Necesito conectar mi software con la API REST de Beply.

📚 Documentación oficial: https://beply.es/desarrolladores/
🔍 Listado de recursos: GET https://example.beply.es/api/3

CONVENCIONES OBLIGATORIAS:
- URL base: https://example.beply.es/api/3/
- Autenticación: cabecera "Token: tu-api-key" — guárdala en una variable
  de entorno del backend (process.env.BEPLY_API_KEY o equivalente). NO la
  pegues en código fuente ni en repositorios públicos.
- POST/PUT en application/x-www-form-urlencoded por defecto. Excepciones:
    · uploadFiles → multipart/form-data
    · sendEmail   → application/json
- La respuesta es siempre application/json (salvo exportar... que devuelve binario PDF/XLSX/CSV)
- Nombres de campos en español: codcliente, nombre, pvpunitario, dtopor, codimpuesto...
- Fechas: envío en YYYY-MM-DD, respuesta en DD-MM-YYYY

TIPOS DE ENDPOINTS:
1) Recursos REST (minúsculas, CRUD genérico):
   GET    /api/3/<recurso>            → listar (soporta filter[col]=val, sort, limit, offset)
   GET    /api/3/<recurso>/<id>       → obtener uno
   POST   /api/3/<recurso>            → crear (form-urlencoded)
   PUT    /api/3/<recurso>/<id>       → actualizar parcial
   DELETE /api/3/<recurso>/<id>       → eliminar
   GET    /api/3/<recurso>/schema     → ver campos disponibles

   Ejemplos de recursos: clientes, productos, proveedores, facturaclientes,
   albaranclientes, pedidoclientes, presupuestoclientes, pagoclientes, asientos,
   almacenes, stocks, agentes, impuestos.

2) Funciones (camelCase, flujos completos en una llamada):
   POST /api/3/crearFacturaCliente               → factura con líneas + VeriFactu auto
   POST /api/3/pagarFacturaCliente/<idfactura>   → marcar pagada
   POST /api/3/crearFacturaRectificativaCliente  → rectificativa
   GET  /api/3/exportarFacturaCliente/<id>?type=PDF → PDF binario
   POST /api/3/uploadFiles                       → subir archivo (multipart/form-data)
   POST /api/3/sendEmail                         → enviar email (JSON; adjunta PDFs de documentos)
   POST /api/3/attachedfilerelations             → vincular archivo a registro

FORMATO DE RESPUESTA:
- POST genérico: { "ok": "Registro actualizado correctamente.", "data": { ... } }
- crearFacturaCliente y similares: { "doc": { ... }, "lines": [ ... ] }
- sendEmail: { "status": "success", "message": "email-sent-successfully", "data": { "uuid": "...", "recipients": ["cliente@example.com"], "attachments": ["FAC2026A1.pdf"], "sent_at": "YYYY-MM-DD HH:MM:SS" } }
- Errores:
   401 → { "status": "error", "message": "Clave de API no válida" }
   404 → { "error": "Registro no encontrado" }
   400 (validación) → { "error": "<mensaje>", "data": { ... } }
   sendEmail sin SMTP → { "status": "error", "code": "SEND_ERROR" | "EMAIL_NOT_CONFIGURED", "message": "email-send-failed" | "email-not-configured-in-facturascripts" }

SEND EMAIL:
- Endpoint: POST /api/3/sendEmail con Content-Type: application/json
- Campos requeridos: to, subject, body
- Adjuntar factura PDF:
  { "attachments": [{ "type": "document", "modelClassName": "FacturaCliente", "modelCode": "<idfactura>" }] }
- Adjuntos soportados: document, base64, attachedFile.
- Requiere SMTP configurado en la instancia; si recibes SEND_ERROR o EMAIL_NOT_CONFIGURED, pide configurar el correo antes de reintentar.

VeriFactu/TicketBAI/SII se aplican automáticamente al crear facturas según el
domicilio fiscal de la cuenta. Hash, encadenado, QR y envío a la AEAT son
transparentes para el integrador.