# 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 do mesmo payload canônico de recibo. Utilize caminhos de ponto Mustache como `{{order.number}}`, `{{store.name}}` e `{{totals.total_display}}`. Arrays são renderizados com seções:

```
{{#lines}}

  {{name}} x {{qty}} — {{line_total_display}}

{{/lines}}
```

O contrato canônico é produzido pelo construtor de dados de recibo do WCPOS no servidor e espelhado pelo renderizador de recibos offline no aplicativo. Os recibos são abertos imediatamente a partir dos dados locais e, em seguida, atualizados com a resposta do servidor quando disponível. Portanto, modelos personalizados devem utilizar os campos abaixo em vez de métodos PHP de pedido.

## Regras de renderização[​](#rendering-rules "Link direto para Regras de renderização")

### Campos de moeda[​](#currency-fields "Link direto para Campos de moeda")

Os campos monetários numéricos são preservados como números, e o renderizador adiciona campos `_display` com formatação de localidade para saída no 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 para seções condicionais ou saída legível por máquina.

### Campos com exibição de impostos[​](#tax-display-aware-fields "Link direto para Campos com exibição de impostos")

Vários campos possuem variantes com impostos inclusos e exclusos, além de um valor de conveniência para exibição. O valor de conveniência segue a configuração de exibição de impostos do carrinho da loja.

| Campo de conveniência   | Campo com impostos inclusos  | Campo com impostos exclusos  |
| ----------------------- | ---------------------------- | ---------------------------- |
| `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.total`          | `totals.total_incl`          | `totals.total_excl`          |

### Objetos de data[​](#date-objects "Link direto para Objetos de data")

Os campos de data são objetos com múltiplas variantes pré-formatadas. Isso evita a necessidade de formatação de 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 ao idioma |
| `date_short`, `date_long`, `date_full`              | Formatos de data conforme o idioma      |
| `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 de nível superior[​](#top-level-sections "Link direto para Seções de nível superior")

| Seção                | Tipo    | Descrição                                                                                                                |
| -------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------ |
| `order`              | object  | Identificação do pedido, status, datas, observação e informações de URL de pagamento                                     |
| `store`              | object  | Identificação da loja, endereço, dados de contato, números fiscais, logotipo, horário de funcionamento e texto de rodapé |
| `cashier`            | object  | Usuário que processou o pedido                                                                                           |
| `customer`           | object  | Nome de exibição do cliente, endereços e números fiscais                                                                 |
| `lines`              | array   | Itens de linha do produto                                                                                                |
| `fees`               | array   | Linhas de taxas                                                                                                          |
| `shipping`           | array   | Linhas de frete                                                                                                          |
| `discounts`          | array   | Linhas de cupom/desconto                                                                                                 |
| `totals`             | object  | Totais do pedido, totais de pagamento, resumo de reembolso e contagem de itens                                           |
| `tax`                | object  | Flags de modo de exibição de imposto para controle de seções                                                             |
| `tax_summary`        | array   | Linhas de resumo de imposto por alíquota                                                                                 |
| `has_tax_summary`    | boolean | Guard de conveniência para `tax_summary`                                                                                 |
| `payments`           | array   | Linhas de pagamento                                                                                                      |
| `refunds`            | array   | Registros de reembolso aplicados ao pedido                                                                               |
| `fiscal`             | object  | Campos de snapshot fiscal preenchidos por integrações fiscais                                                            |
| `presentation_hints` | object  | Dicas de formatação e renderização                                                                                       |
| `i18n`               | object  | Rótulos traduzidos para templates inclusos e personalizados                                                              |

## Referência de campos[​](#field-reference "Link direto para Referência de campos")

A referência completa de campos está agrupada por seção abaixo. Tudo está recolhido por padrão — expanda o grupo de que você precisa.

order — identificação, status, datas

### order[​](#order "Link direto para order")

| Campo                 | Tipo        | Exemplo / descrição                                                      |
| --------------------- | ----------- | ------------------------------------------------------------------------ |
| `order.id`            | number      | `1234`                                                                   |
| `order.number`        | string      | Número do pedido exibido ao cliente, ex.: `"10045"`                      |
| `order.currency`      | string      | Código de moeda ISO, ex.: `"USD"`                                        |
| `order.customer_note` | string      | Nota do cliente/pedido                                                   |
| `order.wc_status`     | string      | Slug bruto do status do WooCommerce, ex.: `"processing"`                 |
| `order.status_label`  | string      | Rótulo de status localizado, incluindo status personalizados             |
| `order.created_via`   | string      | Origem/canal, ex.: `"woocommerce-pos"`                                   |
| `order.needs_payment` | boolean     | Se a 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 de pagamento, strings vazias quando não pago                        |
| `order.completed`     | date object | Data de conclusão, strings vazias quando incompleto                      |
| `order.printed`       | date object | Carimbo de data/hora de impressão/reimpressão no momento da renderização |

store — identificação, endereço, contato, horários

### store[​](#store "Link direto para store")

| Campo                           | Tipo        | Exemplo / descrição                                                                           |
| ------------------------------- | ----------- | --------------------------------------------------------------------------------------------- |
| `store.id`                      | number      | ID da loja, ou ID histórico para 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      | Complemento                                                                                   |
| `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; recomendado para a maioria dos templates                   |
| `store.tax_ids`                 | array       | IDs fiscais estruturados da empresa; itere sobre este array em vez de usar um único ID 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 de horário de funcionamento                                                    |
| `store.opening_hours_vertical`  | string/null | Bloco de horário de funcionamento em múltiplas linhas                                         |
| `store.opening_hours_inline`    | string/null | Texto de horário de funcionamento separado por vírgulas                                       |
| `store.opening_hours_notes`     | string/null | Observações de horário de funcionamento em texto livre                                        |
| `store.personal_notes`          | string/null | Nota pessoal/rodapé do recibo                                                                 |
| `store.policies_and_conditions` | string/null | Texto de reembolso, devoluções ou termos                                                      |
| `store.footer_imprint`          | string/null | Dados legais do rodapé                                                                        |

