Guides
  1. Documentation

Pincode de devolução — fluxo loja para motorista

Passo a passo do modelo tradicional onde a transportadora é dona do PIN de devolução e o operador da loja repassa o código ao motorista que está devolvendo o pacote.

📘

Quando esse fluxo se aplica?

Este é o fluxo tradicional de pincode de devolução, controlado por return_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 no momento do handover de volta.

É o comportamento padrão de toda integração de transportadora que suporta pincode de devolução.

👍

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 quando ele entra em rota de retorno, e valida quando o motorista digita ao chegar de volta na loja. A Abbiamo só recebe o código pra exibir no dashboard da filial, ajudando o operador a confirmar a devolução no balcão.

É o caminho com menos integração nova — qualquer transportadora que já fazia pincode de devolução 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 devolução no dashboard — esse controle fica todo do lado da transportadora.

Quando uma devolução acontece

Devolução é o caminho de volta do pacote pra origem (a loja) depois que a entrega ao cliente final não foi concluída — cliente ausente, recusa, endereço inválido, etc. A transportadora despacha o motorista pra refazer o caminho até a loja com o pacote, e é no handover de volta no balcão que esse PIN de 4 dígitos é validado.

Quem valida o quê

AtorResponsabilidade
TransportadoraGera o PIN. Ecoa o código de volta pra Abbiamo no primeiro evento de status do retorno. 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, no momento em que recebe o pacote de volta).
MotoristaRecebe o PIN do operador e digita no app da própria transportadora antes de finalizar a devolução.

Passo a passo

  1. Falha na entrega ao cliente final. A entrega falha por um dos motivos típicos (PACKAGE_NOT_COLLECTED, recusa do cliente, endereço inválido, etc.) e entra em fluxo de devolução. A integração filial × transportadora já está configurada com return_verification.pincode = true e return_verification.pincode_owner = "carrier".
  2. Despacho da devolução. A Abbiamo envia o webhook Delivery request pra transportadora (ou outro despacho equivalente, dependendo da fase do ciclo de vida). O bloco logistic_data.return_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, no momento em que decide despachar a rota de retorno.
  4. A transportadora ecoa o PIN. No primeiro evento de status do retorno enviado depois do despacho de devolução — tipicamente Returning delivery — a transportadora inclui o campo return_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 na loja com o pacote. O operador lê o PIN no dashboard e repassa pro motorista (verbalmente no balcão é o caso mais comum) antes de aceitar fisicamente o pacote de volta.
  7. Motorista digita no app da transportadora. A validação acontece dentro do sistema da transportadora — a Abbiamo não participa nesse momento.
  8. Devolução confirmada. Quando a transportadora aceita o código, ela envia o evento Returned delivery pra Abbiamo, e a entrega transita pra RETURNED.

Exemplos de payload

Delivery request da Abbiamo pra transportadora (bloco relevante):

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

Atualização de status da transportadora ecoando o PIN de devolução de volta pra Abbiamo (exemplo no returning-delivery):

{
  "delivery_id": "851dc274-e090-4881-8f3c-5b660cecf059",
  "event_at": "2026-05-12T16:10:00.000Z",
  "return_verification_code": "8745"
}

Quando return_verification.pincode = false (ou o bloco está ausente), a transportadora não deve enviar return_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. A flag de pickup e a flag de return são independentes — uma entrega pode ter um, outro, ambos ou nenhum. Trate as duas separadamente.

Erros comuns

  • Enviar return_verification_code em toda devolução. Só envie quando o Delivery request marcou return_verification.pincode = true. Caso contrário o campo é ignorado.
  • Misturar collect_verification_code e return_verification_code. São campos distintos com semânticas diferentes — o primeiro é pra coleta na loja no início da rota, o segundo é pra devolução na loja no fim de uma rota que falhou. Não reaproveite o valor.
  • 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 returned-delivery não chega).
  • Ecoar só no returned. Ecoe o PIN no returning-delivery — quanto antes melhor. Quando o returned chega, o eco no dashboard já perdeu utilidade pro operador.

Referências relacionadas

Updated 2 days ago