Formatos de dados

Aqui você encontra o formato em que seus dados devem chegar. O PDFgine não imprime o valor enviado como está; aplica o formatador declarado pelo modelo, no idioma do documento.

Em uma frase: os dados chegam brutos e o PDFgine os formata. Envie um valor pré-formatado e o documento será lido corretamente em um idioma e incorretamente no outro.

Um formatador é declarado em três lugares: no campo "format" de uma coluna de tabela e de uma linha de resumo, em "dataRules.formatter" de um elemento que imprime um único valor e nas funções format_date e format_money em textos que combinam vários campos.

{
  "issueDate": "2026-09-06",
  "currency": "USD",
  "lineItems": [
    { "name": "Site corporativo", "quantity": 1, "unitPrice": 24000, "total": 24000 }
  ]
}

// No modelo:
// coluna da tabela:   "format": { "kind": "currency", "currency": "USD", "decimals": 2 }
// coluna de data:    "format": { "kind": "date", "dateStyle": "short" }
// elemento de texto:   "{{ referenceNo }} · {{ format_date issueDate }}"

IBAN, telefone e números fiscais também chegam em formato canônico: IBAN sem espaços, telefone em E.164 (+442071838750). O agrupamento é um formato de apresentação e não faz parte dos dados.

O nome com que o documento é recebido

Um documento baixado recebe o nome "{document type} - {counterparty} - {reference no}". As três partes vêm dos dados enviados: document.title, customer e referenceNo. O que estiver ausente é omitido e, se nenhuma parte gerar um nome utilizável, o documento usa sua identidade, por exemplo quote-doc_94812af2.pdf.

Content-Disposition: attachment;
  filename="Quote - Müller og Søn ApS - QUO-2026-0042.pdf";
  filename*=UTF-8''Quote%20-%20M%C3%BCller%20og%20S%C3%B8n%20ApS%20-%20QUO-2026-0042.pdf

O nome é escrito duas vezes no mesmo cabeçalho. O campo estendido preserva o idioma do documento; o clássico contém uma escrita ASCII legível para clientes que não leem o estendido. Os caracteres não aceitos por sistemas de arquivos (barra, barra invertida, dois-pontos, asterisco, interrogação, aspas, menor que, maior que, barra vertical) são removidos junto com os caracteres de controle, e o nome tem tamanho limitado para funcionar em todos os sistemas de arquivos.

Imagens

Um elemento de imagem do modelo pode ser vinculado a um campo de dados, recebendo a origem na solicitação. São aceitos o ID de um recurso enviado (ast_…, para logotipos, carimbos e assinaturas recorrentes: envio único, só o ID é transmitido) e uma imagem inline (data:image/png;base64,…, para uso único). Se o campo estiver ausente ou vazio, usa-se a imagem do modelo; se houver um valor inválido, a solicitação é rejeitada com 422 e a resposta indica o campo.

{
  "templateCode": "invoice",
  "format": "pdf",
  "data": {
    "logo": "ast_9f1c7b1f0f6b4f5f9f0a0d1e2c3b4a59",
    "signature": "data:image/png;base64,iVBORw0KGgo..."
  }
}

Limites: uma imagem inline deve ser PNG, JPEG ou WebP, com no máximo 2 MB por imagem e 6 MB para todas as imagens do documento. Um recurso enviado pode ter até 10 MB. Para imagens temporárias, informe expiresInMinutes no envio (1 minuto–7 dias); recursos expirados são excluídos automaticamente.

Recursos

Logotipos, assinaturas e fontes são enviados uma vez e referenciados por ID. A página própria explica o envio, os limites e as permissões das fontes.

Os problemas mais comuns

• Um valor pré-formatado é impresso como chega. "1.234,56" é lido corretamente em um idioma e incorretamente em outro, e nenhum formatador consegue corrigir depois.
• Uma data deve estar em ISO 8601. Um formato local chega como texto: não é formatado, ordenado nem traduzido.
• A moeda não faz parte do valor. Envie o número e deixe o formatador da coluna adicionar o código ISO.
• Uma proporção é enviada sobre cem: 18 para 18%. Enviar 0.18 imprime zero vírgula dezoito por cento.
• Uma condição lê um booleano JSON. A string "false" é um texto não vazio e conta como presente.