rustedf.cloud
Menú

Cómo generar un PDF desde HTML en C# y ASP.NET Core

Publicado el 3 min de lectura

En .NET, convertir HTML en PDF suele significar añadir una biblioteca de renderizado y las piezas nativas de las que depende a cada entorno en el que despliegas. Con una API es una petición HTTP, y HttpClient ya la hace. Esta guía muestra un cliente tipado pequeño y un endpoint de ASP.NET Core que devuelve el archivo, con la API de rustedf.cloud.

Un cliente tipado

using System.Net.Http.Json;
public sealed class PdfClient(HttpClient http)
{
public async Task<byte[]> RenderAsync(
string templateId,
Dictionary<string, object?> data,
string locale = "es-ES",
CancellationToken cancellationToken = default)
{
using var response = await http.PostAsJsonAsync(
"v1/render",
new { template_id = templateId, locale, data },
cancellationToken);
if (!response.IsSuccessStatusCode)
{
var body = await response.Content.ReadFromJsonAsync<ErrorBody>(cancellationToken);
throw new InvalidOperationException(
body?.Error?.Message ?? $"Error al generar ({(int)response.StatusCode})");
}
return await response.Content.ReadAsByteArrayAsync(cancellationToken);
}
}
public sealed record ErrorBody(ErrorDetail? Error);
public sealed record ErrorDetail(string? Code, string? Message);

Una respuesta correcta es el propio PDF, así que los bytes son el archivo. En un fallo, el cuerpo es un JSON con un code estable y un message.

Construye data como un diccionario. System.Text.Json renombra las propiedades de una clase o de un objeto anónimo (NombreCliente pasa a nombreCliente), y las claves de tu plantilla deben coincidir exactamente. Las claves de un diccionario se quedan como las escribes.

Regístralo y sirve un PDF

Program.cs
using System.Net.Http.Headers;
builder.Services.AddHttpClient<PdfClient>(client =>
{
client.BaseAddress = new Uri("https://api.rustedf.com/");
client.DefaultRequestHeaders.Authorization =
new AuthenticationHeaderValue("Bearer", builder.Configuration["Rustedf:Key"]);
client.Timeout = TimeSpan.FromSeconds(40);
});
app.MapGet("/facturas/{numero}.pdf", async (string numero, PdfClient pdf) =>
{
var data = new Dictionary<string, object?>
{
["number"] = numero,
["customer"] = new Dictionary<string, object?> { ["name"] = "Ana Souza" },
["total"] = "2040.50",
};
var archivo = await pdf.RenderAsync(builder.Configuration["Rustedf:InvoiceTemplate"]!, data, "es-ES");
return Results.File(archivo, "application/pdf");
});

Guarda la clave en la configuración, en un almacén de secretos o en una variable de entorno (Rustedf__Key), nunca en una vista ni en el navegador. Fija el tiempo límite por encima del límite de tu plan, para que tu petición no se rinda antes que el servicio.

Para enviar HTML en lugar del id de una plantilla guardada, usa una propiedad html en lugar de template_id. Pasa todo lo que haya escrito un usuario por data, y no dentro de la cadena de HTML: los valores de data se escapan, y el propio HTML se lee como una plantilla.

Reintentar cuando el servicio está ocupado

Un 429 (límite de peticiones) o un 503 (ocupado) trae una cabecera Retry-After. Una generación que falla no gasta crédito, así que reintentar es seguro.

if (response.StatusCode is HttpStatusCode.TooManyRequests or HttpStatusCode.ServiceUnavailable)
{
var espera = response.Headers.RetryAfter?.Delta ?? TimeSpan.FromSeconds(2);
await Task.Delay(espera, cancellationToken);
// envía la petición de nuevo, un número limitado de veces
}

Errores que conviene tratar

Estado code Qué hacer
401 unauthorized La clave falta, es incorrecta o está revocada.
402 insufficient_credits Se acabaron los créditos. No se generó nada.
422 invalid_template La plantilla o los datos fallaron. Lee el message.
429 rate_limited Espera el Retry-After y reintenta.
503 busy El servicio está ocupado. Espera el Retry-After y reintenta.
504 render_timeout El documento tardó más de lo que permite tu plan.

Ejecuta POST /v1/validate con el mismo cuerpo mientras construyes la plantilla: enumera todo lo que el servicio no admitió por completo, sin devolver el PDF ni gastar crédito.

Consulta Generar un PDF, Autenticación y Errores y límites.

Más guías de C#

← Todos los artículos