rustedf.cloud
Menu

Como gerar PDF a partir de HTML em C# e ASP.NET Core

Publicado em 3 min de leitura

No .NET, transformar HTML em PDF costuma significar adicionar uma biblioteca de renderização e as peças nativas de que ela depende a cada ambiente em que você publica. Com uma API, é uma requisição HTTP, e o HttpClient já faz isso. Este guia mostra um cliente tipado pequeno e um endpoint do ASP.NET Core que devolve o arquivo, com a API do rustedf.cloud.

Um 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 = "pt-BR",
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 ?? $"Falha ao gerar ({(int)response.StatusCode})");
}
return await response.Content.ReadAsByteArrayAsync(cancellationToken);
}
}
public sealed record ErrorBody(ErrorDetail? Error);
public sealed record ErrorDetail(string? Code, string? Message);

Uma resposta bem-sucedida é o próprio PDF, então os bytes são o arquivo. Em uma falha, o corpo é um JSON com um code estável e uma message.

Monte o data como um dicionário. O System.Text.Json renomeia as propriedades de uma classe ou de um objeto anônimo (NomeDoCliente vira nomeDoCliente), e as chaves do seu template precisam bater exatamente. As chaves de um dicionário ficam como você escreveu.

Registre e sirva um 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("/faturas/{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 arquivo = await pdf.RenderAsync(builder.Configuration["Rustedf:InvoiceTemplate"]!, data, "pt-BR");
return Results.File(arquivo, "application/pdf");
});

Guarde a chave na configuração, em um cofre de segredos ou em uma variável de ambiente (Rustedf__Key), nunca em uma view nem no navegador. Defina o tempo limite acima do limite do seu plano, para que a sua requisição não desista antes do serviço.

Para enviar HTML em vez do id de um template salvo, use uma propriedade html no lugar de template_id. Passe tudo o que um usuário digitou por data, e não dentro da string de HTML: os valores em data são escapados, e o próprio HTML é lido como um template.

Tentar de novo quando o serviço está ocupado

Um 429 (limite de requisições) ou um 503 (ocupado) traz um cabeçalho Retry-After. Uma geração que falha não custa crédito, então tentar de novo é seguro.

if (response.StatusCode is HttpStatusCode.TooManyRequests or HttpStatusCode.ServiceUnavailable)
{
var espera = response.Headers.RetryAfter?.Delta ?? TimeSpan.FromSeconds(2);
await Task.Delay(espera, cancellationToken);
// envie a requisição de novo, um número limitado de vezes
}

Erros que vale tratar

Status code O que fazer
401 unauthorized A chave está ausente, errada ou revogada.
402 insufficient_credits Os créditos acabaram. Nada foi gerado.
422 invalid_template O template ou os dados falharam. Leia a message.
429 rate_limited Espere o Retry-After e tente de novo.
503 busy O serviço está ocupado. Espere o Retry-After e tente de novo.
504 render_timeout O documento levou mais do que o seu plano permite.

Rode POST /v1/validate com o mesmo corpo enquanto monta o template: ele lista tudo o que o serviço não suportou por completo, sem devolver o PDF nem usar crédito.

Leia Gerar um PDF, Autenticação e Erros e limites.

Mais guias de C#

  • Código e integrações

    Gerar PDF no ASP.NET Core: MVC, Razor Pages e minimal APIs

    Transforme uma view Razor em PDF no ASP.NET Core com uma chamada de API: renderizador de views, view pronta para impressão, action MVC e handler do Razor Pages.

    3 min de leitura

  • Código e integrações

    Converter página web em PDF em C# sem navegador headless

    Busque uma página com HttpClient e transforme o HTML em PDF com uma chamada de API em C#. Quais páginas isso atende, quais não e como conferir antes de depender.

    3 min de leitura

  • Código e integrações

    Gerador de relatório PDF em C#: tabela paginada com totais

    Monte um relatório em PDF em C# a partir de uma lista de objetos: tabela com cabeçalho repetido em cada página, total, número de página e contagem de páginas.

    3 min de leitura

← Todos os posts