> For the complete documentation index, see [llms.txt](https://cloudware.gitbook.io/documentacao-api/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://cloudware.gitbook.io/documentacao-api/setup.md).

# Setup

### 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"

![](https://i.imgur.com/BASGwVI.png)

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

![](https://i.imgur.com/Gs9TDnY.png)

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"

![](https://i.imgur.com/xbwKbDz.png)

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.

![](https://i.imgur.com/tenAEIS.png)

Para finalizar, voltar ao início da página, e selecionar o token gerado

![](https://i.imgur.com/BWrGuEk.png)

#### 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

![](https://i.imgur.com/xECDZhq.png)

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"

![](https://i.imgur.com/wGYya0c.png)