De uma chave Sandbox a uma devolução concluída

Comece pelo início rápido da API. Utilize um projeto Sandbox dedicado para estes exemplos. A Alkax regista o progresso físico das entregas e devoluções. O seu sistema de comércio é responsável pelos reembolsos, stock, trocas e crédito ao cliente.

Credenciais e ambientes

O servidor da API é https://api.alkax.io. A escolha entre Sandbox e Produção depende do ambiente da credencial, não de um caminho no URL. Nunca coloque uma chave de programador em código de navegador ou móvel. Um token de acesso de conta Alkax é diferente de uma credencial X-Alkax-Key.

Operação	Âmbito
Criar uma expedição ou devolução canónica	delivery:create
Ler o estado privado de expedição/devolução	delivery:read
Submeter eventos de entrega/devolução; registar a receção num ponto de entrega	delivery:events
Submeter provas ou ficheiros de prova de devolução	delivery:proof
Confirmação de endereço, aprovar/rejeitar/cancelar uma devolução canónica, acesso à recolha, resolução RTS	delivery:write

Uma integração completa de entregas e devoluções precisa dos âmbitos exigidos pelas operações que executa. A rotação mantém os âmbitos da chave anterior, pelo que emitir uma nova chave não altera o conjunto de âmbitos autorizados. A ausência do âmbito de prova pode impedir o sucesso do evento de conclusão dependente. Copie apenas a chave em bruto. Consulte a resolução de problemas.

Ciclo de vida da expedição de saída

Após a confirmação do endereço, utilize o instantâneo confirmado imutável como destination em POST /api/v1/deliveries. Forneça um Idempotency-Key e um activationEventId estável. A criação devolve id, trackingNumber e o estado. Não assuma que a referência externa da encomenda é um número de seguimento Alkax.

Submeta POST /api/v1/deliveries/{id}/events com um UUID estável em eventId, uma data/hora real em occurredAt e um destes comandos:

Comando	Resultado
MarkInTransit	InTransit
MarkAtLocalDepot	AtLocalDepot
MarkOutForDelivery	OutForDelivery
RecordDeliveryAttempt	DeliveryAttempted
CompleteDelivery	Delivered

Repita o evento exato após uma falha de transporte. Um 409 exige a inspeção do estado canónico; não invente um novo ID para contornar as verificações de conflito. São rejeitadas datas/horas mais de cinco minutos no futuro. Os IDs de eventos são separados dos IDs de pedidos utilizados para diagnóstico. Não dependa de frases de erro traduzidas.

Para a prova de entrega de saída, faça primeiro POST /api/v1/deliveries/{id}/proofs com proofId estável, method, occurredAt e os campos obrigatórios de recetor/referência. Forneça este proofId a CompleteDelivery. Submeta a prova antes do evento dependente. A prova tem de pertencer à mesma expedição/ambiente; a prova de devolução tem um contrato separado.

Acesso do destinatário

O seguimento anónimo expõe apenas o progresso geral. Um número de seguimento não pode autorizar a associação de contas, pedidos de devolução, instruções privadas ou acesso a provas. A associação de conta verifica o contacto do destinatário. A correspondência de um endereço de correio eletrónico não verificado não é um mecanismo de autorização. O contacto da confirmação de endereço não é automaticamente o contacto do destinatário da expedição canónica.

Um destinatário associado só pode pedir uma devolução depois de a expedição estar Delivered. Em As minhas entregas, escolha recolha ou entrega num ponto e indique um motivo. O pedido permanece pendente até ser aprovado ou rejeitado. Uma entrega num ponto aprovada continua a exigir o registo da receção física. É suportado um pedido por volume de saída e as decisões são finais.

Autorização de devolução pelo comerciante

POST /api/v1/returns aceita originalShipmentId, eventId, type, reason, destination, origin/instruções opcionais e requisitos de prova de recolha/receção. Utilize type: RecipientReturn, reason: RecipientChangedMind para o processo mínimo de cliente. Uma devolução de cliente exige uma expedição de saída Delivered. Se a origem for omitida, parte-se do instantâneo de saída, não de uma consulta de endereço mutável.

