Começar com as APIs da STEF
Siga este guia para ativar a sua conta, criar a sua aplicação, subscrever APIs e invocá-las com segurança.
1. Ligar-se ao Portal API
O portal API da STEF permite-lhe subscrever as APIs da STEF através de aplicações consumidoras pessoais ou partilhadas no seio de uma equipa.
- Para aceder ao portal, é necessário solicitar a criação de uma conta de cliente.
- Para isso, entre em contacto com o seu interlocutor STEF IT para que trate dos procedimentos necessários.
- Receberá um convite que lhe permitirá criar a sua conta e aceder aos portais STEF de qualificação e de produção.
A palavra-passe deve ser renovada a cada 200 dias; será avisado desta necessidade de atualização quando se ligar ao portal.
Acesso aos portais API
- Produção: https://api-portal-ext.stef.com/
- Qualificação: https://api-portal-quaext.stef.com/
Para poder criar uma aplicação consumidora partilhada com a sua equipa, é necessário solicitar a criação de uma equipa junto do seu interlocutor STEF IT.
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-ext.stef.com
- Qualificação: https://api-suitelogi-quaext.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!.