API

Jasmin provides a Web REST API that allows you to access a subscription's data. This API covers all of the product's modules (Sales, Purchases, Taxes, etc.) and allows you to view data as well as create and update entities and transactions (documents), which makes it possible to create solutions that integrate Jasmin with any other system.

See more

O sistema de autenticação de utilizadores e de segurança dos produtos requer que todas as aplicações integradas sejam registadas no sistema. Essa informação é utilizada no acesso à Web API para assegurar o acesso aos dados da subscrição de um determinado cliente.O registo da aplicação permite ao programador ter acesso ao token de autorização que deve ser utilizado em todas as chamadas à Web API

A Web API utiliza o standard OAuth 2.0 para autorizar o acesso às subscrições e por consequência aos dados. Encontra-se disponível uma área que permite gerir o registo das suas aplicações de integração para programadores de aplicações de integração.

Para mais informações sobre o OAuth 2.0, sugere-se a consulta dos seguintes artigos:

• Como funciona a autorização OAuth 2.0?
• Quais os fluxos de autorização suportados na Web API?

Registo de aplicações

O registo de aplicações encontra-se disponível na App Store que se encontra dividida em três áreas:

• App Store;
• Developer;
• Subscription Apps.

Área do Developer

Esta área está dividida em duas subáreas: Dashboard e Publisher .

Publisher

Nesta subárea é apresentada a lista de publishers associada à conta de utilizador, sendo permitido adicionar e remover publishers.

Para adicionar um novo publisher basta clicar no Create Publisher na área Publisher e indicar os seguintes dados:

• Key: identificador do publisher;
• Name: o nome público do publisher;
• Description: descrição do publisher.

Dashboard

Nesta subárea é permitido consultar, editar, publicar ou remover aplicações, bem como criar ou remover subscrições para testes.

1) Adicionar nova aplicação

Para adicionar uma nova aplicação, siga os seguintes passos:

1. Clicar no Creat App na área Dashboard;
2. Inserir os seguintes dados sobre a aplicação:
   - Product: nome do produto;
   - Key: identificador da aplicação (chave/clienteId que será usada nas aplicações integradoras);
   - Name: o nome público da aplicação;
   - Description: descrição da aplicação;
3. Depois de confirmar, é redirecionado para a página de configuração da aplicação onde terá que preencher todos os dados necessários.

Esta página de configuração está dividida em seis áreas, sendo necessário preencher as seguintes informações:

General:

Deverá preencher os seguintes campos:

• Product: nome do produto;
• Version: versão da aplicação;
• Name: nome público da aplicação;
• Key: identificador da aplicação;
• Publisher Key: identificador do publisher;
• Home Page: o endereço Web da aplicação (para efeitos informativos);
• Description: descrição da aplicação.

Logo & Images:

Nesta área deverá indicar o logótipo da aplicação para efeitos informativos.

Autorization

Deverá inserir os seguintes dados:

• OAuthFlow: fluxo de autenticação que pode ser de 4 tipos - Implicit, Hybrid, Client Credencials e Authorization Code;
• Redirect URI: o endereço da página que será utilizada na autorização (ver documentação sobre autorização).

Ao selecionar os tipos de fluxo Client Credentials ou AuthorizationCode, deverá gerar um Client Secret no botão disponível para o efeito, sendo necessário gravar a aplicação após alteração do fluxo.  Para obter o token que autoriza as chamadas à API é necessário possuir a chave da aplicação e o secret. Não é possível recuperar esta informação, por isso deverá guardá-la de forma segura. Contudo, é possível gerar um novo Client Secret através da opção Reset Client Secret.

Additional Settings

Deverá preencher os seguintes dados:

• App Store Preview Link: o link do preview da aplicação na store. Pode ser utilizado para subscrever a aplicação sem efetuar a publicação da mesma;
• Notifications Endpoint: o endpoint para o envio de notificações para a aplicação;
• External Subscription Url: a Url externa de redireccionamento para a aplicação.

Distribution

Após preencher todos os requisitos necessários, é possível submeter a aplicação para aprovação através da opção Submit for approval. Será também apresentado o estado em que se encontra a aprovação da aplicação.

Delete App

Poderá remover a aplicação da App Directory através da opção Delete App.

2) Editar o registo de uma aplicação

É possível editar as aplicações depois de as criar, exceto os campos:

• Product;
• Name;
• Key.

Poderá também efetuar o publish ou unpublish de aplicações, bem como solicitar a geração de novo Client Secret (esta opção apenas se encontra disponível para aplicações com os tipos de autenticação Client Credentials ou AuthorizationCode).

3) Efetuar publish/unpublish de uma aplicação

Ao efetuar o publish, está a permitir que a aplicação fique visível na App Store do Jasmin e, assim, qualquer utilizador pode subscrevê-la e utilizá-la nas suas subscrições. Por outro lado, ao efetuar o unpublish, esta deixa de estar visível na App Store. No entanto, independentemente do unpublish, as aplicações podem continuar a ser utilizadas nas subscrições que a tenham associado previamente.

Nota: Estas funcionalidades apenas se encontram disponíveis na edição de uma aplicação e na listagem de aplicações, no botão associado.

4) Subscrever uma aplicação sem a publicar

Poderá utilizar ou partilhar o link de preview para visualizar o aspeto da aplicação na store, bem como para efetuar a subscrição da app para efeitos de teste ou para a manter como privada.

5) Criar uma nova subscrição para efeitos de desenvolvimento

Para que o desenvolvimento de uma aplicação integrada não interfira com as contas reais dos clientes, é possível criar uma subscrição de desenvolvimento que poderá utilizar para este efeito.

Em termos funcionais e de dados iniciais, este tipo de subscrição é idêntica a uma subscrição DEMO. Este tipo de subscrição permite experimentar livremente o produto durante 30 dias com dados fictícios.

Se uma subscrição de desenvolvimento expirar, o developer poderá sempre criar uma nova, sendo que perderá todos os dados inseridos na subscrição anterior. De referir que só poderá criar três subscrições.

6) Remover subscrição

Ao remover uma subscrição, esta deixa imediatamente de estar disponível na área de Manager.

Subscribed Apps

1) Associar uma aplicação a uma subscrição

Ao associar uma aplicação a uma subscrição está a permitir que esta seja utilizada na subscrição.

Para associar a sua aplicação, siga os seguintes passos:

1. Selecionar a aplicação da lista de aplicações disponíveis;
2. Selecionar a opção Subscribe e, posteriormente, a subscrição pretendida;
3. Clicar em Confirmar.

2) Remover uma aplicação de uma subscrição

Ao remover uma aplicação de uma subscrição, deixa de ser possível utilizar a aplicação nessa subscrição.

O ProgrammableWeb é uma plataforma que permite acompanhar todas as novidades e informações sobre a Web API do Jasmin.

Ver mais