JASMIN – Guia Visual – Como integrar com a API

JASMIN – Um Guia Visual em Como integrar com a API passo a passo

Se procura pelos links necessários para a integração que estão “escondidos” pela documentação oficial, poderá consultá-los rapidamente no fundo desta página.

Pré-requisitos mínimos:

• Ter uma conta Jasmin

PARTE 1 – Criação de Contas e Chaves de Autenticação

Antes de se poder aceder à API temos de criar contas, chaves de autenticação e as autorizações necessárias de acesso.

1. Aceder ao “Developer Dashboard” autenticando-se com os dados da sua conta em: https://apps.primaverabss.com/developer/dashboard
   
2. No menu do topo aceder à opção PUBLISHER
   
3. Clicar no botão CRIAR PUBLISHER

4. Preencher os campos, onde:
   • CHAVE – É uma chave identificadora, definida por si
   • NOME – Um nome, definido por si
   • DESCRIÇÃO – Uma descrição, , definida por si
     
5. Voltamos ao “Developer Dashboard” pelo Link ou clicando no menu do topo: https://apps.primaverabss.com/developer/dashboard
   
6. De seguida, clicamos em CRIAR APLICAÇÃO
   

7. Preencher os campos onde:
   • PRODUTO: Escolher das opções: Jasmin
   • CHAVE: Uma chave identificadora, definida por si
   • NOME: Um nome para a aplicação, definido por si
   • DESCRIÇÂO: Uma descrição, definida por si
   • Clicar em CONFIRMAR
     
8. No novo ecrã, em:
   • CHAVE DO PUBLISHER escolher o nome do publisher disponível da lista
   • AUTORIZAÇÃO escolher: CREDENCIAIS DO CLIENTE
   • Clicar em GRAVAR.
     
9. A nova aplicação já deve aparecer listada no painel, como neste exemplo:

10. Vamos clicar em cima do nome da App, para entrar de novo no painel da aplicação para podermos obter as chaves secretas.
11. Ir a AUTORIZAÇÃO e clicar em REPOR CLIENT SECRET. Na pergunta “Tem a certeza?” clique em YES.

12. Um ecrã novo aparece com a CHAVE DA APLICAÇÃO e SECRET DA APLICAÇÃO. Ambos os valores serão para usar mais tarde, guarde-os pois não os poderá consultar aqui.
    Se perder estas chaves, terá de as gerar de novo.
13. Agora, em DEFINIÇÕES ADICIONAIS, clicamos na ligação do link

14. No novo ecrã, clicamos em ADICIONAR.
15. E novamente ADICIONAR na nova caixa.

PARTE 1 – terminada.

PARTE 2 – Testar ligações da API com o POSTMAN

O Postman (https://www.postman.com/) é uma plataforma de API para desenvolvedores projetar, construir, testar e iterar as suas APIs. Esta é a forma mais rápida de conseguir testar o seu acesso à API do Jasmin. Crie uma conta gratuita e instale a versão para Windows ou use a versão on-line.

Depois:

1. Ir ao link: https://developers.primaverabss.com/jasmin/postman/
2. Clique na coleção pretendida para importar para o POSTMAN, o resultado deverá ser idêntico a:

3. A título de exemplo, vamos tentar obter a lista de clientes. Para isso clicamos na coleção SALES & PURCHASES > SALES > CUSTOMERS > SALESCORE – CUSTOMER PARTIES – GET ALL
4. Deverá aparecer um novo separador como:

5. No URL de GET, temos de alterar o URL, ou atribuindo valor às variáveis, ou substituindo os valores. Os identificadores podem ser obtidos, quando acede ao seu Jasmin, identificado no URL os dois parâmetros “account” e “subscription”,  https://my.jasminsoftware.com/api/{account}/{subscription}/
   – ex. – https://my.jasminsoftware.com/00001/00001-0001/
   • {{url}} – https://my.jasminsoftware.com/
   • {{tenant}} – identificador da conta, exemplo: 00001
   • {{organization}} – identificado da subscrição, exemplo: 00001-0001
     
6. Antes de podermos executar o GET, temos de obter o TOKEN de autenticação. Para isso clicamos no separador AUTHORIZATION > TYPE e escolhemos OAUTH 2.0

7. Nas novas opções, preencher os seguintes campos:

• TOKEN NAME: Dar um nome ao Token que vamos receber
• GRANT TYPE: Escolher Client Credentials
• ACCESS TOKEN URL: usar o URL: https://identity.primaverabss.com/connect/token
• CLIENT ID: é o valor obtido na PARTE 1, ponto 12 com o nome CHAVE DA APLICAÇÃO
• CLIENT SECRET: é o valor obtido na PARTE 1, ponto 12 com o nome SECRET DA APLICAÇÃO

8. Para obter o token de autenticação, vamos clicar em GET NEW ACCESS TOKEN
9. Se tudo correu bem, deverá aparecer uma janela com o Token de resposta. Basta clicar em USE TOKEN para que seja preenchido automaticamente no campo ACCESS TOKEN no POSTMAN

10. Se por acaso na autenticação aparecer uma mensagem de erro é porque algo correu mal nos pontos anteriores. Terá de voltar atrás e rever todos os passos.
11. Se tudo correu bem, agora é só carregar em SEND para executar o GET
12. Na secção em baixo, será possível ver a resposta. Neste caso pedimos a listagem de todos os Clientes. Aqui mostrados, registos de exemplo em formato JSON

13. Posteriormente, para usar qualquer um dos endpoints da API, não necessita de requisitar novo token de autenticação, podendo fazer da seguinte forma:

• Clicamos no separador AUTHORIZATION > TYPE e escolhe-se o OAUTH 2.0 novamente.

• Desta vez no separador CURRENT TOKEN, clicamos na lista em ACCESS TOKEN e da lista pendente, escolhemos o último token que obtivemos.

• Se tiver os restantes requisitos do endpoint preparados, basta clicar em SEND.

PARTE 2 – terminada.

LINKS Úteis:

• Developer Dashboard – https://apps.primaverabss.com/developer/dashboard
• Coleções Postman – https://developers.primaverabss.com/jasmin/postman/
• URL Token de Autenticação – https://identity.primaverabss.com/connect/token
• URL com Identificadores – https://my.jasminsoftware.com/api/{account}/{subscription}/

Se achou útil este post, deixe em baixo um comentário.