Introdução
O presente documento tem como objetivo detalhar o uso da API, contendo explicações da autenticação e pedidos comuns, bem como alguns exemplos em cURL, Ruby, Postman, e OpenAPI.
Este documento está estruturado da seguinte forma
- Introdução, OpenAPI e Postman - Breve descrição do documento, exemplos de OpenAPI e Postman de autenticação e pedidos à API
- Autenticação - Explicação do processo de autenticação à API, com vários exemplos. Primeiro passo a realizar para a integração da API
- Como fazer uma fatura - Descrição do processo de emissão de fatura, com exemplos
- Referência da API - Descrição, com exemplos, de pedidos comuns à API
OpenAPI é atualmente o método standard de documentar APIs. Como tal, temos disponível no seguinte link, a documentação da referenciada API, em OpenAPI. Link para visualizar e descarregar OpenAPI: https://app.swaggerhub.com/apis/cloudware-deploy/CWApi/1.0.
Postman é uma ferramenta poderosa de realização de pedidos a APIs, incluindo a componente de autenticação. De seguida está o ficheiro que deverá importar para o Postman, que lhe disponibiliza todos os pedidos que desejar fazer.
De modo a utilizar o Postman, siga os passos descritos de seguida
No menu superior, na página inicial , colocar o rato sobre o menu "Empresa", e selecionar "Dados da API". Este menu Empresa > Configurações > Dados da API encontra-se disponível para o user Empresário.
Depois de entrar no menu "Dados da API", será necessário consultar o identificador (futuramente referido como client_id), e segredo (client_secret). Neste menu, o endereço URI de redirect deverá ser alterado para https://oauth.pstmn.io/v1/callback.
Depois de instalado o software Postman, disponível em https://www.postman.com/downloads/, este deverá ser aberto.
Confrontado com a página inicial, deverá selecionar a opção "Importar"
Com este ficheiro importado, deverá ter uma nova coleção aberta, com os possíveis pedidos à API disponibilizados
Antes de realizar qualquer pedido, é necesário configurar a autenticação. Para o efeito, deve clicar em Open API
De seguida, deve clicar em "varáveis"
A partir deste ponto, algumas informações têm de ser atualizadas. Utilizando as informações obtidas no primeiro passo (Alterar e consultar dados da API), deve alterar o valor atual dos campos clientid e clientsecret para os dados identificador e segredo, respetivamente, consultados na página de dados da API. O redirecturi vem já com o valor correto, e deverá estar de acordo com o valor colocado nos dados da api, alterado anteriormente. O base_url deverá ser https://appX.toconline.pt, e o base_url_oauth deverá ser https://appX.toconline.pt/oauth/auth, sendo que X será o valor que pode ver nos seus dados da api, ou no link que utiliza para aceder ao nosso software.
De seguida, deve clicar em "autenticação"
Daqui, deverá colocar todos os campos como mostrado na imagem, ir ao final da página e clicar em "Gerar novo token de acesso"
Para finalizar, voltar ao início da página, e selecionar o token gerado
A partir deste ponto, todos os passos estão concluidos para a experimentação com a API. De modo a enviar um pedido à API, deve selecionar o pedido que quer enviar, na barra lateral esquerda
Aberto o pedido, pode editar os parâmetros que deseja enviar, e enviar o pedido utilizando o botão "enviar". A resposta do pedido irá surgir na caixa "Resposta"
Last modified 23d ago