VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa/Documentos

Criar e editar modelos

Cria, altera, duplica e apaga modelos de documento, com as regras do modelo padrão e a proteção das imagens.

Cada tipo de documento e idioma tem exatamente um modelo padrão, que a plataforma usa ao gerar faturas e romaneios sem que ninguém escolha. Você pode criar quantos modelos quiser, mas o padrão é protegido: não pode ser apagado, e não pode deixar de ser padrão sem que outro assuma. O HTML passa por uma verificação que bloqueia imagens apontando para endereços internos.

Criar

POST/api/v1/admin/documentsAdmin

Criar um modelo

Corpo da requisição

namestringobrigatório
Nome do modelo, até 255 caracteres.
typestringobrigatório
invoicepacking_slipcredit_memocustom
Tipo.
body_htmlstringobrigatório
HTML do documento com marcadores {{variavel}}. Em <img src> valem URLs http(s) públicas, caminhos relativos e {{variaveis}}; imagens data: base64 são hospedadas automaticamente.
variablesarraypadrão: []
Nomes das variáveis usadas (informativo).
is_defaultbooleanpadrão: false
true torna este o padrão do tipo e idioma e desmarca o anterior.
languagestringpadrão: pt-BR
Idioma.

Exemplo de requisição (criar)

bash
curl -X POST "$BASE_URL/api/v1/admin/documents" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Etiqueta de pedido", "type": "custom", "body_html": "<h1>Pedido {{order_number}}</h1><p>{{customer_name}} total {{total}}</p>", "variables": ["order_number", "customer_name", "total"], "language": "pt-BR"}'

Resposta (criar)

201Modelo criado
json
{
  "id": "3204f98e-2c66-42d5-baee-bbc191a1b063",
  "name": "Etiqueta de pedido",
  "type": "custom",
  "body_html": "<h1>Pedido {{order_number}}</h1><p>{{customer_name}} total {{total}}</p>",
  "variables": ["order_number", "customer_name", "total"],
  "is_default": false,
  "language": "pt-BR",
  "created_at": "2026-10-11T21:19:07.694671Z",
  "updated_at": "2026-10-11T21:19:07.694671Z"
}

Campos da resposta

iduuid
Id do modelo.
namestring
Nome do modelo.
typestring
invoicepacking_slipcredit_memocustom
Tipo do documento.
body_htmlstring
O HTML do documento, com marcadores {{variavel}}. As aspas, < e > vêm escapados como \u003c no JSON (é só a forma de escrever; ao decodificar volta o HTML).
variablesarray
Nomes das variáveis que o autor declarou usar. É informativo: é gravado como veio, não é calculado nem conferido contra o corpo.
is_defaultboolean
Se é o modelo padrão do seu tipo e idioma.
languagestring
Idioma, por exemplo pt-BR.
created_atstring
Criação, RFC 3339.
updated_atstring
Última alteração, RFC 3339.

Erros (criar)

StatusQuandoCorpo
401Sem token, token inválido ou expirado.{"error":"missing authorization header"}
400Corpo que não é JSON válido.{"error":"invalid JSON body","detail":"..."}
400Falta name, type ou body_html.{"error":"name, type, and body_html are required"}
400<img src> aponta para endereço interno, ou tem esquema data:/javascript: que não pôde ser hospedado.{"error":"invalid_image_src","detail":"invalid_image_src: ssrf_forbidden: url targets internal/private/loopback address (src=http://127.0.0.1/x.png)"}
500type fora de invoice, packing_slip, credit_memo, custom. Hoje volta como 500, não 400.{"error":"failed to create document","detail":"invalid document type: foo"}

Alterar

PUT/api/v1/admin/documents/{id}Admin

Alterar um modelo

Parâmetros de caminho

iduuidobrigatório
Id do modelo (UUID).

Corpo da requisição

namestring
Nome do modelo, até 255 caracteres.
typestring
invoicepacking_slipcredit_memocustom
Tipo.
body_htmlstring
HTML do documento com marcadores {{variavel}}. Em <img src> valem URLs http(s) públicas, caminhos relativos e {{variaveis}}; imagens data: base64 são hospedadas automaticamente.
variablesarray
Nomes das variáveis usadas (informativo).
is_defaultboolean
true torna este o padrão do tipo e idioma e desmarca o anterior.
languagestring
Idioma.

Exemplo de requisição (alterar)

bash
curl -X PUT "$BASE_URL/api/v1/admin/documents/3204f98e-2c66-42d5-baee-bbc191a1b063" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Etiqueta de pedido v2"}'

Resposta (alterar)

