Começar com as APIs
Siga este guia para iniciar sessão no portal, criar a sua aplicação, subscrever APIs e efetuar a sua primeira chamada.
1. Ligar-se ao Portal API
Os portais API da STEF permitem-lhe subscrever as APIs da STEF através de aplicações consumidoras pessoais ou partilhadas no seio de uma equipa.
Enquanto colaborador da STEF, não é necessário solicitar a criação de uma conta para aceder aos portais.
Aceda ao portal pretendido e, no momento da autenticação, clique no botão Iniciar sessão como colaborador STEF.
Consulte o guia das instâncias APIM para obter a lista dos portais disponíveis e respetivos usos.
Para poder criar uma aplicação consumidora partilhada com a sua equipa, é necessário solicitar a criação de uma equipa através da abertura de um ticket JIRA APIM, indicando o nome da equipa e o(s) portal(is) de destino.
2. Criar uma aplicação
Para poder consumir uma API, deve primeiro dispor de uma aplicação consumidora. A sua criação gera uma credential, o identificador da sua aplicação durante uma chamada.
- Clique no seu perfil no canto superior direito do portal
- Clique no botão Applications
- Clique no botão New application
- Indique o nome e a descrição da sua aplicação
- Para partilhar esta aplicação com a sua equipa, selecione This is a team owned application e escolha a equipa pretendida
- Clique no botão Create application
- Anote a credential gerada no momento da criação
3. Subscrever uma API
Uma aplicação consumidora pode subscrever uma ou várias APIs em função das suas necessidades.
Utilize o menu APIs para consultar o catálogo das APIs STEF disponíveis.
Navegue até aos produtos do seu interesse para visualizar a documentação técnica para programadores, que apresenta para cada API:
- As diferentes operações suportadas
- A definição dos objetos de entrada e de saída
- Exemplos de código para as consumir
Para subscrever uma API:
- Abra o detalhe de uma API
- Clique em Use this API no canto superior direito
- Clique no botão Register associado à aplicação que pretende subscrever
A subscrição deverá depois ser validada pela STEF; para isso, contacte o seu interlocutor STEF IT.
Como uma aplicação pode subscrever várias APIs, repita o procedimento de subscrição para cada API que pretende utilizar.
Consultar e gerir as suas subscrições
Para consultar as subscrições de uma aplicação, clique no seu perfil no canto superior esquerdo e depois em Applications; em seguida, clique no nome da sua aplicação. No separador APIs, apresentado automaticamente, encontra a lista das suas subscrições e o respetivo estado.
Também pode solicitar a subscrição de outras APIs diretamente a partir deste menu, clicando em + API.
4. Consumir uma API
Todas as invocações das APIs da STEF passam pela Gateway API da STEF, de forma a aplicar as regras de segurança de acesso, assegurar a proteção dos serviços backend do sistema de informação da STEF e recolher estatísticas de invocação.
As Gateway API estão acessíveis através dos seguintes URLs:
- Produção: https://api-suitelogi.stef.com
- Qualificação: https://api-suitelogi-qua.stef.com/
Para consumir uma API e respeitar as regras de segurança de acesso, adicione o header HTTP X-STEF-Client-Id ao pedido, preenchido com a credential da sua aplicação consumidora.
A documentação técnica para programadores propõe, para cada API publicada na plataforma, exemplos de código que permitem invocar a Gateway API a partir de diferentes linguagens: Shell, Python, Node.js, JavaScript, Go, Java, C# e Ruby.
Exemplo de invocação
curl -X GET "https://api.stef.com/v1/transport/orders" \
-H "X-STEF-Client-Id: <YOUR_APPLICATION_SECRET>" \
-H "Content-Type: application/json"
Além dos exemplos de código, a documentação técnica para programadores propõe formulários que permitem invocar as APIs diretamente a partir do portal, em modo interativo, através do botão Try it!.