rustedf.cloud
Menu

Como gerar fatura em PDF com uma API

Publicado em 2 min de leitura

Uma fatura é um conjunto de dados (um número, um cliente, algumas linhas, um total) que precisa sair do seu sistema como documento. Este guia monta uma como template HTML e a gera em PDF com a API do rustedf.cloud, formatada para o país de quem vai ler.

Ele trata de faturas e recibos comerciais. Documentos fiscais eletrônicos, como a NF-e, seguem regras próprias e não são o assunto aqui, assim como os requisitos legais e tributários de cada país.

O template

Um template é HTML e CSS com {{ }} para valores e {% %} para lógica. Salve-o no portal, onde você tem pré-visualização ao vivo, ou envie-o direto na requisição.

<style>
@page {
size: A4;
margin: 20mm;
@bottom-right { content: "Página " counter(page) " de " counter(pages); }
}
body { font-family: sans-serif; }
table { width: 100%; border-collapse: collapse; }
th, td { padding: 6px 4px; border-bottom: 1px solid #ccc; text-align: left; }
.n { text-align: right; }
</style>
<h1>Fatura {{ number }}</h1>
<p>{{ customer.name }}<br>Emitida em {{ issued | date(style="long") }}</p>
<table>
<thead>
<tr><th>Descrição</th><th class="n">Qtd.</th><th class="n">Valor</th></tr>
</thead>
<tbody>
{% for item in items %}
<tr>
<td>{{ item.name }}</td>
<td class="n">{{ item.qty | number }}</td>
<td class="n">{{ item.amount | currency(code="BRL") }}</td>
</tr>
{% endfor %}
</tbody>
</table>
<h2>Total {{ total | currency(code="BRL") }}</h2>

O loop {% for %} repete uma linha para cada item, então a tabela cresce com os seus dados e segue na página seguinte quando precisa. A regra @page define o papel e um contador de páginas no canto.

Os dados

Envie os valores como texto. Uma string como "1234.50" evita as surpresas dos números de ponto flutuante, e o filtro currency a arredonda para os dígitos da moeda.

{
"number": "2025-0042",
"issued": "2025-03-14",
"customer": { "name": "Mercado Bela Vista Ltda." },
"items": [
{ "name": "Identidade visual", "qty": 1, "amount": "4800.00" },
{ "name": "Design de embalagens", "qty": 6, "amount": "3900.00" }
],
"total": "8700.00"
}

Calcule as linhas e o total no seu sistema e envie os resultados. O template os formata; ele não precisa ser o lugar onde o seu dinheiro é calculado.

Um template, todos os mercados

Acrescente um locale à requisição e os três filtros de formatação o seguem.

Terminal window
curl -X POST https://api.rustedf.com/v1/render \
-H "Authorization: Bearer $RUSTEDF_KEY" \
-H "Content-Type: application/json" \
-d '{
"template_id": "0194f2c0-…",
"locale": "pt-BR",
"data": { "number": "2025-0042", "issued": "2025-03-14", "total": "8700.00" }
}' \
-o fatura.pdf

Veja como o mesmo valor e a mesma data aparecem para quatro leitores:

Idioma Moeda 1234.5 date(style="long") para 2024-03-15
en-US USD $1,234.50 March 15, 2024
pt-BR BRL R$ 1.234,50 15 de março de 2024
de-DE EUR 1.234,50 € 15. März 2024
es-ES EUR 1234,50 € 15 de marzo de 2024

O locale vem primeiro da requisição, depois do template salvo e, por fim, do idioma padrão da sua conta. Uma tag inválida é um 400.

Logotipo e código de pagamento

Envie um PNG ou JPEG uma vez, no portal ou com POST /v1/assets, e use-o por referência. Um QR code para um link de pagamento está a um filtro de distância:

<img src="asset:0194f2c0-…" width="120" alt="Logotipo da empresa">
{{ pay_url | qr(size=30) | safe }}

O safe está ali porque o QR code é um markup que o próprio serviço desenha. Os seus dados continuam escapados.

Confira antes de o cliente ver

POST /v1/validate monta o documento e lista tudo o que o serviço não suportou por completo, sem devolver o PDF e sem usar crédito. Rode-o no seu template uma vez e acrescente "strict": true aos seus testes, para que uma mudança que introduza uma propriedade não suportada falhe ali e não em produção.

Continue com Templates, Idiomas e formatação e Imagens.

← Todos os posts