DEVELOPER GUIDE / INTRODUÇÃO
Guia de integração
Do primeiro pedido REST à avaliação de uma integração institucional: uma referência de alto nível para equipas de engenharia, arquitectura e operações.
Compreender a plataforma
A Halcyon Platform organiza serviços versionados em torno de modelos de dados e contratos de integração. O Terminal é uma das experiências que consome esses serviços; uma aplicação parceira pode utilizar apenas interfaces expressamente autorizadas.
Fazer um primeiro pedido
Comece pelo endpoint público de saúde. Este exemplo não utiliza dados financeiros ou operacionais protegidos.
curl --request GET \\\n --url https://terminal.halcyonterminal.app/api/v1/health \\\n --header 'Accept: application/json'Num pedido bem-sucedido, a resposta segue o envelope { ok, data, meta }, incluindo informação de estado e metadados de pedido. Verifique sempre o código HTTP antes de consumir os dados.
Preparar acesso institucional
O tipo de autenticação é definido por operação. Serviços protegidos exigem uma sessão ou chave institucional aprovada, com autorização específica para os recursos solicitados. O mecanismo de credenciais, os âmbitos e a documentação adicional são fornecidos durante o onboarding do parceiro.
Guarde segredos exclusivamente no backend ou num cofre apropriado. As permissões de uma conta e os direitos contratuais dos dados são verificações distintas; nenhuma chave concede acesso irrestrito à plataforma.
Tratar respostas e erros
Prepare a integração para respostas HTTP não bem-sucedidas, falhas temporárias e indisponibilidade de dependências. Registe o identificador de pedido devolvido pelo serviço quando disponível, sem guardar credenciais ou payloads sensíveis. Os contratos institucionais identificam esquemas de erro, limites e políticas de repetição aplicáveis.
Avançar para uma integração
- Definição do caso de uso
Descreva os sistemas, fluxos de dados e finalidades da instituição.
- Revisão técnica e contratual
A PACA Systems confirma a disponibilidade das interfaces e os direitos de acesso.
- Especificação por âmbito
Disponibilização dos contratos aprovados, exemplos e requisitos de segurança aplicáveis.
- Testes e validação
O acesso a sandbox/UAT e a produção depende da maturidade da integração e do plano acordado.
Integre a Halcyon na sua instituição.
A documentação técnica detalhada, os ambientes de teste e as permissões são definidos por integração e disponibilizados após validação institucional.