Pular para o conteúdo principal

Faça o seu primeiro pedido à API

Este guia de início rápido utiliza um projeto da Plataforma de programadores e o respetivo ambiente Sandbox determinístico. Exercita o mesmo processo de autenticação de Produção sem criar efeitos em produção.

Antes de começar​

Precisa de:

  • uma conta Alkax com acesso à Consola de programadores;
  • um projeto e o respetivo ambiente Sandbox;
  • uma credencial Sandbox com delivery:read para o primeiro cenário de teste;
  • um backend ou ambiente de servidor seguro;
  • o URL base da API: https://api.alkax.io.

Guarde as credenciais num gestor de segredos e oculte-as nos registos da aplicação.

Abra https://alkax.io/developers, crie um projeto e emita uma credencial Sandbox em Credenciais. Copie o segredo quando for apresentado; não poderá recuperá-lo mais tarde.

Definir as variáveis do pedido​

export ALKAX_API="https://api.alkax.io"
export ALKAX_API_KEY="ak_test_<key-id>.<secret>"

Fazer um pedido determinístico ao Sandbox​

Chame um cenário de teste versionado que seja seguro executar no desenvolvimento local e na integração contínua:

curl "$ALKAX_API/api/v1/sandbox/fixtures/valid-high-confidence" \
  --header "X-Alkax-Key: $ALKAX_API_KEY" \
  --header "Accept: application/json"

A resposta inclui um resultado estável do cenário e um cabeçalho X-Request-Id. Utilize esse ID para encontrar o pedido no separador Registos da Consola de programadores.

Outros cenários estáveis são ambiguous, weak-access, not-found e conflicting-evidence. A área de testes da consola pode executar os mesmos cenários e gerar exemplos em curl, TypeScript, Python e C#.

Passar a um endpoint de negócio​

Emita uma credencial apenas com o âmbito necessário e chame o endpoint com o mesmo cabeçalho X-Alkax-Key. Para confirmação pelo destinatário antes da expedição, siga o guia Delivery Intelligence.

Não utilize uma chave Sandbox em Produção. Quando a integração estiver pronta, ative uma subscrição paga e emita uma credencial ak_live_ separada no ambiente de Produção.

Tratar a resposta​

  • Considere o estado HTTP como o resultado principal.
  • Guarde os IDs estáveis, os códigos de erro legíveis por máquina e o ID do pedido.
  • Utilize identificadores seguros para repetição quando o guia o exigir.
  • Aumente o intervalo entre tentativas perante respostas 429 e 5xx transitórias.
  • Nunca repita um pedido inválido sem o alterar.

Consulte Erros e novas tentativas para conhecer o modelo comum de resposta.

Continuar​

Concluir uma integração funcional​

Após o primeiro pedido Sandbox, continue com a integração de entregas e devoluções e o guia prático de webhooks. O cenário é um exemplo de endereço; não cria uma expedição. Utilize as APIs versionadas e os processos Sandbox documentados para exercitar um ciclo de vida sintético completo antes de passar a Produção.