Setup

Esta primeira página descreve o processo de setup e de obtenção das credenciais de acesso à API, para qualquer uma das versões.

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:

• v0 - https://app.swaggerhub.com/apis/cloudware-deploy/APIv0/1.0

• v1 - https://app.swaggerhub.com/apis/cloudware-deploy/APIv1/1.0

Pedido de credenciais de acesso

No produto (TOCOnline, Business ou iziBizi), através do menu Empresa > Dados API (acessível apenas aos administradores da empresa), deverá introduzir o nome e o e-mail do integrador que será responsável por realizar a conexão à API. Este irá receber um e-mail com um link temporário de consulta e edição das credenciais de acesso à API, bem como um ficheiro necessário para a utilização do Postman.

Postman

O Postman é uma ferramenta poderosa de realização de pedidos a APIs, incluindo a componente de autenticação. De momento está disponível um ficheiro que poderá importar para o Postman, e permite começar a realizar pedidos à API em 2 simples passos. Este ficheiro está disponível na página de credenciais da API, enviado por e-mail ao integrador selecionado no menu Empresa > Dados API, no produto.

Setup Postman

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 descarregado na página de credenciais da API.

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 realizar a autenticação. Para o efeito, deve clicar em Open API

De seguida, deve clicar em "autenticação"

Daqui, deverá ter todos os campos como mostrado na imagem, ir ao final da página e clicar em "Gerar novo token de acesso". Este processo irá abrir uma página no seu browser, que deverá ativar um pop-up. Caso este pop-up não surja, deverá garantir que não tem a opção de 'permitir pop-ups' desativada. Quando o pop-up surjir, deverá clicar na checkbox que surge no popup, antes de confirmar a operação.

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"