Documentos

A loja imprime documentos a partir de modelos: uma fatura que vai com o pedido, o romaneio que a separação usa, a nota de crédito de uma devolução. Cada modelo é um HTML com marcadores como {{order_number}} e {{total}}, que a plataforma troca pelos dados do pedido na hora de gerar. Esta seção é a API para listar, editar e gerar esses modelos.

Como funciona

O fluxo típico:

1. Ver as variáveis

   Liste as variáveis que dá para usar.

2. Criar o modelo

   Crie o HTML com os marcadores, ou duplique um existente e ajuste.

3. Testar

   Pré-visualize com dados de exemplo e depois com um pedido real.

4. Tornar padrão

   Marque is_default para que a plataforma use o modelo nas faturas e romaneios.

Conceitos-chave

Modelo padrão

O padrão de um tipo e idioma é o que a plataforma usa quando gera o documento sozinha, por exemplo o romaneio de uma remessa. Marcar outro modelo como padrão desmarca o anterior. Tirar a marca do último padrão é recusado (409).

Marcadores

O texto {{total}} vira o total do pedido já formatado em reais; {{items_table}} vira a tabela de itens. A troca é textual, sem lógica (não há "se" nem laços). Para ver todos os nomes, use Variáveis disponíveis.

Idioma

O padrão é pt-BR. O idioma identifica o modelo, mas não traduz o conteúdo: os rótulos fixos de items_table saem em português.

Segurança do HTML

As imagens do HTML são verificadas para impedir que o servidor seja levado a abrir endereços internos. Scripts não são removidos do HTML do modelo: só administradores da loja podem criá-lo, mas trate o HTML de modelo como código da sua loja.

Endpoints

Erros comuns

• Enviar type fora da lista: a resposta é 500, não 400.
• Tentar apagar o modelo padrão (403) ou tirar o is_default do único padrão (409).
• Esquecer entity_id em render (400).
• Esperar um PDF de /pdf: é HTML para imprimir.
• Usar src de imagem em localhost ou data: sem poder hospedar: 400 invalid_image_src.
• Achar que variables é conferido: é só um rótulo informativo gravado como veio.

Próximos passos