O formato de encomenda do Taler

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 "CURRENCY:DECIMAL_VALUE".

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

montante

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

max_fee

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.

max_wire_fee

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.

wire_fee_amortization

Em quantas transações de clientes o comerciante espera amortizar as taxas de transferência, em média? Se a taxa de transferência do Exchange for superior a max_wire_fee, a diferença é dividida por este número para calcular a contribuição esperada do cliente para a taxa de transferência. A contribuição do cliente pode ainda ser reduzida pela diferença entre a max_fee e a soma das taxas de depósito efetivas. 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 até à qual o comerciante pretende que o Exchange transfira definitivamente o dinheiro devido por este contrato. Uma vez expirado este prazo, o Exchange agregará todos os depósitos cujos contratos tenham ultrapassado o refund_deadline e efetuará 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á efetuado o pagamento.

refund_deadline

Prazo até ao qual o comerciante está disposto (e pode) a reembolsar o contrato usando o Taler. Note-se que o Exchange Taler mantém o pagamento em custódia pelo menos até este prazo. Até esta data, o comerciante 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 quantity unidades deste produto enviadas para o delivery_location 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.

product_id

ID único do produto no catálogo do comerciante. Pode ser escolhido livremente, uma vez que só tem significado para o comerciante, mas deve ser um número no intervalo

.

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.

delivery_date

Hora em que o produto deve ser entregue no delivery_location.

delivery_location

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 locations, 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 locations, 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.

zip_code

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.

street_number

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.