3.1.6. O formato de encomenda do Taler#

O formato de pedido do Taler descreve o JSON que deve ser POSTADO no backend do comerciante para criar um pedido. É o protótipo a partir do qual o backend do comerciante criará os «termos do contrato» reais <https://docs.taler.net/core/api-merchant.html#the-contract-terms>`__.

Existem diferentes versões para o formato da ordem; são descritas em pormenor no Manual de referência.

Nota

Os montantes financeiros são sempre especificados como uma cadeia de caracteres no formato "MOEDA:VALOR_DECIMAL".

Esta secção fornece uma visão geral dos campos mais comuns:

montante: Especifica o montante total a ser pago ao comerciante pelo cliente.

taxa_max: Este é o montante total máximo das taxas de depósito que o comerciante está disposto a pagar. Se as taxas de depósito das moedas excederem este montante, o cliente deve incluí-lo no total do pagamento. A taxa é especificada utilizando o mesmo formato utilizado para amount.

taxa_máxima_de_fios: Taxa máxima de transferência aceite pelo comerciante (parte do cliente a ser dividida pelo fator wire_fee_amortization e ainda reduzida se as taxas de depósito forem inferiores a max_fee). Se não existir, a predefinição é zero.

taxa_de_transacção_amortização: Em quantas transações de clientes o comerciante espera amortizar as taxas de transferência, em média? Se a comissão de transferência da bolsa for superior à taxa_máx_de_transferência, a diferença é dividida por este número para calcular a contribuição esperada do cliente para a comissão de transferência. A contribuição do cliente pode ainda ser reduzida pela diferença entre a taxa_max e a soma das taxas de depósito efectivas. Opcional, o valor por defeito se não existir é 1. Os valores zero e negativos são inválidos e também interpretados como 1.

pay_url: Qual URL aceita pagamentos. Este é o URL onde a carteira irá POSTAR moedas.

fulfillment_url: Qual o URL a que a carteira deve aceder para obter o cumprimento, por exemplo, o HTML ou PDF de um artigo que foi comprado, ou um sistema de acompanhamento de encomendas para envios, ou uma simples página Web legível por humanos que indique o estado do contrato.

order_id: Identificador alfanumérico, livremente definido pelo comerciante. Utilizado pelo comerciante para identificar inequivocamente a transação.

resumo: Resumo breve e legível do contrato. A utilizar quando o contrato é apresentado apenas numa linha, por exemplo, no histórico de transacções do cliente.
carimbo de data/hora: Hora em que a oferta foi gerada.

prazo_de_pagamento: Data e hora em que o comerciante pretende que a bolsa transfira definitivamente o dinheiro devido por este contrato. Uma vez expirado este prazo, a bolsa agregará todos os depósitos em que os contratos tenham ultrapassado o refund_deadline e efectuará um único pagamento por transferência bancária. Os montantes serão arredondados para a unidade de transferência; se o montante total for inferior à unidade de transferência, não será efectuado o pagamento.

prazo_de_reembolso: Prazo até o qual o vendedor está disposto (e pode) reembolsar o contrato usando o Taler. Note-se que a bolsa Taler mantém o pagamento em caução pelo menos até este prazo. Até esta data, o vendedor poderá assinar uma mensagem para efetuar um reembolso ao cliente. Após este prazo, não será mais possível reembolsar o cliente. Deve ser menor que o pay_deadline.

produtos

Conjunto de produtos que estão a ser vendidos ao cliente. Cada entrada contém uma tupla com os seguintes valores:

descrição: Descrição do produto.
quantidade: Quantidade dos itens a serem enviados. Pode especificar uma unidade (por exemplo, 1 kg) ou apenas a contagem.
preço: Preço para quantidade de unidades deste produto enviadas para o local_de_entrega indicado. Note-se que, normalmente, a soma de todos os preços deve corresponder ao montante total do contrato, mas pode ser diferente devido a descontos ou porque os preços individuais não estão disponíveis.
produto_id: ID único do produto no catálogo do comerciante. Pode ser escolhido livremente, uma vez que só tem significado para o vendedor, mas deve ser um número no intervalo $[0,2^{51})$ .
impostos: Mapa dos impostos aplicáveis a pagar pelo comerciante. A etiqueta é o nome do imposto, ou seja, IVA, imposto sobre vendas ou imposto sobre o rendimento, e o valor é o montante do imposto aplicável. Note-se que são permitidos rótulos arbitrários, desde que sejam utilizados para identificar o regime fiscal aplicável. Os pormenores podem ser especificados pela entidade reguladora. Esta informação é utilizada para declarar ao cliente quais os impostos que o comerciante pretende pagar e pode ser utilizada pelo cliente como recibo. A informação também é suscetível de ser utilizada em auditorias fiscais ao comerciante.
data_de_entrega: Hora em que o produto deve ser entregue no local_de_entrega.
localização_da_entrega: Isto deve dar uma etiqueta no mapa locations, especificando onde o item deve ser entregue.

Os valores podem ser omitidos se não forem aplicáveis. Por exemplo, se uma compra for sobre um pacote de produtos que não têm preços individuais ou IDs de produtos, o product_id ou o price podem não ser especificados no contrato. Da mesma forma, para produtos virtuais entregues diretamente através do URI de preenchimento, não existe delivery_location.

comerciante

endereço: Isto deve dar uma etiqueta no mapa locais, especificando onde o comerciante está localizado.
nome: Isto deve dar um nome legível para a atividade do comerciante.
jurisdição: Isto deve dar uma etiqueta no mapa locais, especificando a jurisdição sob a qual este contrato deve ser arbitrado.

locais

Mapa associativo das localizações utilizadas no contrato. As etiquetas para as localizações neste mapa podem ser escolhidas livremente e utilizadas sempre que uma localização seja necessária noutras partes do contrato. Desta forma, se o mesmo local for requerido muitas vezes (como o endereço comercial do cliente ou do comerciante), só precisa de ser listado (e transmitido) uma vez e pode ser referido através da etiqueta. Uma lista não exaustiva de atributos de localização é a seguinte:

nome: Nome do destinatário da entrega, quer se trate de uma empresa ou de uma pessoa.
país: Nome do país de entrega, tal como consta de uma encomenda postal, por exemplo, «França».
Estado: Nome do estado para entrega, tal como se encontra num pacote postal, por exemplo, «NY».
região: Nome da região de entrega, tal como consta de uma encomenda postal.
províncias: Nome da província de entrega, tal como consta de uma encomenda postal.
cidade: Nome da cidade de entrega, tal como consta de uma encomenda postal.
código postal: Código postal para entrega, tal como se encontra numa encomenda postal.
rua: Nome da rua para entrega, tal como se encontra num pacote postal.
número_da_rua: Número da rua (número da casa) para entrega, tal como se encontra numa encomenda postal.

Nota

As localizações não são obrigadas a especificar todos estes campos e também podem ter campos adicionais. Os renderizadores de contratos têm de renderizar pelo menos os campos acima indicados e devem renderizar os campos que não entendem como uma lista de valores chave.