### Objetos de identificação fiscal[​](#tax-id-objects "Link direto para 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 ser impresso                                            |
| `country` | string/null | Código ISO do país, quando disponível                                                   |
| `label`   | string/null | Rótulo de exibição localizado, resolvido antes da renderização                          |

Exemplo:

```
{{#store.tax_ids}}

  {{label}}: {{value}}

{{/store.tax_ids}}
```

cashier — usuário que processou o pedido

### cashier[​](#cashier "Link direto para cashier")

| Campo          | Tipo   | Exemplo / descrição                              |
| -------------- | ------ | ------------------------------------------------ |
| `cashier.id`   | number | ID de usuário WordPress, `0` quando desconhecido |
| `cashier.name` | string | Nome de exibição do operador de caixa            |

customer — nome, endereços, IDs fiscais

### customer[​](#customer "Link direto para 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 de endereço de cobrança do WooCommerce       |
| `customer.shipping_address.*` | object      | Campos de endereço de entrega do WooCommerce        |
| `customer.tax_ids`            | array       | IDs fiscais do cliente capturados do pedido         |

As chaves de endereço comuns incluem `first_name`, `last_name`, `company`, `address_1`, `address_2`, `city`, `state`, `postcode`, `country`, `email` e `phone`.

lines — itens de linha do produto

### lines[​](#lines "Link direto para lines")

Itere com `{{#lines}}...{{/lines}}`.

| Campo                               | Tipo   | Descrição                                               |
| ----------------------------------- | ------ | ------------------------------------------------------- |
| `key`                               | string | Chave estável da linha / ID do item do pedido           |
| `sku`                               | string | SKU do produto                                          |
| `name`                              | string | Nome de exibição do produto ou da linha                 |
| `qty`                               | number | Quantidade vendida                                      |
| `qty_refunded`                      | number | Quantidade reembolsada para esta linha                  |
| `unit_subtotal` / `_incl` / `_excl` | number | Preço unitário antes do desconto                        |
| `unit_price` / `_incl` / `_excl`    | number | Preço unitário após o desconto                          |
| `line_subtotal` / `_incl` / `_excl` | number | Subtotal da linha antes do desconto                     |
| `discounts` / `_incl` / `_excl`     | number | Valor do desconto como valor positivo                   |
| `line_total` / `_incl` / `_excl`    | number | Total final da linha                                    |
| `total_refunded`                    | number | Total reembolsado para esta linha como valor positivo   |
| `taxes`                             | array  | Linhas de imposto por alíquota para esta linha          |
| `meta`                              | array  | Metadados do item do pedido como pares `{key, value}`   |
| `attributes`                        | array  | Atributos do produto/variação como pares `{key, value}` |

