TEMPLATING

Geração de fatura em PDF

Manda emissor, destinatário e itens em JSON, recebe um PDF de fatura pronto — com totais sempre calculados no servidor, nunca aceitos do cliente.

PDF invoice generation

Send issuer, recipient and line items as JSON, get a ready invoice PDF back — with totals always computed server-side, never trusted from the client.

SYNC resposta na mesma chamada answers in the same call

Endpoints

POST /api/v1/templating/invoice gera uma fatura em PDF (bytes crus, não o envelope JSON) generates an invoice PDF (raw bytes, not the JSON envelope)

Um único template embutido: fatura. Corte de escopo explícito — isto não é um motor de templates genérico nem faz conversão entre formatos, é exatamente um tipo de documento.

One built-in template: invoice. Explicit scope cut — this isn't a generic templating engine or format converter, it's exactly one document type.

Parâmetros

Parameters

Nome	Name	Onde	In
`invoice_number`, `currency`	body	número livre da fatura; moeda opcional, padrão `BRL` (formatação brasileira — `R$ 1.234,56`). Qualquer outra moeda sai como `{CÓDIGO} 1234.56`, sem localização própria	free-form invoice number; optional currency, defaults to `BRL` (Brazilian formatting — `R$ 1.234,56`). Any other currency prints as `{CODE} 1234.56`, with no native localization
`issuer`, `recipient`	body	`name` obrigatório em ambos; `document`, `address`, `email` opcionais	`name` required on both; `document`, `address`, `email` optional
`items[]`	body	pelo menos 1 item, cada um com `description`, `quantity` > 0 e `unit_price` ≥ 0. Limite de itens por fatura tunável (padrão 100)	at least 1 item, each with `description`, `quantity` > 0 and `unit_price` ≥ 0. Items-per-invoice limit is tunable (default 100)
`notes`	body	opcional, texto livre exibido no rodapé da fatura	optional, free text shown in the invoice's footer

Exemplo

Example

curl -X POST "https://api.alicercelabs.com.br/api/v1/templating/invoice" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -o fatura.pdf \
  -d '{
  "invoice_number": "2026-001",
  "currency": "BRL",
  "issuer": { "name": "AlicerceLabs", "document": "00.000.000/0001-00", "email": "contato@alicercelabs.com.br" },
  "recipient": { "name": "Cliente Exemplo Ltda", "document": "11.111.111/0001-11" },
  "items": [
    { "description": "Consultoria", "quantity": 2, "unit_price": 500 },
    { "description": "Setup inicial", "quantity": 1, "unit_price": 150.50 }
  ],
  "notes": "Pagamento via PIX em até 10 dias."
}'

Resposta: 200, Content-Type: application/pdf, o PDF cru no corpo — totais calculados no servidor (2×500 + 150,50 = R$ 1.150,50).

Response: 200, Content-Type: application/pdf, the raw PDF in the body — totals computed server-side (2×500 + 150.50 = R$ 1.150,50).

Erros possíveis

Possible errors

Status	Motivo	Reason
400	`issuer.name`/`recipient.name` ausente, `items` vazio ou acima do limite, item inválido (sem descrição, quantidade ≤ 0, preço negativo)	missing `issuer.name`/`recipient.name`, empty or over-limit `items`, invalid item (no description, quantity ≤ 0, negative price)
401	token ausente ou inválido	missing or invalid token
429	limite de taxa excedido	rate limit exceeded

Limites

Limits

10.000/dia · 416/hora. Itens por fatura: 100 por padrão, tunável por cliente via admin. Sem cache, sem banco — cada fatura é gerada na hora a partir do dado enviado, não há nada aqui que valha a pena memoizar.

10,000/day · 416/hour. Items per invoice: 100 by default, tunable per client via admin. No cache, no database — each invoice is generated on the fly from the submitted data, there's nothing here worth memoizing.