Panorama concetual

3.1.1. Panorama concetual#

3.1.1.1. Sobre este tutorial#

Este tutorial aborda como processar pagamentos usando o Backend do comerciante GNU Taler. O público deste tutorial são desenvolvedores de comerciantes (como lojas virtuais) que estão trabalhando na integração do GNU Taler com o Frontend voltado para o cliente e o Backoffice voltado para o pessoal.

Este capítulo explica alguns conceitos básicos. No segundo capítulo, aprenderá a efetuar pagamentos básicos.

Esta versão do tutorial tem exemplos para Python3. Ela usa a biblioteca requests para requisições HTTP. Versões para outras linguagens/ambientes também estão disponíveis.

Se quiser ver alguns exemplos simples e correntes, veja estes:

3.1.1.2. Descrição geral da arquitetura#

A pilha de software Taler para um comerciante consiste nos seguintes componentes principais:

  • Um frontend que interage com o browser do cliente. O frontend permite ao cliente criar um carrinho de compras e efetuar uma encomenda. Após o pagamento, acciona a respectiva lógica comercial para satisfazer a encomenda. Este componente não está incluído no Taler, mas assume-se que existe no comerciante. Este tutorial descreve como desenvolver um frontend do Taler.

  • Um backend de pagamento específico do Taler que facilita o frontend para processar transacções financeiras com o Taler. Para este tutorial, irá utilizar um backend de sandbox público. Para utilização em produção, tem de configurar o seu próprio backend ou pedir a outra pessoa que o faça por si.

A imagem seguinte ilustra as várias interações destes componentes-chave:

../../_images/arch-api.png

O backend fornece o suporte ao protocolo criptográfico, armazena informações financeiras específicas do Taler e se comunica com a troca GNU Taler pela Internet. O frontend acede ao backend através de uma API RESTful. Como resultado, o frontend nunca tem de comunicar diretamente com a bolsa, e também não lida com dados sensíveis. Em particular, as chaves de assinatura do comerciante e as informações da conta bancária são encapsuladas no backend do Taler.

Algumas funcionalidades do backend (a «interface pública») são expostas diretamente ao browser do cliente. Na API HTTP, todos os endpoints privados (para o Backoffice) são prefixados com /private/. Este tutorial centra-se nos endpoints /private/. A interface pública é utilizada diretamente pela carteira e não é relevante para o comerciante (para além de que a API deve ser exposta).

3.1.1.3. Backend e autenticação de sandbox pública#

A forma como o frontend se autentica no backend do Taler depende da configuração. Veja Manual do Operador do Backend do Comerciante.

O backend público de sandbox https://backend.demo.taler.net/instances/sandbox/ utiliza uma chave API no cabeçalho Authorization. O valor deste cabeçalho deve ser Bearer secret-token:sandbox para o backend público sandbox.

>>> import requests
>>> requests.get("https://backend.demo.taler.net/instances/sandbox/private/orders",
...              headers={"Authorization": "Bearer secret-token:sandbox"})
<Response [200]>

Se for devolvido um código de estado HTTP diferente de 200, algo correu mal. Deve descobrir qual é o problema antes de continuar com este tutorial.

O backend do sandbox https://backend.demo.taler.net/instances/sandbox/ usa KUDOS como uma moeda imaginária. Moedas denominadas em KUDOS podem ser retiradas de https://bank.demo.taler.net/.

3.1.1.4. Instâncias de comerciante#

Um único servidor backend de comerciante Taler pode ser utilizado por vários comerciantes que são entidades comerciais separadas. A cada uma destas entidades comerciais separadas é atribuída uma instância de comerciante que é identificada por um identificador de instância alfanumérico. Se a instância for omitida, é assumida a id de instância admin.

As seguintes instâncias de comerciante estão configuradas em https://backend.demo.taler.net/:

Nota

Estes são comerciantes fictícios utilizados para os nossos demonstradores e não são afiliados ou oficialmente aprovados pelos respectivos projectos.

Todos os endpoints das instâncias oferecem a mesma API. Assim, a instância a utilizar é simplesmente incluída no URL de base do backend do comerciante.

3.1.1.5. Tutoriais em vídeo#

Esta página contém toda a documentação do tutorial em vídeo que apresenta a API comercial do Taler.

3.1.1.5.1. Vídeo#

3.1.1.5.2. Requisitos#

Necessário para esta série de tutoriais:

  • Um backend de comerciante Taler
    Para maior comodidade, recomendamos a utilização do endereço https://backend.demo.taler.net/instances/sandbox/.
  • Uma instância da carteira Taler
    As instruções de configuração estão disponíveis em https://wallet.taler.net, embora não sejam necessárias para este tutorial.
  • 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.
    Como introdução, este vídeo mostra como exportar código de trabalho das suas consultas preparadas na Insomnia em Python (ou em qualquer linguagem suportada) e executá-las, mas isto não será demonstrado novamente nos próximos tutoriais.

3.1.1.5.3. Aviso de demonstração do backend#

Recomenda-se vivamente a utilização do serviço de demonstração do comerciante Taler em linha https://backend.demo.taler.net/instances/sandbox/ para este tutorial.

A chave de acesso é: sandbox.

3.1.1.5.4. Informações sobre a ficha secreta#

O token secreto está em conformidade com o documento RFC 8959. Você pode aprender mais sobre ele aqui: https://datatracker.ietf.org/doc/html/rfc8959. Não se esqueça de que este é um token Bearer e que o seu cabeçalho de autenticação precisa de o especificar.

O cabeçalho de autorização deve ter o seguinte aspeto:
Autorização: Bearer secret-token:<chave de acesso>

3.1.1.5.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.