As variantes formatadas incluem `unit_subtotal_display`, `unit_price_display`, `line_subtotal_display`, `discounts_display`, `line_total_display` e variantes `_display` inclusivas/exclusivas.

fees e shipping

### fees e shipping[​](#fees-and-shipping "Link direto para fees e shipping")

Itere com `{{#fees}}...{{/fees}}` e `{{#shipping}}...{{/shipping}}`.

| Campo                       | Tipo   | Descrição                                                           |
| --------------------------- | ------ | ------------------------------------------------------------------- |
| `label`                     | string | Rótulo da taxa ou nome do método de envio                           |
| `method_id`                 | string | ID do método de envio (somente envio)                               |
| `total` / `_incl` / `_excl` | number | Totais para exibição, com impostos inclusos e com impostos exclusos |
| `taxes`                     | array  | Linhas de imposto por alíquota                                      |
| `meta`                      | array  | Pares de metadados `{key, value}`                                   |

Variantes formatadas: `total_display`, `total_incl_display` e `total_excl_display`.

discounts — linhas de cupom/desconto

### discounts[​](#discounts "Link direto para discounts")

Itere com `{{#discounts}}...{{/discounts}}`.

| Campo                       | Tipo   | Descrição                                          |
| --------------------------- | ------ | -------------------------------------------------- |
| `label`                     | string | Descrição do cupom ou código como fallback         |
| `code`                      | string | Código do cupom                                    |
| `codes`                     | string | Fallback legado/exibição para códigos concatenados |
| `total` / `_incl` / `_excl` | number | Valor do desconto como valor positivo              |

Variantes formatadas: `total_display`, `total_incl_display` e `total_excl_display`. Adicione seu próprio sinal de menos no template se quiser que os descontos sejam exibidos como linhas negativas.

totals — totais do pedido, pagamento, reembolso e itens

### totals[​](#totals "Link direto para totals")

| Campo                                       | Tipo   | Descrição                                        |
| ------------------------------------------- | ------ | ------------------------------------------------ |
| `totals.subtotal` / `_incl` / `_excl`       | number | Subtotal do pedido antes dos descontos           |
| `totals.discount_total` / `_incl` / `_excl` | number | Total de descontos do pedido como valor positivo |
| `totals.tax_total`                          | number | Valor total de impostos                          |
| `totals.total` / `_incl` / `_excl`          | number | Total geral do pedido                            |
| `totals.paid_total`                         | number | Valor pago/aplicado                              |
| `totals.change_total`                       | number | Troco devolvido ao cliente                       |
| `totals.refund_total`                       | number | Total reembolsado como valor positivo            |
| `totals.net_total`                          | number | `total - refund_total`, limitado a zero          |
| `totals.total_qty`                          | number | Soma das quantidades dos itens                   |
| `totals.line_count`                         | number | Contagem de linhas de produto                    |

As variantes formatadas incluem `subtotal_display`, `discount_total_display`, `tax_total_display`, `total_display`, `paid_total_display`, `change_total_display`, `refund_total_display` e `net_total_display`, além de variantes inclusivas/exclusivas quando aplicável.

tax e tax\_summary — controles de exibição e linhas por alíquota

### tax e tax\_summary[​](#tax-and-tax_summary "Link direto para 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 imposto incluso |
| `tax.display_excl`       | boolean | Verdadeiro quando os preços são exibidos sem imposto         |
| `tax.breakdown`          | string  | `hidden`, `single` ou `itemized`                             |
| `tax.breakdown_hidden`   | boolean | Verdadeiro quando as linhas de imposto devem ser ocultadas   |
| `tax.breakdown_single`   | boolean | Verdadeiro quando um total único de imposto é preferido      |
| `tax.breakdown_itemized` | boolean | Verdadeiro quando linhas por alíquota são preferidas         |
| `has_tax_summary`        | boolean | Verdadeiro quando `tax_summary` contém linhas                |

Itere `tax_summary` com `{{#tax_summary}}...{{/tax_summary}}`.