200Modelo alterado
json
{
  "id": "3204f98e-2c66-42d5-baee-bbc191a1b063",
  "name": "Etiqueta de pedido v2",
  "type": "custom",
  "body_html": "<h1>Pedido {{order_number}}</h1><p>{{customer_name}} total {{total}}</p>",
  "variables": ["order_number", "customer_name", "total"],
  "is_default": false,
  "language": "pt-BR",
  "created_at": "2026-10-11T21:19:07.694671Z",
  "updated_at": "2026-10-11T21:19:07.694671Z"
}

Campos da resposta

(objeto)object
O modelo depois da alteração. Só os campos enviados mudam (alteração parcial).

Erros (alterar)

StatusQuandoCorpo
401Sem token, token inválido ou expirado.{"error":"missing authorization header"}
400Corpo que não é JSON válido.{"error":"invalid JSON body","detail":"..."}
404O modelo não existe.{"error":"document not found"}
400<img src> aponta para endereço interno, ou tem esquema data:/javascript: que não pôde ser hospedado.{"error":"invalid_image_src","detail":"invalid_image_src: ssrf_forbidden: url targets internal/private/loopback address (src=http://127.0.0.1/x.png)"}
409Tirar is_default do único modelo padrão do tipo e idioma.{"error":"documents.last_default_protected","detail":"documents: cannot unset is_default \u2014 at least one default template must exist for this type+language; mark another template as default first"}
500type fora de invoice, packing_slip, credit_memo, custom. Hoje volta como 500, não 400.{"error":"failed to update document","detail":"invalid document type: foo"}

Duplicar

POST/api/v1/admin/documents/{id}/duplicateAdmin

Duplicar um modelo

Parâmetros de caminho

iduuidobrigatório
Id do modelo (UUID).

Exemplo de requisição (duplicar)

bash
curl -X POST "$BASE_URL/api/v1/admin/documents/3204f98e-2c66-42d5-baee-bbc191a1b063/duplicate" \
  -H "Authorization: Bearer $TOKEN"

Resposta (duplicar)

201Cópia criada
json
{
  "id": "3204f98e-2c66-42d5-baee-bbc191a1b063",
  "name": "Etiqueta de pedido (copy)",
  "type": "custom",
  "body_html": "<h1>Pedido {{order_number}}</h1><p>{{customer_name}} total {{total}}</p>",
  "variables": ["order_number", "customer_name", "total"],
  "is_default": false,
  "language": "pt-BR",
  "created_at": "2026-10-11T21:19:07.694671Z",
  "updated_at": "2026-10-11T21:19:07.694671Z"
}

Campos da resposta

(objeto)object
O novo modelo: o nome ganha o sufixo (copy) (em inglês) e a cópia nunca é padrão.

Erros (duplicar)

StatusQuandoCorpo
401Sem token, token inválido ou expirado.{"error":"missing authorization header"}
404O modelo não existe.{"error":"document not found"}
500Falha inesperada no servidor.{"error":"failed to ..."}

Apagar

DELETE/api/v1/admin/documents/{id}Admin

Apagar um modelo

Parâmetros de caminho

iduuidobrigatório
Id do modelo (UUID).

Exemplo de requisição (apagar)

bash
curl -X DELETE "$BASE_URL/api/v1/admin/documents/3204f98e-2c66-42d5-baee-bbc191a1b063" \
  -H "Authorization: Bearer $TOKEN"

Resposta (apagar)

200Modelo apagado
json
{
  "message": "document deleted"
}

Campos da resposta

messagestring
Texto fixo de confirmação, em inglês.

Erros (apagar)

StatusQuandoCorpo
401Sem token, token inválido ou expirado.{"error":"missing authorization header"}
404O modelo não existe.{"error":"document not found"}
403O modelo é o padrão do seu tipo.{"error":"cannot delete default document template"}
500Falha inesperada no servidor.{"error":"failed to ..."}
Apagar é definitivo

O modelo é removido de verdade, sem lixeira. Para trocar o padrão, marque outro modelo com is_default: true (isso desmarca o antigo) e só então apague o antigo.

Imagens no HTML

Imagens em base64 (data:image/...) são enviadas para a mídia da loja e trocadas por um endereço público. <img src> que aponte para localhost, rede privada ou esquema não http(s) é recusado com 400 invalid_image_src, e a mensagem diz qual src falhou.

Veja também

  • Listar modelos
  • Gerar o documento
Anterior
Modelos de documento: listar e consultar
Próxima
Gerar o documento
Nesta página
  • Criar
  • Exemplo de requisição (criar)
  • Resposta (criar)
  • Erros (criar)
  • Alterar
  • Exemplo de requisição (alterar)
  • Resposta (alterar)
  • Erros (alterar)
  • Duplicar
  • Exemplo de requisição (duplicar)
  • Resposta (duplicar)
  • Erros (duplicar)
  • Apagar
  • Exemplo de requisição (apagar)
  • Resposta (apagar)
  • Erros (apagar)
  • Veja também