Crear facturas en línea con la API de GroupDocs.Assembly Cloud

Visión general

Generar facturas al instante es una necesidad habitual para sistemas de facturación, plataformas de comercio electrónico y aplicaciones SaaS.
Con GroupDocs.Assembly Cloud puede crear facturas profesionales totalmente en la nube, sin instalar software de oficina en sus servidores.

Ventajas clave

Flexibilidad de la plantilla – Diseñe los formatos de factura en un editor nativo como Microsoft Word, LibreOffice Writer, etc.
Vinculación dinámica de datos – Rellene plantillas con datos JSON o XML, usando marcadores simples o expresiones LINQ avanzadas para cálculos, bucles y secciones condicionales.
Varios formatos de salida – Genere la factura final como DOCX (para seguir editándola) o como PDF (para distribución de solo lectura).
Almacenamiento seguro – Acceda a plantillas y documentos almacenados en GroupDocs Cloud mediante tokens de autenticación.
Entorno ligero – Todo el procesamiento se ejecuta en GroupDocs Cloud, liberando su infraestructura de bibliotecas de terceros o de requisitos elevados de CPU y memoria.

En las siguientes secciones recorrremos todo el proceso: desde la preparación de la plantilla y la fuente de datos hasta la generación de la factura con el SDK .NET usando C# y con simples comandos cURL.

Preparar la plantilla de la factura

Diseñe el formato de la factura con su editor de escritorio favorito (Microsoft Word, LibreOffice Writer, etc.).
Inserte etiquetas de marcador de posición que coincidan con los campos JSON que proporcionará más adelante, por ejemplo:

Plantilla	Ruta JSON
`<<[Invoice.Number]>>`	`invoice.number`
`<<[Customer.Name]>>`	`customer.name`

La definición de la plantilla para renderizar una tabla tendría este aspecto:

Descripción	Cantidad	Precio unitario	Coste
`<<foreach [in Items]>>` `<<[Description]>>`	`<<[Quantity]>>`	`$<<[UnitPrice]:"N2">>`	`$<<[Quantity*UnitPrice]:"N2">>` `<</foreach>>`

Para su comodidad, descargue un ejemplo de plantilla que se muestra a continuación:

O bien cree su propia plantilla y súbala al almacenamiento de GroupDocs Cloud (sección siguiente).

Subir la plantilla al almacenamiento en la nube

Pasos principales para el código C#

Crear un objeto Configuration con su App SID y App Key.
Inicializar el cliente AssemblyApi.
Subir el archivo de plantilla local a una ruta en el almacenamiento en la nube (p. ej., templates/invoice-template.docx).

// 1️⃣ Initialize the Cloud API configuration
var config = new Configuration
{
    AppSid = "YOUR_APP_SID",      // replace with your App SID
    AppKey = "YOUR_APP_KEY"       // replace with your App Key
};
var assemblyApi = new AssemblyApi(config);

// 2️⃣ Define the cloud path where the template will be stored
string cloudTemplatePath = "templates/invoice-template.docx";

// 3️⃣ Open the local template file (prepare this file beforehand)
using (var templateStream = File.OpenRead("resources/invoice-template.docx"))
{
    // 4️⃣ Build the upload request – the API expects a stream + target path
    var uploadRequest = new UploadFileRequest(templateStream, cloudTemplatePath);

    // 5️⃣ Execute the upload; the template is now available in Cloud storage
    assemblyApi.UploadFile(uploadRequest);
}

Consejo: también puede subir el archivo mediante un sencillo comando cURL (ver la sección Generar factura con cURL) si prefiere un enfoque de línea de comandos.

Crear la fuente de datos

Construir un JSON con los datos de la factura

A continuación se muestra el JSON de ejemplo que coincide con los marcadores de posición usados en la plantilla.
Guárdelo como invoice-data.json en la carpeta resources o inclúyalo directamente en su código.

