Referência de dados do recibo
Os modelos HTML sem lógica e os modelos XML térmicos do WCPOS são renderizados a partir da mesma carga útil canônica de recibo. Use caminhos com ponto do Mustache, como {{order.number}}, {{store.name}} e {{totals.total_display}}. Os arrays são renderizados com seções:
{{#lines}}
{{name}} x {{qty}} — {{line_total_display}}
{{/lines}}
O contrato canônico é produzido no servidor pelo construtor de dados de recibo do WCPOS e espelhado pelo renderizador de recibos offline no aplicativo. Os recibos são abertos imediatamente a partir dos dados locais e, quando disponível, são atualizados com a resposta do servidor; portanto, os modelos personalizados devem usar os campos abaixo em vez de métodos de pedido PHP.
Os dados de recibo v1.1 adicionam campos registrados de preço normal, preço de venda antes do cupom e economia para cada linha de produto. Também fornecem totais de economia no nível do pedido, incluindo um valor de Total economizado que combina a economia do preço normal com os descontos do WooCommerce sem alterar os totais ou relatórios do pedido.
Os dados de recibo v1.2 adicionam discount_type a cada linha de desconto: o tipo de cupom do WooCommerce por trás do desconto.
O recibo, por seções
Cada parte de um recibo impresso vem de uma seção do contrato de dados. Passe o cursor sobre qualquer um dos lados para ver a correspondência e clique para ir aos campos dessa seção. Todos os exemplos desta página usam o mesmo pedido de exemplo.
store.name · store.address_lines · store.tax_ids · store.logoorder.number · order.created · cashier.name · customer.namelines[] · line_savings · savings_in_discountstotals.* · discounts[] · fees[] · shipping[] · totals.total_savedpayments[]store.personal_notes · store.policies_and_conditions · i18n.thank_you_purchaseReceitas comuns
A maioria das edições de modelos se enquadra em uma destas três opções. Cada cartão mostra primeiro o resultado impresso e depois a marcação exata — copie-a para qualquer modelo HTML ou XML térmico sem lógica. O terceiro cartão mostra um pedido legado anterior à v1.9, em vez do pedido de exemplo acima.
{{#lines}}
{{#line_savings}}
<s>{{line_regular_total_display}}</s>
{{i18n.savings}}: -{{line_savings_display}}
{{/line_savings}}
{{/lines}}{{#totals.total_saved_complete}}
{{#totals.total_saved}}
{{i18n.total_saved}}:
{{totals.total_saved_display}}
{{/totals.total_saved}}
{{/totals.total_saved_complete}}{{#lines}}
{{#line_savings}}
{{^savings_in_discounts}}
{{i18n.savings}}: -{{line_savings_display}}
{{/savings_in_discounts}}
{{/line_savings}}
{{/lines}}Estender os dados do recibo
O WCPOS mantém o contrato acima independente de fornecedores. Quando um plugin precisa incluir no recibo algo que o WooCommerce não modela, ele mesmo o adiciona pelo filtro woocommerce_pos_receipt_data, assim como os plugins filtram os totais dos pedidos do próprio WooCommerce. O filtro é executado em todos os recibos criados pelo servidor: recibos em tempo real, instantâneos fiscais no momento do pagamento, downloads de PDF e modelos PHP legados.
add_filter( 'woocommerce_pos_receipt_data', function ( array $data, WC_Abstract_Order $order, string $mode ) {
foreach ( $data['discounts'] as &$row ) {
if ( 'smart_coupon' === $row['discount_type'] ) {
$row['gift_card'] = true;
}
}
return $data;
}, 10, 3 );
Um modelo pode então verificar a nova chave em uma seção como qualquer outra:
{{#discounts}}
{{#gift_card}}Gift Card{{/gift_card}}{{^gift_card}}{{i18n.discount}}{{/gift_card}}{{#label}}: {{label}}{{/label}}
{{/discounts}}
As chaves definidas no esquema devem manter seus tipos documentados. As chaves adicionadas não fazem parte do esquema; portanto, não aparecem no seletor de campos do editor de modelos, e os instantâneos fiscais só contêm os dados adicionados pelo filtro no momento em que o pedido foi pago. O filtro está disponível a partir do WCPOS 1.10.8.
Regras de renderização
Campos de moeda
Os campos monetários numéricos são preservados como números, e o renderizador adiciona campos _display adaptados à localidade para a saída do modelo:
| Campo numérico | Campo de exibição |
|---|---|
totals.total | totals.total_display |
lines[].line_total | lines[].line_total_display |
payments[].amount | payments[].amount_display |
tax_summary[].tax_amount | tax_summary[].tax_amount_display |
Prefira os campos _display ao imprimir recibos. Use os campos numéricos apenas em seções condicionais ou em saídas legíveis por máquina.
Campos que consideram a exibição de impostos
Vários campos têm variantes com e sem impostos, além de um valor de conveniência para exibição. Esse valor segue a configuração de exibição de impostos no carrinho da loja.
| Campo de conveniência | Campo com impostos | Campo sem impostos |
|---|---|---|
lines[].regular_price | lines[].regular_price_incl | lines[].regular_price_excl |
lines[].selling_price | lines[].selling_price_incl | lines[].selling_price_excl |
lines[].unit_savings | lines[].unit_savings_incl | lines[].unit_savings_excl |
lines[].line_regular_total | lines[].line_regular_total_incl | lines[].line_regular_total_excl |
lines[].line_selling_total | lines[].line_selling_total_incl | lines[].line_selling_total_excl |
lines[].line_savings | lines[].line_savings_incl | lines[].line_savings_excl |
lines[].unit_price | lines[].unit_price_incl | lines[].unit_price_excl |
lines[].unit_subtotal | lines[].unit_subtotal_incl | lines[].unit_subtotal_excl |
lines[].line_subtotal | lines[].line_subtotal_incl | lines[].line_subtotal_excl |
lines[].discounts | lines[].discounts_incl | lines[].discounts_excl |
lines[].line_total | lines[].line_total_incl | lines[].line_total_excl |
fees[].total | fees[].total_incl | fees[].total_excl |
shipping[].total | shipping[].total_incl | shipping[].total_excl |
discounts[].total | discounts[].total_incl | discounts[].total_excl |
totals.subtotal | totals.subtotal_incl | totals.subtotal_excl |
totals.discount_total | totals.discount_total_incl | totals.discount_total_excl |
totals.sale_savings_total | totals.sale_savings_total_incl | totals.sale_savings_total_excl |
totals.total_saved | totals.total_saved_incl | totals.total_saved_excl |
totals.total | totals.total_incl | totals.total_excl |
Objetos de data
Os campos de data são objetos com diversas variantes pré-formatadas. Isso evita formatar datas dentro do Mustache.
| Campo | Descrição |
|---|---|
datetime, date, time | Strings padrão de data/hora |
datetime_short, datetime_long, datetime_full | Formatos combinados adaptados à localidade |
date_short, date_long, date_full | Formatos apenas de data adaptados à localidade |
date_ymd, date_dmy, date_mdy | Formatos de data com ordem fixa |
weekday_short, weekday_long | Nomes dos dias da semana |
day, month, month_short, month_long, year | Partes individuais da data |
Objetos de data disponíveis: order.created, order.paid, order.completed, order.printed e refunds[].date. order.printed é atualizado no momento da renderização, o que é útil para reimpressões.
Seções principais
| Seção | Tipo | Descrição |
|---|---|---|
order | objeto | Identidade, status, datas, observação e informações da URL de pagamento do pedido |
store | objeto | Identidade, endereço, contato, identificações fiscais, logotipo, horário de funcionamento e texto de rodapé da loja |
cashier | objeto | Usuário que processou o pedido |
customer | objeto | Nome de exibição, endereços e identificações fiscais do cliente |
lines | array | Itens de produto do pedido |
fees | array | Linhas de taxas |
shipping | array | Linhas de entrega |
discounts | array | Linhas de cupons/descontos |
totals | objeto | Totais do pedido, totais de pagamento, resumo de reembolsos e contagem de itens |
tax | objeto | Indicadores do modo de exibição de impostos para seções condicionais |
tax_summary | array | Linhas de resumo de impostos por alíquota |
has_tax_summary | booleano | Indicador de conveniência para tax_summary |
payments | array | Linhas de pagamento |
refunds | array | Registros de reembolso aplicados ao pedido |
fiscal | objeto | Campos de instantâneo fiscal preenchidos por integrações fiscais |
presentation_hints | objeto | Dicas para formatação e renderização |
i18n | objeto | Rótulos traduzidos para modelos incluídos e personalizados |
Como os preços se relacionam
Uma linha de produto contém vários preços, cujos nomes ficam mais claros quando vistos nos próprios valores. Esta é a linha de espresso do pedido de exemplo — um produto de $17.00 em promoção por $14.50, com mais um cupom de 10%:
unit_price → 13.05 · line_total → 26.10lines[].discounts → 2.90 nesta linhaunit_savings → 2.50 · line_savings → 5.00totals.sale_savings_total = 5.00totals.discount_total = 5.28totals.total_saved = 10.28A economia com promoções e os descontos de cupons são coisas diferentes: a economia com promoções compara o preço de venda com o preço normal registrado, enquanto discounts representa os cálculos de cupons do próprio WooCommerce. Os totais e relatórios de pedidos do WooCommerce incluem apenas a parte dos cupons — por isso, total_saved existe como o valor único, exibido ao cliente, que combina ambos.
Referência de campos
A referência completa dos campos está agrupada por seção abaixo. Tudo começa recolhido — expanda o grupo de que você precisa.
order — identidade, status e datas
order
| Campo | Tipo | Exemplo / descrição |
|---|---|---|
order.id | number | 1042 |
order.number | string | Número do pedido exibido ao usuário, por exemplo, "1042" |
order.currency | string | Código de moeda ISO, por exemplo, "USD" |
order.customer_note | string | Observação do cliente/pedido |
order.wc_status | string | Slug de status bruto do WooCommerce, por exemplo, "processing" |
order.status_label | string | Rótulo de status localizado, inclusive para status personalizados |
order.created_via | string | Origem/canal, por exemplo, "woocommerce-pos" |
order.needs_payment | boolean | Se uma seção de pagamento deve ser exibida |
order.payment_url | string | URL de pagamento do pedido, quando disponível |
order.created | date object | Data de criação do pedido |
order.paid | date object | Data do pagamento; strings vazias se não foi pago |
order.completed | date object | Data da conclusão; strings vazias se não foi concluído |
order.printed | date object | Data e hora da impressão/reimpressão no momento da renderização |
store — identidade, endereço, contato e horários
store
| Campo | Tipo | Exemplo / descrição |
|---|---|---|
store.id | number | ID da loja ou ID histórico de lojas excluídas |
store.name | string | Nome de exibição da loja |
store.address.address_1 | string | Linha 1 do endereço |
store.address.address_2 | string | Linha de complemento/unidade |
store.address.city | string | Cidade/localidade |
store.address.state | string | Estado/região |
store.address.postcode | string | Código postal |
store.address.country | string | Código ISO do país |
store.address_lines | array | Linhas de endereço pré-formatadas; recomendadas para a maioria dos modelos |
store.tax_ids | array | Identificações fiscais estruturadas da empresa; percorra esta lista em vez de usar uma única identificação fiscal |
store.phone | string | Telefone da loja |
store.email | string | E-mail da loja |
store.logo | string/null | URL ou URI de dados do logotipo da loja |
store.opening_hours | string/null | Texto compacto do horário de funcionamento |
store.opening_hours_vertical | string/null | Bloco de horário de funcionamento em várias linhas |
store.opening_hours_inline | string/null | Texto do horário de funcionamento separado por vírgulas |
store.opening_hours_notes | string/null | Observações livres sobre o horário de funcionamento |
store.personal_notes | string/null | Rodapé do recibo/observação pessoal |
store.policies_and_conditions | string/null | Texto sobre reembolsos, devoluções ou condições |
store.footer_imprint | string/null | Informações legais no rodapé |
Objetos de identificação fiscal
store.tax_ids e customer.tax_ids contêm objetos com a mesma estrutura:
| Campo | Tipo | Descrição |
|---|---|---|
type | string | Identificador como eu_vat, de_steuernummer, au_abn, br_cpf, us_ein ou other |
value | string | Valor da identificação fiscal a imprimir |
country | string/null | Código ISO do país, quando conhecido |
label | string/null | Rótulo de exibição localizado, definido antes da renderização |
Exemplo:
{{#store.tax_ids}}
{{label}}: {{value}}
{{/store.tax_ids}}
cashier — usuário que processou o pedido
cashier
| Campo | Tipo | Exemplo / descrição |
|---|---|---|
cashier.id | number | ID do usuário do WordPress; 0 quando desconhecido |
cashier.name | string | Nome de exibição do caixa |
customer — nome, endereços e identificações fiscais
customer
| Campo | Tipo | Exemplo / descrição |
|---|---|---|
customer.id | number/null | ID do cliente ou null para visitantes |
customer.name | string | Nome de exibição do cliente ou rótulo de visitante |
customer.billing_address.* | object | Campos do endereço de cobrança do WooCommerce |
customer.shipping_address.* | object | Campos do endereço de entrega do WooCommerce |
customer.tax_ids | array | Identificações fiscais estruturadas do cliente registradas no pedido |
As chaves comuns de endereço incluem first_name, last_name, company, address_1, address_2, city, state, postcode, country, email e phone.
lines — itens de produto do pedido
lines
Percorra {{#lines}}...{{/lines}}. Os valores de exemplo são da linha de espresso do pedido de exemplo.
Cada campo monetário vem em par: o número (use-o nas condições {{#…}} — zero e null ocultam a seção, e um campo null não tem correspondente _display) e sua string _display (use-a para imprimir). Os campos marcados incl/excl também têm variantes _incl e _excl, cada uma com seu próprio _display.
null em pedidos sem histórico de preços no WCPOS — inclua-o em uma seção.discounts — indicador para evitar contagem dupla.{key, value}.{key, value}.Exibição do preço normal e da economia
Para um layout de preço unitário, mostre o preço normal registrado, o preço de venda e a economia assim:
{{#lines}}
{{#unit_savings}}
<span style="text-decoration: line-through;">{{regular_price_display}}</span>
<span>{{selling_price_display}}</span>
<span>{{i18n.savings}}: -{{unit_savings_display}}</span>
{{/unit_savings}}
{{/lines}}
Use os campos de total da linha quando a quantidade importar:
{{#lines}}
{{#line_savings}}
<span style="text-decoration: line-through;">{{line_regular_total_display}}</span>
<span>{{i18n.savings}}: -{{line_savings_display}}</span>
{{/line_savings}}
{{/lines}}
selling_price é o preço antes dos cupons. Use unit_price ou line_total para o valor final após os descontos do WooCommerce.
Pedidos mais antigos do WCPOS podem já incluir a redução do preço normal para o preço de venda em discounts. Se seu modelo personalizado imprimir tanto a economia da linha quanto os descontos da linha, use savings_in_discounts para evitar mostrar a mesma redução duas vezes:
{{#lines}}
{{#line_savings}}
<span style="text-decoration: line-through;">{{line_regular_total_display}}</span>
{{^savings_in_discounts}}
<span>{{i18n.savings}}: -{{line_savings_display}}</span>
{{/savings_in_discounts}}
{{/line_savings}}
{{#discounts}}
<span>{{i18n.discount}}: -{{discounts_display}}</span>
{{/discounts}}
{{/lines}}
Se o modelo não imprimir uma linha de discounts por item, continue exibindo line_savings mesmo quando savings_in_discounts for verdadeiro. Os modelos incluídos tratam dessa distinção automaticamente.
fees e shipping
fees e shipping
Percorra {{#fees}}...{{/fees}} e {{#shipping}}...{{/shipping}}.
| Campo | Tipo | Descrição |
|---|---|---|
label | string | Rótulo da taxa ou nome da forma de entrega |
method_id | string | ID da forma de entrega (apenas entrega) |
total / _incl / _excl | number | Totais para exibição, com impostos e sem impostos |
taxes | array | Linhas de impostos por alíquota |
meta | array | Pares de metadados {key, value} |
Variantes formatadas: total_display, total_incl_display e total_excl_display.
discounts — linhas de cupons/descontos
discounts
Percorra {{#discounts}}...{{/discounts}}.
| Campo | Tipo | Descrição |
|---|---|---|
label | string | Descrição do cupom ou, se ausente, código |
code | string | Código do cupom |
discount_type | string | Slug do tipo de cupom do WooCommerce, por exemplo, fixed_cart, percent ou fixed_product. Vazio quando o cupom não existe mais. |
total / _incl / _excl | number | Valor do desconto como número positivo |
Variantes formatadas: total_display, total_incl_display e total_excl_display. Adicione o sinal de menos no próprio modelo se quiser exibir os descontos como linhas negativas.
discount_type foi adicionado nos dados de recibo v1.2. Instantâneos fiscais de recibos capturados antes disso não o contêm.
totals — totais do pedido, de pagamentos, de reembolsos e de itens
totals
Os valores de exemplo vêm do pedido de exemplo, que posteriormente recebeu um reembolso parcial de $7.25.
Os campos monetários seguem o mesmo par dos itens do pedido: um número simples para condições e uma string _display para impressão, com variantes _incl/_excl onde indicado.
Use total_saved quando quiser mostrar ao cliente um único valor para toda a economia. Não o calcule somando discount_total e sale_savings_total no modelo: pedidos criados antes da v1.9.0 podem já incluir a economia de preços do WCPOS no total de descontos do WooCommerce. O campo canônico total_saved detecta e elimina essa sobreposição.
Os totais de economia são null e total_saved_complete é falso quando alguma linha de produto não tem dados de preço registrados suficientes para um total confiável. Condicione a linha a total_saved_complete e use total_saved para ocultar o valor zero:
{{#totals.total_saved_complete}}
{{#totals.total_saved}}
<span>{{i18n.total_saved}}: {{totals.total_saved_display}}</span>
{{/totals.total_saved}}
{{/totals.total_saved_complete}}
Os modelos incluídos que exibem preços usam a mesma estrutura condicional com as variantes que incluem impostos (total_saved_incl e total_saved_incl_display) e mostram Total economizado apenas quando o valor completo é maior que zero.
tax e tax_summary — condições de exibição e linhas por alíquota
tax e tax_summary
Use tax para condições de modo de exibição e tax_summary para linhas detalhadas por alíquota.
| Campo de imposto | Tipo | Descrição |
|---|---|---|
tax.display | string | incl ou excl |
tax.display_incl | boolean | Verdadeiro quando os preços são exibidos com impostos |
tax.display_excl | boolean | Verdadeiro quando os preços são exibidos sem impostos |
tax.breakdown | string | hidden, single ou itemized |
tax.breakdown_hidden | boolean | Verdadeiro quando as linhas de impostos devem ser ocultadas |
tax.breakdown_single | boolean | Verdadeiro quando se prefere um único total de impostos |
tax.breakdown_itemized | boolean | Verdadeiro quando se preferem linhas por alíquota |
has_tax_summary | boolean | Verdadeiro quando tax_summary contém linhas |
Percorra tax_summary com {{#tax_summary}}...{{/tax_summary}}.
| Campo | Tipo | Descrição |
|---|---|---|
code | string | ID/código da alíquota |
rate | number/null | Percentual da alíquota, quando identificado |
label | string | Rótulo da alíquota |
compound | boolean | Se a alíquota é composta |
taxable_amount_excl | number/null | Base tributável sem impostos |
tax_amount | number | Imposto cobrado |
taxable_amount_incl | number/null | Base tributável com impostos |
Variantes formatadas: taxable_amount_excl_display, tax_amount_display e taxable_amount_incl_display.
payments — linhas de pagamento
payments
Percorra {{#payments}}...{{/payments}}.
| Campo | Tipo | Descrição |
|---|---|---|
method_id | string | Identificador da forma de pagamento |
method_title | string | Título exibido da forma de pagamento |
amount | number | Valor aplicado ao pedido |
transaction_id | string | ID da transação do gateway |
tendered | number | Valor em dinheiro recebido, quando disponível |
change | number | Troco devolvido, quando disponível |
Variantes formatadas: amount_display, tendered_display e change_display.
refunds — registros de reembolso
refunds
Percorra {{#refunds}}...{{/refunds}}. Os valores de reembolso são magnitudes positivas; os modelos decidem se devem acrescentar um sinal de menos ou renderizar um bloco separado de itens devolvidos.
| Campo | Tipo | Descrição |
|---|---|---|
id | number | ID do registro de reembolso |
date | date object | Data de criação do reembolso |
amount | number | Total do reembolso |
subtotal | number | Subtotal das linhas reembolsadas |
tax_total | number | Imposto reembolsado |
shipping_total | number | Valor da entrega reembolsado |
shipping_tax | number | Imposto sobre a entrega reembolsado |
reason | string | Motivo do reembolso |
refunded_by_id | number/null | ID do usuário que emitiu o reembolso |
refunded_by_name | string | Nome de exibição do usuário que emitiu o reembolso |
refunded_payment | boolean | Se o pagamento foi reembolsado pelo gateway |
destination | string | original_method, cash ou manual |
gateway_id | string | ID do gateway usado no reembolso |
gateway_title | string | Título de exibição do gateway |
processing_mode | string | Modo de processamento pelo provedor/manual |
lines | array | Linhas de produtos reembolsados |
fees | array | Linhas de taxas reembolsadas |
shipping | array | Linhas de entrega reembolsadas |
Os campos das linhas de reembolso incluem name, sku, qty, total, total_incl, total_excl, line_total, unit_total e taxes. As linhas de taxas e entrega reembolsadas usam label, total, total_incl, total_excl e taxes. Variantes de exibição são adicionadas para totais e valores de impostos.
fiscal — instantâneo da integração fiscal
fiscal
Os campos fiscais ficam vazios por padrão e são preenchidos pelas integrações fiscais ou pelo enriquecimento de instantâneos do WCPOS Pro.
| Campo | Tipo | Descrição |
|---|---|---|
fiscal.immutable_id | string | Identificador fiscal imutável |
fiscal.receipt_number | string | Número do recibo fiscal |
fiscal.sequence | number/null | Contador sequencial |
fiscal.hash | string | Valor de hash/assinatura |
fiscal.qr_payload | string | Conteúdo do QR para verificação fiscal |
fiscal.tax_agency_code | string | Código da autoridade fiscal |
fiscal.signed_at | string | Data e hora da assinatura fiscal |
fiscal.signature_excerpt | string | Trecho da assinatura para exibição |
fiscal.document_label | string | Rótulo do documento, por exemplo, Nota fiscal |
fiscal.is_reprint | boolean | Se esta renderização é uma reimpressão |
fiscal.reprint_count | number | Número de reimpressões |
fiscal.extra_fields | array/object | Valores específicos da jurisdição |
presentation_hints — dicas de formatação e renderização
presentation_hints
Esses campos são usados principalmente pelo renderizador e pelo formatador. Eles ficam disponíveis aos modelos quando necessário.
| Campo | Tipo | Descrição |
|---|---|---|
presentation_hints.display_tax | string | incl, excl, hidden, itemized ou single |
presentation_hints.prices_entered_with_tax | boolean | Se os preços do catálogo incluem impostos |
presentation_hints.rounding_mode | string | Configuração de arredondamento de impostos do WooCommerce |
presentation_hints.locale | string | Localidade usada na formatação |
presentation_hints.timezone | string | Fuso horário do recibo |
presentation_hints.currency_position | string | Posição do símbolo da moeda |
presentation_hints.currency_symbol | string | Símbolo da moeda |
presentation_hints.price_thousand_separator | string | Separador de milhares |
presentation_hints.price_decimal_separator | string | Separador decimal |
presentation_hints.price_num_decimals | number | Casas decimais |
presentation_hints.price_display_suffix | string | Sufixo de exibição de preços do WooCommerce |
presentation_hints.order_barcode_type | string | Tipo de código de barras usado pelos modelos da galeria |
Os campos monetários pré-formatados (valores *_display como totals.total_display) renderizam os valores com o símbolo da moeda do pedido, usando a posição e os separadores acima — assim os recibos mostram $12.00, não USD 12.00. O campo bruto order.currency continua sendo o código ISO para qualquer lógica do seu modelo.
i18n — rótulos traduzidos
i18n
Use rótulos de i18n em vez de escrever o texto diretamente sempre que possível:
{{i18n.order}} #{{order.number}}
{{i18n.cashier}}: {{cashier.name}}
{{i18n.total}}: {{totals.total_display}}
As chaves comuns incluem order, date, cashier, customer, item, sku, qty, unit_price, regular_price, selling_price, savings, discount, subtotal, total_saved, total, tax, paid, tendered, change, tax_summary, refunded, net_total, customer_note, thank_you_purchase, opening_hours e as chaves de rótulos de identificação fiscal, como store_tax_id_label_eu_vat e customer_tax_id_label_other. Extensões podem adicionar outras chaves.