Introdução

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

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

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

Setup Postman

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 http://postman-echo.com/get.
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"
A partir deste ponto, deverá importar o ficheiro openAPI
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 client_id e client_secret para os dados identificador e segredo, respetivamente, consultados na página de dados da API. Os restantes atributos preenchidos na imagem deverão ser copiados para o Postman.
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

Pedidos à API

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"