Documentação API
Search…
⌃K

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:

Pedido de credenciais de acesso

No TOCOnline, através do menu Empresa -> Dados API, 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 acesso e edição das credenciais de acesso à API, bem como um ficheiro necessário para a utilização do Postman.

Postman

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 TOCOnline.

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"