A autorização é separada da logística. As devoluções de cliente pedidas precisam de POST /api/v1/returns/{id}/approve?eventId={uuid}. A rejeição e o cancelamento utilizam a mesma convenção de ID na query. O cancelamento só é possível antes da entrega física. Uma devolução aprovada começa em AwaitingHandover; a aprovação por si só não agenda um estafeta.

Confirmar a recolha e submeter provas de devolução

1. Chame POST /api/v1/returns/{id}/pickup-confirmation com delivery:write.
2. Entregue o URL do destinatário devolvido de forma segura. Emitir uma substituição revoga a ligação anterior ainda não concluída. Não registe nem exponha o token no seguimento público.
3. O destinatário revê/corrige a recolha através do processo público com token. O instantâneo confirmado permanece separado do destino original de saída.
4. Se forem necessárias provas, capture uma assinatura/fotografia PNG real. Envie através de PUT /api/v1/returns/{id}/proof-assets/{proofId}/signature (ou /photo) com { "dataUrl": "data:image/png;base64,..." }. Máximo de 2 MB, 2048 por 2048 píxeis.
5. Utilize a reference devolvida em POST /api/v1/returns/{id}/proofs com o mesmo proofId, purpose: Pickup ou Receipt, método e data/hora. Os métodos de assinatura exigem informações do recetor. Texto arbitrário ou URLs de comerciantes não substituem validamente os ficheiros de devolução enviados.
6. Inclua esse ID de prova no evento correspondente de entrega física/conclusão.

As novas tentativas de envio de ficheiros têm de utilizar bytes idênticos. A prova de recolha de uma devolução não pode satisfazer o requisito de receção e nenhuma pode reutilizar a prova de saída. Os ficheiros privados exigem delivery:proof e correspondência de projeto/ambiente tanto na leitura como na escrita.

Logística inversa e RTS por entrega falhada

Submeta eventos de devolução com IDs estáveis em /api/v1/returns/{id}/events: SchedulePickup, MarkPickedUp, MarkAtReturnHub, MarkInTransit, Complete. Complete produz DeliveredToMerchant numa devolução de cliente e ReturnedToSender numa entrega falhada. RecordException regista uma exceção logística; não é uma autorização para reescrever o histórico.

Para uma expedição DeliveryAttempted, chame POST /api/v1/deliveries/{id}/resolution com evaluationId estável, failureReason normalizado, attemptCount positivo e um returnDestination confirmado quando a devolução ao remetente (RTS) for possível. A política documentada escolhe RTS em caso de recusa, destinatário indisponível após três tentativas ou problema de pagamento após duas. Problemas de endereço exigem correção; falhas desconhecidas seguem para revisão manual. As provas normalizadas repetidas são deduplicadas. Não utilize o texto de falha em bruto da transportadora como motivo canónico.

As leituras privadas de devoluções utilizam /api/v1/returns/{id} ou /by-tracking/{trackingNumber}. O endpoint anónimo /api/public/returns/{trackingNumber} omite o contacto, a localização precisa, as instruções e as provas.

Limites de responsabilidade e confiança

Merchant server -- scoped environment key --> Alkax API
Recipient      -- expiring capability ----> Confirm address / pickup
Recipient      -- verified account -------> Linked delivery / return request
Public viewer  -- tracking number --------> Coarse progress only
Alkax webhook  -- signed raw body --------> Merchant webhook receiver
Merchant system -- own business policy ---> Refund / inventory system

Sandbox e Produção têm credenciais, recursos e subscrições de webhooks separados. Um webhook não transfere permissão para outro ambiente. Consulte o guia prático de webhooks e a lista de verificação para entrada em produção.

Utilize a matriz de testes Sandbox para os casos de correção, expiração, rejeição, âmbito errado e reenvio.