Geração de Pin Codes

A API de Geração de Pin Codes disponibiliza uma solução centralizada para geração, validação e gerenciamento de códigos de segurança utilizados nas operações logísticas do Magalog.

Os Pin Codes podem ser utilizados em diferentes etapas da jornada de um pedido, como coleta, entrega e devolução, permitindo que aplicações e parceiros utilizem uma solução padronizada para confirmação dessas operações.

A solução foi desenvolvida como um serviço API-First, agnóstico e multi-tenant, permitindo que diferentes parceiros configurem suas próprias regras de geração e utilização dos códigos. Entre as configurações disponíveis estão formato, tamanho, tempo de expiração, mensagens e canais de notificação.

Principais funcionalidades

• Geração de Pin Codes
• Validação de Pin Codes
• Suporte a diferentes tipos de código
• Definição de tempo de expiração
• Controle de tentativas de validação
• Notificações via Webhook
• Autenticação e autorização utilizando o ID Magalu

Como funciona

O fluxo básico de utilização da API é:

1. Configure o parceiro — defina as regras de geração dos códigos (tamanho, formato, expiração e mensagem) via PUT /logistic/pincode-service/v1/client/settings.
2. Registre o webhook — informe a URL de callback e o token de autorização via PUT /logistic/pincode-service/v1/client/webhook.
3. Gere o Pin Code — chame POST /logistic/pincode-service/v1/pincodes informando o identificador externo da operação (external_id) e o tipo de código (pin_type).
4. Notifique o cliente — o serviço envia o código de forma assíncrona pelo canal configurado (webhook).
5. Valide na operação — no momento da coleta, entrega ou devolução, chame POST /logistic/pincode-service/v1/pincodes/validate com o código informado pelo usuário final.

A geração e a validação dos códigos acontecem de forma síncrona por meio da API REST, enquanto as notificações são processadas de forma assíncrona.

Quando utilizar

A API pode ser utilizada sempre que uma aplicação precisar de um código de segurança associado a uma operação ou etapa da jornada logística. Alguns exemplos:

• confirmar a retirada de um pedido;
• confirmar a entrega de um pedido;
• confirmar a devolução de um pedido;
• validar uma operação realizada por um parceiro;
• disponibilizar um mecanismo padronizado de autenticação de uma operação logística.

Exemplos de aplicabilidade e Experiência no App

Coleta	Entrega	Devolução
O entregador insere o PIN de coleta fornecido pelo remetente para validar a retirada da mercadoria. Chamada de API associada: POST /logistic/pincode-service/v1/pincodes/validate (pin_type: pickup)	O cliente fornece o PIN de entrega ao entregador, que o insere no app para finalizar o pedido com segurança. Chamada de API associad: POST /logistic/pincode-service/v1/pincodes/validate (pin_type: delivery)	Na devolução, o PIN de retorno é inserido para confirmar o recebimento do item no ponto de coleta ou retirada. Chamada de API associada: POST /logistic/pincode-service/v1/pincodes/validate (pin_type: return)

Escopos necessários

Para utilizar a API de Geração de Pin Codes, a aplicação deve possuir as permissões necessárias para os recursos que pretende acessar.

Escopo	Descrição
open:urpc:read	Permite operações de leitura e consulta disponibilizadas pela API.
open:urpc:write	Permite operações de criação, validação e alteração disponibilizadas pela API.

A API utiliza JWT emitido pelo ID Magalu, com autorização baseada em escopos. Para informações sobre criação da aplicação, autenticação e obtenção dos tokens, consulte o guia de integração com as APIs do Grupo Magalu.

Antes de começar

Se você pretende utilizar esta API, percorra o guia de desenvolvimento. Ele apresenta os conceitos e boas práticas básicas das APIs do Grupo Magalu e é o ponto de partida para obter um token do ID Magalu válido para operar.

Objetivos

Objetivo	Descrição
Centralização	Disponibilizar um serviço único para geração e validação de Pin Codes, independentemente do produto ou time consumidor.
Self-service	Permitir que cada parceiro configure suas próprias regras por meio da API, sem necessidade de intervenção manual.
Segurança	Garantir que os códigos sejam armazenados de forma segura e que sua validação seja protegida contra tentativas excessivas.
Flexibilidade	Permitir diferentes formatos, tamanhos, períodos de expiração e canais de notificação.
Desacoplamento	Separar a geração e validação do código dos mecanismos utilizados para sua notificação.
Resiliência	Processar notificações de forma assíncrona e utilizar mecanismos de retry para reduzir o impacto de indisponibilidades.

Tipos de Pin Code

Os códigos podem ser utilizados para diferentes finalidades dentro da jornada logística.

Tipo	Descrição
pickup	Código utilizado para confirmação de coleta ou retirada.
delivery	Código utilizado para confirmação de entrega.
return	Código utilizado para confirmação de devolução.

Ciclo de vida do Pin Code

Um Pin Code possui um ciclo de vida controlado pela API.

Status	Descrição
active	O código está disponível para validação.
validated	O código foi validado com sucesso.
expired	O período de validade do código foi encerrado.
blocked	O limite de tentativas de validação foi atingido.