{
  "invoice": {
    "number": "INV-2024-001",
    "issueDate": "2024-01-15T00:00:00"
  },
  "customer": {
    "name": "John Smith",
    "company": "Acme Corporation",
    "email": "john.smith@example.com",
    "address": "123 Main Street",
    "city": "New York",
    "state": "NY",
    "zipCode": "10001",
    "country": "USA"
  },
  "items": [
    {
      "description": "Web Development Services",
      "quantity": 40,
      "unitPrice": 150.00
    },
    {
      "description": "UI/UX Design",
      "quantity": 20,
      "unitPrice": 120.00
    },
    {
      "description": "Consulting Services",
      "quantity": 10,
      "unitPrice": 200.00
    }
  ],
  "taxRate": 10.0
}

Uso del archivo JSON en el código

// Load the JSON data from a file – this string will be passed to the API
string jsonData = File.ReadAllText("resources/invoice-data.json");

Nota: el mismo JSON puede enviarse en línea dentro del cuerpo de la solicitud cuando se usa cURL; el enfoque por archivo resulta más cómodo para conjuntos de datos extensos.

Generar la factura con el SDK .NET

Pasos principales para el código C#

Subir la plantilla (ya cubierto).
Leer la fuente de datos JSON.
Configurar AssembleOptions – indique el formato de salida (docx o pdf) y enlace la plantilla.
Llamar a AssembleDocument para generar la factura.
Guardar el archivo resultante localmente o en otra ubicación en la nube.

using GroupDocs.Assembly.Cloud.Sdk;
using GroupDocs.Assembly.Cloud.Sdk.Model;
using GroupDocs.Assembly.Cloud.Sdk.Model.Requests;
using System.IO;

// 1️⃣ Initialize the Assembly API (same config as upload step)
var config = new Configuration { AppSid = "YOUR_APP_SID", AppKey = "YOUR_APP_KEY" };
var assemblyApi = new AssemblyApi(config);

// 2️⃣ Load JSON data (see previous section)
string jsonData = File.ReadAllText("resources/invoice-data.json");

// 3️⃣ Prepare assembly options
var assembleOptions = new AssembleOptions
{
    // Choose the format you need – "docx" for editable, "pdf" for final PDF
    SaveFormat = "pdf",

    // Pass the whole JSON string – the API parses it automatically
    ReportData = jsonData,

    // Reference the template that we uploaded earlier
    TemplateFileInfo = new TemplateFileInfo
    {
        FilePath = "templates/invoice-template.docx"   // cloud path
    }
};

// 4️⃣ Build the request object
var assembleRequest = new AssembleDocumentRequest(assembleOptions);

// 5️⃣ Execute the request – the response contains the generated file stream
var assembledDocument = assemblyApi.AssembleDocument(assembleRequest);

// 6️⃣ Persist the result locally
using (var outputStream = File.Create("output/invoice-output.pdf"))
{
    // Copy the API stream to a file on disk
    assembledDocument.CopyTo(outputStream);
}

Resultado: invoice-output.pdf (o .docx si cambió SaveFormat) contiene la factura completamente poblada, lista para enviarse al cliente.

Generar la factura con cURL

Si prefiere no instalar ningún SDK y resolver todo mediante llamadas HTTP, el proceso completo puede realizarse con simples peticiones cURL.

1️⃣ Obtener un token de acceso

curl.exe -X POST "https://api.groupdocs.cloud/connect/token" \
  -d "grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET" \
  -H "Content-Type: application/x-www-form-urlencoded"

La respuesta contiene access_token; copie su valor para los siguientes pasos.

2️⃣ Subir la plantilla mediante cURL

curl.exe -X PUT "https://api.groupdocs.cloud/v1.0/assembly/storage/file/templates/invoice-template.docx" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -F "File=@resources/invoice-template.docx"

Si la plantilla ya está almacenada (como se describió en el paso de SDK), puede omitir esta llamada.

3️⃣ Ensamblar la factura

