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

Modelos de documento: listar e consultar

Lista os modelos de fatura, romaneio e nota de crédito, consulta um modelo, acha o padrão de um tipo e lista as variáveis disponíveis.

Um modelo de documento é um HTML com marcadores {{variavel}} que a plataforma preenche com os dados de um pedido para gerar uma fatura, um romaneio de separação, uma nota de crédito ou um documento livre. Estas rotas leem os modelos da loja. Para editar, veja Criar e editar modelos. Basta ser administrador da loja: nenhuma delas exige um privilégio específico.

Listar modelos

GET/api/v1/admin/documentsAdmin

Listar modelos de documento

Parâmetros de consulta

typestring
invoicepacking_slipcredit_memocustom
Só modelos deste tipo. Sem o parâmetro, todos.

Exemplo de requisição (listar)

bash
curl "$BASE_URL/api/v1/admin/documents?type=invoice" \
  -H "Authorization: Bearer $TOKEN"

Resposta (listar)

200Modelos
json
{
  "documents": [{
      "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"
    }],
  "total": 1
}

Campos da resposta

documentsarray
Modelos da loja.
documents[].iduuid
Id do modelo.
documents[].namestring
Nome do modelo.
documents[].typestring
invoicepacking_slipcredit_memocustom
Tipo do documento.
documents[].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).
documents[].variablesarray
Nomes das variáveis que o autor declarou usar. É informativo: é gravado como veio, não é calculado nem conferido contra o corpo.
documents[].is_defaultboolean
Se é o modelo padrão do seu tipo e idioma.
documents[].languagestring
Idioma, por exemplo pt-BR.
documents[].created_atstring
Criação, RFC 3339.
documents[].updated_atstring
Última alteração, RFC 3339.
totalinteger
Quantidade.

Erros (listar)

StatusQuandoCorpo
401Sem token, token inválido ou expirado.{"error":"missing authorization header"}
500type fora de invoice, packing_slip, credit_memo, custom. Hoje volta como 500, não 400.{"error":"failed to list documents","detail":"invalid document type: foo"}
500Falha inesperada no servidor.{"error":"failed to ..."}

Consultar modelo

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

Consultar um modelo

Parâmetros de caminho

iduuidobrigatório
Id do modelo (UUID).

Exemplo de requisição (consultar)

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

Resposta (consultar)

200Modelo
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 (consultar)

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 ..."}

Modelo padrão

GET/api/v1/admin/documents/defaultAdmin

Achar o modelo padrão de um tipo

Parâmetros de consulta

typestringobrigatório
invoicepacking_slipcredit_memocustom
Tipo do documento.
languagestringpadrão: pt-BR
Idioma.

Exemplo de requisição (padrão)

bash
curl "$BASE_URL/api/v1/admin/documents/default?type=invoice&language=pt-BR" \
  -H "Authorization: Bearer $TOKEN"

Resposta (padrão)

200Modelo padrão
json
{
  "id": "3204f98e-2c66-42d5-baee-bbc191a1b063",
  "name": "Etiqueta de pedido",
  "type": "invoice",
  "body_html": "<h1>Pedido {{order_number}}</h1><p>{{customer_name}} total {{total}}</p>",
  "variables": ["order_number", "customer_name", "total"],
  "is_default": true,
  "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 (padrão)

StatusQuandoCorpo
401Sem token, token inválido ou expirado.{"error":"missing authorization header"}
400Falta type.{"error":"type parameter is required"}
404Não há modelo padrão para o tipo.{"error":"no default document found for this type"}
500type fora de invoice, packing_slip, credit_memo, custom. Hoje volta como 500, não 400.{"error":"failed to get default document","detail":"invalid document type: foo"}
500Falha inesperada no servidor.{"error":"failed to ..."}

Variáveis disponíveis

GET/api/v1/admin/documents/fieldsAdmin

Variáveis disponíveis nos modelos

Exemplo de requisição (variáveis)

bash
curl "$BASE_URL/api/v1/admin/documents/fields" \
  -H "Authorization: Bearer $TOKEN"

Resposta (variáveis)

200Variáveis
json
{
  "fields": [
    { "name": "order_number", "label": "Order Number", "source": "order.order_number" },
    { "name": "total", "label": "Total", "source": "order.total" },
    { "name": "items_table", "label": "Order Items Table (HTML)", "source": "items" }
  ],
  "total": 31
}

Campos da resposta

fieldsarray
Variáveis que o editor oferece.
fields[].namestring
Nome da variável: escreva {{name}} no HTML.
fields[].labelstring
Rótulo em inglês.
fields[].sourcestring
De onde vem o dado.
totalinteger
Quantidade.

Erros (variáveis)

StatusQuandoCorpo
401Sem token, token inválido ou expirado.{"error":"missing authorization header"}
Variáveis a mais do que a lista

O renderizador também preenche customer_cpf, customer_cnpj, customer_document, legal_name e trade_name (identidade do cliente pessoa física ou jurídica), que a lista de fields ainda não traz. Marcador desconhecido é deixado no texto como está, sem erro.

Valores prontos para imprimir

Valores em dinheiro saem formatados (R$ 182,00), datas em dd/mm/aaaa, e items_table vira uma tabela HTML pronta. Isso é só para o documento: os dados da API em centavos não mudam.

Veja também

  • Criar e editar modelos
  • Gerar o documento
Anterior
Documentos
Próxima
Criar e editar modelos
Nesta página
  • Listar modelos
  • Exemplo de requisição (listar)
  • Resposta (listar)
  • Erros (listar)
  • Consultar modelo
  • Exemplo de requisição (consultar)
  • Resposta (consultar)
  • Erros (consultar)
  • Modelo padrão
  • Exemplo de requisição (padrão)
  • Resposta (padrão)
  • Erros (padrão)
  • Variáveis disponíveis
  • Exemplo de requisição (variáveis)
  • Resposta (variáveis)
  • Erros (variáveis)
  • Veja também