API de recibo em PDF para pagamentos de ecommerce e SaaS
Gere recibos em PDF a partir de dados de pedido, pagamento, impostos e reembolso, com QR codes, códigos de barras, configurações PDF/A e saída repetível por modelo.
/api/v1/pdf/render Transformar dados de pedido concluído, pagamento, reembolso e impostos em um recibo PDF que pode ser enviado por e-mail, armazenado, impresso ou anexado à conta do cliente sem exigir que cada chamador mantenha código de desenho de PDF.
Quando usar esta API
- Seu sistema já controla status de pagamento, número do recibo, linhas de imposto e dados do cliente.
- Você precisa de um recibo PDF para e-mail, histórico da conta, fluxos de suporte ou exportação de auditoria.
- Você quer QR codes ou códigos de barras dentro do recibo para consulta, reembolso ou retirada.
- Você precisa de um modelo de recibo estável depois que o layout for aprovado.
O que ela não substitui
- Você precisa processar pagamentos ou executar reembolsos. O gPdf renderiza o recibo; seu sistema de pagamentos controla a movimentação de dinheiro.
- Você precisa de empacotamento legal de e-invoice. Use o endpoint E-Invoice Render para saída Factur-X ou ZUGFeRD.
- Você precisa controlar hardware de POS ou lógica de gaveta de dinheiro.
Qual endpoint chamar
/api/v1/pdf/render
JSON Render é o caminho padrão para este fluxo.
/api/v1/template-render
Use quando o fluxo precisar da API relacionada, de um contrato de template ou de uma consulta de capacidades.
Request mínimo
POST /api/v1/pdf/render - recibo compacto com QR code de consulta.
{
"pages": [
{
"size": "a6",
"elements": [
{
"type": "text",
"x": 10,
"y": 12,
"content": "Receipt R-2026-1001",
"style": { "font_size": 16, "font_family": "NotoSans-Regular" }
},
{
"type": "text",
"x": 10,
"y": 28,
"content": "Order total: $82.40\nPaid by card ending 4242\nTax: $6.10",
"style": { "font_size": 10, "font_family": "NotoSans-Regular" }
},
{
"type": "barcode",
"format": "qrcode",
"content": "https://example.com/receipts/R-2026-1001",
"x": 10,
"y": 58,
"width": 28,
"height": 28
}
]
}
]
}
O que a gPdf faz
- Renderização de página de recibo a partir de corpos de requisição JSON Render.
- Texto, totais, linhas de itens, QR codes, códigos de barras, metadados e configurações PDF/A opcionais.
- Vinculação com Template Render quando o mesmo layout de recibo é reutilizado.
- Saída binária em PDF com o envelope compartilhado de erro do gPdf em caso de falha.
O que seu sistema controla
- Autorização de pagamento, captura, reembolso, cálculo de impostos e numeração de recibos.
- Identidade do cliente, estado do pedido, formatação de moeda e política de retenção.
- Entrega por e-mail, armazenamento em conta e tratamento de recibos duplicados.
Checklist de produção
- Use um número de recibo estável e envie um X-Request-Id em toda renderização.
- Decida se os recibos devem ser regenerados a partir dos dados de origem ou armazenados após a primeira renderização.
- Teste nomes longos de itens, reembolsos, descontos, múltiplas linhas de imposto e pedidos de valor zero.
- Migre para Template Render assim que as equipes de suporte e finanças aprovarem o layout.
- Mantenha decisões de pagamento e impostos fora da requisição de renderização.
Limites da promessa
- O gPdf não processa pagamentos, não calcula impostos e não emite reembolsos.
- Um recibo PDF não é automaticamente uma e-invoice legal.
- Seu sistema controla a verdade de negócio; o gPdf renderiza a representação em PDF.
Recibos em PDF são saídas de renderização
Este não é um endpoint separado de pagamento ou POS. Seu backend de ecommerce, cobrança ou POS decide que um recibo existe e então envia o conteúdo do recibo ao gPdf como um DocumentRequest ou como dados para um modelo publicado.
A camada de renderização deve permanecer determinística. Se um agente de suporte solicitar o mesmo recibo novamente, seu sistema pode repetir os dados de origem ou retornar um PDF armazenado anteriormente, de acordo com sua política de retenção.
Caminho por modelo para recibos repetidos
Layouts de recibo costumam se estabilizar rapidamente. Depois que o design é
aprovado, publique um modelo e chame POST /api/v1/template-render com os
campos do recibo. Isso mantém os sistemas de pagamento focados em dados e deixa
a responsabilidade pelo layout em um único lugar.
FAQ
- O gPdf pode calcular o total do recibo?
- Não. Seu sistema de pagamentos ou comércio controla totais, descontos, impostos e estado de reembolso. O gPdf renderiza os valores que você envia.
- Recibos devem usar JSON Render ou Template Render?
- Use JSON Render enquanto desenha o layout. Use Template Render quando o layout do recibo e o contrato de campos estiverem estáveis.
- O recibo pode incluir um QR code?
- Sim. O gPdf oferece suporte a elementos de código de barras QR code na saída em PDF. Seu sistema controla a URL ou o conteúdo codificado no QR code.
- Isso é o mesmo que a API de e-invoice?
- Não. Recibos em PDF comuns usam JSON Render ou Template Render. O empacotamento Factur-X e ZUGFeRD usa o endpoint E-Invoice Render.