Crie e opere uma integração Alkax

A Plataforma de programadores Alkax agrupa cada integração num projeto. Cada projeto começa com ambientes Sandbox e Produção isolados, para que a atividade de teste, as credenciais, as quotas, os registos e os webhooks não atravessem os limites dos ambientes.

Abra a Consola de programadores em https://alkax.io/developers para criar e gerir projetos.

Modelo de projeto

Um projeto pertence à sua conta ou a uma organização. A política da organização pode limitar a criação de projetos, os âmbitos disponíveis, a quota, a duração das credenciais e o acesso a produção.

As funções de projeto são:

Função	Acesso habitual
Titular	Ciclo de vida completo do projeto, membros, credenciais e definições
Programador	Criar e operar a integração
Analista	Inspecionar utilização, estado de funcionamento e registos de pedidos
Leitor de faturação	Consultar a utilização relacionada com a faturação

Criar o primeiro projeto

1. Abra a Consola de programadores.
2. Selecione Novo projeto e escolha uma conta ou organização como titular.
3. Abra Credenciais e emita uma credencial Sandbox apenas com os âmbitos necessários.
4. Copie imediatamente o segredo. A Alkax guarda apenas o hash derivado e não o pode apresentar novamente.
5. Chame um cenário Sandbox ou utilize a área de testes da consola.
6. Inspecione Utilização e Registos com o ID do pedido devolvido.

Credenciais e âmbitos

Envie uma credencial do servidor no cabeçalho X-Alkax-Key:

X-Alkax-Key: ak_test_<key-id>.<secret>

As chaves Sandbox começam por ak_test_; as chaves de Produção começam por ak_live_. Os âmbitos disponíveis incluem:

Âmbito	Permite
places:read	Ler dados de locais
geocode:read	Pesquisar e geocodificar
delivery:read	Ler o estado de confirmação de entrega
delivery:write	Criar e alterar confirmações de entrega

A codificação e a descodificação Grid estão disponíveis como operações de API separadas com X-Alkax-Key e o âmbito places:read; consulte o guia de endereços Alkax Grid.

A rotação cria uma credencial substituta. Implemente a substituta antes de revogar a chave anterior. A revogação, a expiração e a suspensão do projeto ou do ambiente têm efeito nos pedidos seguintes.

Subscrição e direitos de utilização

A utilização da API de programadores é regida pela subscrição do titular do projeto e pela política aplicável da organização.

Plano	Direitos de utilização da API de programadores
Gratuito	Apenas Sandbox, até 1 000 pedidos por mês
Pro mensal ou anual	Sandbox e Produção, até 50 000 pedidos por mês
Enterprise	Sandbox e Produção, sem limite por predefinição

A franquia do plano é partilhada por todos os projetos e ambientes faturados à mesma conta. Os limites de projeto, organização e ambiente podem impor um teto inferior. Não podem aumentar a franquia da subscrição.

Quando uma subscrição paga expira ou fica inativa, as credenciais de Produção existentes recebem 402 subscription_required. Quando a franquia mensal se esgota, os pedidos recebem 429 quota_exceeded até ao próximo período de faturação ou à atualização do plano.

Sandbox determinístico

As credenciais Sandbox utilizam o mesmo processo de autenticação e os mesmos contratos de endpoints de Produção, mantendo isolados os efeitos e a utilização.

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

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

Os identificadores de cenários estáveis incluem:

Cenário	Resultado
valid-high-confidence	Entregável com confiança elevada
ambiguous	Esclarecimento recomendado
weak-access	Endereço válido com baixa confiança na entrada ou no acesso
not-found	Endereço desconhecido
conflicting-evidence	Provas contraditórias e baixa confiança

Utilize os cenários de falha Sandbox error-403, error-404, error-409, error-429 e error-500 para testar o tratamento de falhas. Utilize uma credencial inválida ou revogada para exercitar o percurso real de 401.

IDs de pedido, utilização e registos

Cada resposta da API de programadores inclui X-Request-Id. O mesmo valor liga a resposta aos registos de pedidos e aos diagnósticos de suporte.

A consola regista metadados que preservam a privacidade, como o modelo da rota, método, estado, latência, impacto na quota, ambiente e nome da credencial. As credenciais e os campos sensíveis do conteúdo são excluídos.

Webhooks

Abra Webhooks, escolha um ambiente, introduza um destino HTTPS público e selecione um tipo de evento na lista. Os eventos de projeto suportados incluem:

• delivery.confirmation.created
• delivery.confirmation.cancelled

O segredo de assinatura é apresentado uma vez. Sandbox e Produção utilizam regras de assinatura idênticas, mas segredos diferentes.

Os pedidos webhook incluem:

X-Alkax-Event-Id: <UUID>
X-Alkax-Timestamp: <Unix seconds>
X-Alkax-Signature: v1=<lowercase HMAC-SHA256>

Calcule a assinatura esperada sobre <timestamp>.<raw-body>, rejeite datas/horas antigas, compare assinaturas em tempo constante e elimine duplicados pelo ID do evento. A consola pode enviar um evento de teste, apresentar tentativas de entrega e excertos seguros de respostas e reenviar manualmente um evento falhado.

A Alkax rejeita destinos de loopback, privados, link-local e destinos que o DNS resolva para endereços privados. Não segue redirecionamentos.

Preparação para Produção

Antes de emitir uma credencial de Produção:

• confirme a subscrição e o acesso a Produção;
• minimize os âmbitos da credencial;
• conclua um pedido Sandbox com sucesso;
• teste o tratamento de falhas e as respostas de quota;
• verifique a acessibilidade e as assinaturas dos webhooks;
• configure as restrições de acesso disponíveis quando adequado;
• confirme que nenhuma chave ak_test_ está presente na configuração de Produção.

Continue com o início rápido da API, o guia de autenticação ou a referência da API.