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
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#
- Generar un PDF en ASP.NET Core: MVC, Razor Pages y minimal APIs
- Convertir una página web a PDF en C# sin navegador headless
- Generador de informes PDF en C#: tabla paginada con totales
- Guardar un PDF en C#: en disco, como descarga o en blob storage
- HTML a PDF en C#: PdfSharp, QuestPDF, iText, Puppeteer o una API
- Generar un PDF en Blazor: Server y WebAssembly
- Generar un PDF en Azure Functions sin empaquetar un navegador
- Generar miles de PDF en C#: ritmo, 429 y reintentos seguros
Sigue leyendo
Código e integraciones
Generar un PDF en ASP.NET Core: MVC, Razor Pages y minimal APIs
Convierte una vista Razor en PDF en ASP.NET Core con una llamada a la API: renderizador de vistas, vista lista para imprimir, acción MVC y handler de Razor Pages.
3 min de lectura
Código e integraciones
Convertir una página web a PDF en C# sin navegador headless
Descarga una página con HttpClient y convierte su HTML en PDF con una llamada a la API en C#. Qué páginas admite, cuáles no y cómo comprobarlo de antemano.
3 min de lectura
Código e integraciones
Generador de informes PDF en C#: tabla paginada con totales
Crea un informe PDF en C# a partir de una lista de objetos: tabla con la cabecera repetida en cada página, total, números de página y recuento de páginas.
3 min de lectura
Código e integraciones
Guardar un PDF en C#: en disco, como descarga o en blob storage
Guarda el PDF que devuelve una llamada de renderizado en C#: escríbelo en disco, envíalo como descarga en ASP.NET Core, usa un enlace firmado o súbelo al storage.
2 min de lectura