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

Usando o SDK

Using the SDK

Totais (quantity × unit_price por item) são sempre calculados no servidor. Nunca confie num total calculado no cliente.

Totals (quantity × unit_price per item) are always computed server-side. Never trust a client-computed total.

SDKs oficiais: Go · Python · JavaScript.

Official SDKs: Go · Python · JavaScript.

Gerar uma fatura em PDF

Generate an invoice PDF

import (
	"context"
	"fmt"

	alicercelabs "github.com/alicercelabs/alicercesdk-go"
)

client := alicercelabs.New("alk_...")
ctx := context.Background()

fatura, err := client.Templating.Invoice(ctx, alicercelabs.InvoiceRequest{
	Issuer:    alicercelabs.InvoiceParty{Name: "Minha Empresa", Document: "00.000.000/0001-00"},
	Recipient: alicercelabs.InvoiceParty{Name: "Cliente Exemplo"},
	Items: []alicercelabs.InvoiceItem{
		{Description: "Consultoria", Quantity: 2, UnitPrice: 500},
	},
})
if err != nil {
	panic(err)
}
fatura.Save("fatura.pdf")

from alicercelabs import AlicerceLabs

client = AlicerceLabs(api_key="alk_...")

fatura = client.templating.invoice(
    issuer={"name": "Minha Empresa", "document": "00.000.000/0001-00"},
    recipient={"name": "Cliente Exemplo"},
    items=[{"description": "Consultoria", "quantity": 2, "unit_price": 500}],
)
fatura.save("fatura.pdf")

import { AlicerceLabs } from "alicercesdk-javascript";

const client = new AlicerceLabs("alk_...");

const fatura = await client.templating.invoice({
  issuer: { name: "Minha Empresa", document: "00.000.000/0001-00" },
  recipient: { name: "Cliente Exemplo" },
  items: [{ description: "Consultoria", quantity: 2, unit_price: 500 }],
});
await fatura.save("fatura.pdf");

Limites

Limits

100/dia · 4/hora sem token; com uma API key (gerada no painel), 1.000/dia · 41/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.

100/day · 4/hour without a token; with an API key (generated in the panel), 1,000/day · 41/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.