Guides
  1. Documentation

Pincode de coleta — fluxo loja para motorista

Passo a passo do modelo tradicional onde a transportadora é dona do PIN e o operador da loja repassa o código ao motorista.

📘

Quando esse fluxo se aplica?

Este é o fluxo tradicional de pincode de coleta, controlado por pickup_verification.pincode_owner = "carrier" no webhook Delivery request. A transportadora gera o PIN como parte da operação dela; o dashboard da filial apenas ecoa o código para que o operador da loja possa repassar ao motorista.

É o comportamento padrão de toda integração de transportadora que suporta pincode de coleta hoje — não exige opt-in. Para o modelo alternativo, em que a Abbiamo é dona do PIN, veja Pincode de coleta — fluxo motorista para loja.

👍

Por que a transportadora gera o PIN nesse modelo?

Esse é o jeito clássico: a transportadora gera o código internamente, mostra pro motorista no app dela e valida quando o motorista digita. A Abbiamo só recebe o código pra exibir no dashboard da filial, ajudando o operador da loja a passar pro motorista no balcão.

É o caminho com menos integração nova — qualquer transportadora que já fazia pincode de coleta funciona aqui sem mudar nada. Em contrapartida, cada transportadora segue com sua própria regra (formato do código, quantas tentativas o motorista pode fazer, etc.), e a filial não tem como liberar administrativamente uma coleta no dashboard — esse controle fica todo do lado da transportadora. Quem precisa de regras unificadas ou liberação centralizada deve olhar o fluxo motorista para loja.

Quem valida o quê

AtorResponsabilidade
TransportadoraGera o PIN. Ecoa o código de volta pra Abbiamo no primeiro evento de status. Valida o PIN digitado pelo motorista dentro do próprio app.
AbbiamoRecebe o PIN da transportadora e exibe na tela do pedido da filial. Não valida o PIN nesse modelo.
Operador da lojaLê o PIN no dashboard e repassa para o motorista (geralmente verbalmente no balcão).
MotoristaRecebe o PIN do operador e digita no app da própria transportadora.

Passo a passo

  1. Criação do pedido. A filial cria a entrega pela Orders API. A integração filial × transportadora já está configurada pela Abbiamo com pickup_verification.pincode = true e pickup_verification.pincode_owner = "carrier".
  2. Despacho. A Abbiamo envia o webhook Delivery request pra transportadora. O bloco logistic_data.pickup_verification traz pincode: true e pincode_owner: "carrier". Nenhum pincode_value é enviado — a própria transportadora vai gerar o código.
  3. A transportadora gera o PIN. Internamente, nos sistemas dela.
  4. A transportadora ecoa o PIN. No próximo evento de status enviado depois que o motorista se dirige ao ponto de coleta — tipicamente At pickup point ou Collecting delivery — a transportadora inclui o campo collect_verification_code no payload. Eventos de status aceitos para carregar esse campo:
  5. Dashboard exibe o PIN. A Abbiamo persiste o código e mostra no sidepanel do pedido dentro do dashboard da filial.
  6. Repasse na loja. O motorista chega. O operador lê o PIN no dashboard e repassa pro motorista (verbalmente no balcão é o caso mais comum).
  7. Motorista digita no app da transportadora. A validação acontece dentro do sistema da transportadora — a Abbiamo não participa nesse momento.
  8. Coleta confirmada. Quando a transportadora aceita o código, ela envia um evento de status collected pra Abbiamo, e a entrega transita pra COLLECTED.

Exemplos de payload

Delivery request da Abbiamo pra transportadora (bloco relevante):

{
  "event_type": "DELIVERY_REQUEST",
  "logistic_data": {
    "pickup_verification": {
      "pincode": true,
      "pincode_owner": "carrier"
    }
  }
}

Atualização de status da transportadora ecoando o PIN de volta pra Abbiamo (exemplo no at-pickup-point):

{
  "delivery_id": "851dc274-e090-4881-8f3c-5b660cecf059",
  "event_at": "2026-05-12T15:10:00.000Z",
  "collect_verification_code": "123456"
}

Quando pickup_verification.pincode = false (ou o bloco está ausente), a transportadora não deve enviar collect_verification_code nos eventos de status — o campo é ignorado e só polui auditoria.

👍

Dica de implementação

A transportadora deve persistir a decisão de "envia o código ou não" por delivery_id no momento em que recebe o webhook Delivery request. Isso evita esquecer de enviar o código num evento posterior, ou enviar em uma entrega que não habilitou pincode.

Erros comuns

  • Enviar collect_verification_code em toda entrega. Só envie quando o Delivery request marcou pickup_verification.pincode = true. Caso contrário o campo é ignorado.
  • Validação só do lado da transportadora — a Abbiamo não ajuda se o operador disser o código errado. Se o operador lê errado e o motorista digita incorretamente, o app da transportadora rejeita. A Abbiamo só percebe indiretamente (o evento collecting-delivery não chega).
  • Ecoar só no collected. Ecoe o PIN no at-pickup-point ou collecting-delivery — quanto antes melhor. Quando o collected chega, o eco no dashboard já perdeu utilidade pro operador.

Referências relacionadas

Updated 2 days ago