Criação de ordens

3.1.3. Criação de ordens#

Esta página contém toda a documentação do vídeo tutorial que explica a criação de uma encomenda simples através da API e a verificação do seu estado.

3.1.3.1. Vídeo#

3.1.3.2. Requisitos#

Necessário para esta série de tutoriais:

  • Um backend de comerciante Taler
    Se precisar de ajuda para utilizar o backend do comerciante pela primeira vez, pode ver o Taler merchant introduction tutorial.
  • Uma instância da carteira Taler
    As instruções de configuração estão disponíveis em https://wallet.taler.net.
  • Um software de gestão de API REST ou competências de programação relevantes
    Nesta série de vídeos, vamos utilizar o software gratuito Insomnia, disponível para transferência em https://insomnia.rest.

3.1.3.3. Aviso de demonstração do backend#

Para este tutorial, pode utilizar o seu próprio serviço de backend de comerciante ou o serviço de demonstração online em https://backend.demo.taler.net/instances/sandbox/.

3.1.3.4. Mais notas sobre o processamento de pagamentos por comerciantes#

  1. Criar uma ordem para um pagamento

Os pagamentos em Taler giram em torno de uma ordem, que é uma descrição legível por máquina da transação comercial para a qual o pagamento deve ser efectuado. Antes de aceitar um pagamento Taler como comerciante, é necessário criar uma tal ordem.

Isto é feito através do POST de um objeto JSON para o endpoint da API /private/orders do backend. Pelo menos os seguintes campos devem ser fornecidos dentro do campo order:

  • mont: O montante a ser pago, como uma cadeia de caracteres no formato CURRENCY:DECIMAL_VALUE, por exemplo EUR:10 para 10 Euros ou KUDOS:1.5 para 1.5 KUDOS.

  • summary: Um resumo legível por humanos sobre o que é o pagamento. O resumo deve ser suficientemente curto para caber nos títulos, embora não seja imposto um limite rígido.

  • fulfillment_url: Um URL que será exibido quando o pagamento for concluído. Para produtos digitais, deve ser uma página que mostre o produto que foi comprado. Num pagamento bem sucedido, a carteira anexa automaticamente o order_id como parâmetro de consulta, bem como o session_sig para pagamentos vinculados à sessão (discutido abaixo).

As encomendas podem ter muitos mais campos, ver O formato de encomenda do Taler. Quando se faz o POST de uma encomenda, também se pode especificar detalhes adicionais, tais como uma substituição da duração do reembolso e instruções para a gestão do inventário. Estes são raramente necessários e não são cobertos neste tutorial; por favor, veja o manual de referência para detalhes.

Um fragmento mínimo de Python para criar uma encomenda teria o seguinte aspeto:

>>> import requests
>>> body = dict(order=dict(amount="KUDOS:10",
...                        summary="Donation",
...                        fulfillment_url="https://example.com/thanks.html"),
...             create_token=False)
>>> response = requests.post("https://backend.demo.taler.net/instances/sandbox/private/orders",
...               json=body,
...               headers={"Authorization": "Bearer secret-token:sandbox"})
<Response [200]>

O backend preenche alguns dados que faltam na encomenda, como o endereço da instância do vendedor. Os dados completos são designados por condições do contrato.

Nota

A solicitação acima desativa o uso de tokens de declaração definindo a opção create_token como false. Se você precisar de tokens de declaração, deverá ajustar o código para construir o URI taler://pay/ fornecido abaixo para incluir o token de declaração.

Depois de fazer um POST com sucesso para /private/orders, será retornado um JSON com apenas um campo order_id com uma string representando o ID do pedido. Se também receber um token de reivindicação, verifique novamente se utilizou o pedido conforme descrito acima.

Juntamente com a instância do comerciante, o ID da encomenda identifica de forma única a encomenda num backend do comerciante. Utilizando o ID da encomenda, pode construir trivialmente o respetivo URI taler://pay/ que deve ser fornecido à carteira. Deixe example.com ser o nome de domínio onde os endpoints públicos da instância são acessíveis. O URI de pagamento do Taler é então simplesmente taler://pay/example.com/$ORDER_ID/ onde $ORDER_ID deve ser substituído pelo ID da ordem que foi devolvida.

Pode colocar o URI taler:// como alvo de uma ligação para abrir a carteira Taler através do esquema taler://, ou colocá-lo num código QR. No entanto, para uma loja Web, a forma mais fácil é simplesmente redirecionar o browser para https://example.com/orders/$ORDER_ID. Essa página irá então ativar a carteira Taler. Aqui o backend gera a lógica correta para ativar a carteira, suportando os vários tipos de carteiras Taler existentes. Em vez de construir o URL acima manualmente, também é possível obtê-lo verificando o estado do pagamento, como descrito na próxima secção.

Ao construir manualmente este URL, certifique-se de que fornece o token de reivindicação (a menos que tenha sido desativado) e se o backend estiver a funcionar sem TLS para utilizar taler+http:// (note que este último só é suportado por carteiras a funcionar em modo de depuração).

Nota

Uma forma trivial de obter o payment_redirect_url correto é verificar o estado do pagamento (ver abaixo). Assim, se ainda não tiver a certeza de como o construir, pode simplesmente pedir ao backend que o faça por si. No entanto, em produção, provavelmente deve construí-lo manualmente e evitar o pedido extra ao backend.

  1. Verificação do estado do pagamento e solicitação de pagamento

Dado o ID da encomenda, o estado de um pagamento pode ser verificado com o endpoint /private/orders/$ORDER_ID. Se o pagamento ainda não tiver sido concluído pelo cliente, /private/orders/$ORDER_ID fornecerá ao frontend um URL (com o nome payment_redirect_url) que accionará a carteira do cliente para executar o pagamento. Este é basicamente o URL https://example.com/orders/$ORDER_ID que discutimos acima.

>>> import requests
>>> r = requests.get("https://backend.demo.taler.net/instances/sandbox/private/orders/" + order_id,
...                  headers={"Authorization": "Bearer secret-token:sandbox"})
>>> print(r.json())

Se o campo status_da_encomenda na resposta for pago, não receberá um payment_redirect_url mas sim informações sobre o estado do pagamento, incluindo:

  • contract_terms: As condições contratuais completas da encomenda.

  • refunded: true se foi concedido um reembolso (possivelmente parcial) para esta compra.

  • refunded_amount: Montante que foi reembolsado

Depois de o frontend ter confirmado que o pagamento foi bem sucedido, é normalmente necessário acionar a lógica comercial para que o comerciante cumpra as suas obrigações ao abrigo do contrato.

Nota

Não é necessário continuar a consultar para notar alterações no estado da transação da encomenda. Os endpoints suportam polling longo, basta especificar um parâmetro de consulta timeout_ms com o tempo que pretende esperar no máximo para que o estado da encomenda mude para paid.

3.1.3.5. Mais tutoriais#

Para ver tutoriais adicionais, pode navegar neste site ou ir a https://docs.taler.net para obter a documentação mais recente sobre os serviços Taler.