Cree un archivo JSON llamado invoice-data.json en la carpeta resources tal como se muestra en la sección [Crear la fuente de datos {#json-data}].

Luego invoque el endpoint AssembleDocument.

Cuando se trabaja con grandes volúmenes de datos de factura, el enfoque más eficiente es leer los datos en una variable intermedia y pasarlos a la solicitud API. El siguiente ejemplo muestra este método:

REPORT_DATA_ESCAPED=$(python -c "import json,sys; print(json.dumps(open('resources/invoice-data.json','r',encoding='utf-8').read()))")
	  
curl.exe -v "https://api.groupdocs.cloud/v1.0/assembly/assemble" \
  -X POST \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  --data-binary @- <<EOF
{
  "TemplateFileInfo": {
    "FilePath": "/templates/invoice-template.docx"
  },
  "SaveFormat": "pdf",
  "OutputPath": "/output/invoice-generated.pdf",
  "ReportData": $REPORT_DATA_ESCAPED
}
EOF

El comando crea la factura y la almacena en el almacenamiento de GroupDocs Cloud en el archivo /output/invoice-generated.pdf.

4️⃣ Descargar la factura generada

Para descargarla, ejecute el siguiente comando:

curl.exe \
  "https://api.groupdocs.cloud/v1.0/assembly/storage/file/Output/invoice-generated.pdf" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Accept: application/octet-stream" \
  -o invoice-generated.pdf

Resultado: ahora dispone de una factura lista para enviar sin escribir código C#.

Conclusión

En este artículo hemos demostrado cómo GroupDocs.Assembly Cloud simplifica la generación de facturas:

Procesamiento ligero en la nube – sin herramientas pesadas de terceros en sus servidores.
Libertad en el diseño de la plantilla – cree documentos plantilla en Word/LibreOffice y guárdelos en el almacenamiento en la nube.
Vinculación dinámica de datos – alimente JSON (o XML) directamente, con soporte para LINQ, cálculos, bucles y condicionales.
Distintos formatos de salida – elija DOCX para seguir editando o PDF para distribución inmutable.
Integración sencilla – use el SDK .NET o varios comandos cURL, ilustrados con ejemplos completos.

¡Comience a automatizar sus flujos de facturación hoy mismo subiendo una plantilla y llamando al endpoint de ensamblado!

Ver también

GroupDocs.Assembly Cloud API Reference – https://reference.groupdocs.cloud/assembly/
GroupDocs.Assembly Cloud Documentation – https://docs.groupdocs.cloud/assembly/
Guía de inicio rápido para crear plantillas de documentos – https://docs.groupdocs.cloud/assembly/getting-started/quick-start/
Trabajo con elementos avanzados (códigos de barras, marcadores, hipervínculos y más) – https://docs.groupdocs.cloud/assembly/developer-guide/working-with-other-elements/
Guía completa de sintaxis avanzada de definición de plantillas – https://docs.groupdocs.com/assembly/net/advanced-usage/

Preguntas frecuentes (FAQs)

¿Puedo usar LibreOffice Writer en lugar de Microsoft Word para mi plantilla?
Sí. La API funciona con cualquier archivo DOCX, sin importar el editor utilizado para crearlo.
¿Es posible realizar cálculos (p. ej., totales, impuestos) dentro de la plantilla?
Absolutamente. Puede usar expresiones LINQ o aritméticas simples en los marcadores, por ejemplo <<[item.quantity * item.unitPrice]>>.
¿Cuál es el tamaño máximo de una plantilla o archivo de datos que puedo subir?
El servicio admite archivos de hasta 500 MB; las plantillas de facturas habituales están muy por debajo de este límite.
¿Necesito crear previamente la carpeta de destino en el almacenamiento en la nube antes de subir?
No. El endpoint de carga crea la jerarquía de carpetas automáticamente si no existe.
¿Obtengo una prueba gratuita?
Sí, están disponibles 150 llamadas API gratuitas al mes.

Visión general#

Preparar la plantilla de la factura#

Subir la plantilla al almacenamiento en la nube#

Crear la fuente de datos#

Generar la factura con el SDK .NET#

Generar la factura con cURL#

Conclusión#

Ver también#

Preguntas frecuentes (FAQs)#