| Campo                 | Tipo        | Descrição                               |
| --------------------- | ----------- | --------------------------------------- |
| `code`                | string      | ID/código da alíquota de imposto        |
| `rate`                | number/null | Percentual da alíquota quando resolvido |
| `label`               | string      | Rótulo da alíquota de imposto           |
| `compound`            | boolean     | Se a alíquota é composta                |
| `taxable_amount_excl` | number/null | Base tributável excluindo imposto       |
| `tax_amount`          | number      | Imposto cobrado                         |
| `taxable_amount_incl` | number/null | Base tributável incluindo imposto       |

Variantes formatadas: `taxable_amount_excl_display`, `tax_amount_display` e `taxable_amount_incl_display`.

payments — linhas de pagamento

### payments[​](#payments "Link direto para payments")

Itere com `{{#payments}}...{{/payments}}`.

| Campo            | Tipo   | Descrição                                   |
| ---------------- | ------ | ------------------------------------------- |
| `method_id`      | string | Identificador do método de pagamento        |
| `method_title`   | string | Título de exibição do método de pagamento   |
| `amount`         | number | Valor aplicado ao pedido                    |
| `transaction_id` | string | ID da transação do gateway                  |
| `tendered`       | number | Valor em dinheiro entregue, quando presente |
| `change`         | number | Troco devolvido, quando presente            |

Variantes formatadas: `amount_display`, `tendered_display` e `change_display`.

refunds — registros de reembolso

### refunds[​](#refunds "Link direto para refunds")

Itere com `{{#refunds}}...{{/refunds}}`. Os valores de reembolso são magnitudes positivas; os templates decidem se devem adicionar 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 da linha reembolsada                      |
| `tax_total`        | number      | Imposto reembolsado                                |
| `shipping_total`   | number      | Valor de frete reembolsado                         |
| `shipping_tax`     | number      | Imposto de frete 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 utilizado para o reembolso           |
| `gateway_title`    | string      | Título de exibição do gateway                      |
| `processing_mode`  | string      | Modo de processamento do provedor/manual           |
| `lines`            | array       | Linhas de produtos reembolsados                    |
| `fees`             | array       | Linhas de taxas reembolsadas                       |
| `shipping`         | array       | Linhas de frete reembolsadas                       |

Os campos de linha de reembolso incluem `name`, `sku`, `qty`, `total`, `total_incl`, `total_excl`, `line_total`, `unit_total` e `taxes`. As linhas de taxas e frete de reembolso utilizam `label`, `total`, `total_incl`, `total_excl` e `taxes`. Variantes de exibição são adicionadas para totais e valores de impostos.

fiscal — snapshot de integração fiscal

### fiscal[​](#fiscal "Link direto para fiscal")

Os campos fiscais são vazios por padrão e preenchidos por integrações fiscais ou pelo enriquecimento de snapshot 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 de sequência                     |
| `fiscal.hash`              | string       | Valor de hash/assinatura                  |
| `fiscal.qr_payload`        | string       | Payload QR para verificação fiscal        |
| `fiscal.tax_agency_code`   | string       | Código da autoridade fiscal               |
| `fiscal.signed_at`         | string       | Carimbo de data/hora da assinatura fiscal |
| `fiscal.signature_excerpt` | string       | Assinatura truncada para exibição         |
| `fiscal.document_label`    | string       | Rótulo do documento, ex.: Nota Fiscal     |
| `fiscal.is_reprint`        | boolean      | Se esta renderização é uma reimpressão    |
| `fiscal.reprint_count`     | number       | Contagem 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[​](#presentation_hints "Link direto para presentation_hints")

Esses campos são consumidos principalmente pelo renderizador e formatador. Eles estão disponíveis para os templates 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 utilizada para 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ço do WooCommerce                  |
| `presentation_hints.order_barcode_type`       | string  | Tipo de código de barras utilizado pelos modelos de galeria |

i18n — rótulos traduzidos

### i18n[​](#i18n "Link direto para i18n")

Utilize rótulos `i18n` em vez de codificar 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`, `discount`, `subtotal`, `total`, `tax`, `paid`, `tendered`, `change`, `tax_summary`, `refunded`, `net_total`, `customer_note`, `thank_you_purchase`, `opening_hours`, e as chaves de rótulo de ID fiscal como `store_tax_id_label_eu_vat` e `customer_tax_id_label_other`. Chaves adicionais podem ser incluídas por extensões.