Pincode de coleta

Pincode de coleta é um código numérico curto (4 dígitos) validado no momento em que o motorista chega à origem (a loja) para confirmar que o motorista certo está pegando o pedido certo. É usado por embarcadores que precisam de uma camada extra de verificação anti-fraude / compliance no handover entre a loja e o motorista.

A Abbiamo suporta dois modelos coexistentes de pincode de coleta. A escolha é parte do acordo comercial entre embarcador e transportadora, e é configurada por integração. As transportadoras só precisam saber que o mesmo campo no payload da Solicitação de entrega (logistic_data.pickup_verification.pincode_owner) indica qual fluxo se aplica a cada entrega.

Modelo tradicional — pincode_owner = "carrier"

A transportadora gera o PIN como parte do próprio fluxo de coleta.

1. A Abbiamo despacha a entrega para a transportadora com pickup_verification.pincode = true e pincode_owner = "carrier". Nenhum valor de PIN é enviado.
2. A transportadora gera o PIN internamente e o devolve para a Abbiamo no primeiro evento de status enviado após o motorista sair em direção ao ponto de coleta — geralmente at-pickup-point ou collecting-delivery — no campo collect_verification_code.
3. A Abbiamo exibe o código para o operador da loja no dashboard. O operador entrega o código ao motorista (geralmente verbalmente no balcão).
4. O motorista digita o código no app da própria transportadora. A validação acontece dentro do sistema da transportadora.
5. A transportadora envia o evento de status collected quando a coleta é finalizada.

Este é o modelo já em produção hoje para transportadoras que suportam pincode de coleta.

Modelo motorista → loja — pincode_owner = "abbiamo"

A Abbiamo é dona do PIN e valida localmente.

1. No momento em que a Abbiamo despacha uma entrega para a transportadora, ela gera um PIN de 4 dígitos único por entrega (um pedido pode ter múltiplos envios, cada um com seu próprio PIN) e persiste. A entrega é então despachada com pickup_verification.pincode = true, pincode_owner = "abbiamo" e pincode_value contendo o código de 4 dígitos.
2. A transportadora exibe o pincode_value para o motorista no app dela — o motorista leva o código consigo até o ponto de coleta.
3. Na loja, o motorista informa o código para o operador. O operador digita o código no dashboard da Abbiamo.
4. A Abbiamo valida o código localmente contra a própria cópia.
5. Se o código bater, a Abbiamo dispara o webhook Validação do pincode de coleta sincronicamente para a transportadora. A transportadora destrava o motorista no app dela e responde 200 / driver_unlocked na mesma resposta HTTP.
6. A Abbiamo transita a entrega para COLLECTED e libera a coleta no lado da loja.

Este modelo é exigido por embarcadores que precisam ser a fonte da verdade do PIN — geralmente por motivos de auditoria, prevenção de fraude ou regulatórios.

Comparação lado a lado

Como configurar

O modelo usado em cada entrega é decidido pela configuração da integração filial × transportadora do lado da Abbiamo — a transportadora não precisa fazer nada por pedido para escolher entre os dois. Para habilitar o modelo motorista → loja para um embarcador específico, a transportadora precisa:

1. Implementar a leitura de pickup_verification.pincode_value na Solicitação de entrega e exibi-lo ao motorista no app.
2. Implementar o handler Validação do pincode de coleta atendendo aos requisitos de idempotência e timeout documentados lá.
3. Falar com carrier@abbiamolog.com para virar a chave da integração para pincode_owner = "abbiamo" no embarcador específico.

Transportadoras que ainda não implementaram o modelo motorista → loja continuam recebendo pincode_owner = "carrier" (ou nenhum bloco pickup_verification quando pickup pincode não é usado) para todos os seus embarcadores — sem breaking change.