Pickup pincode — fluxo filial para motorista

Passo a passo do modelo tradicional de pickup pincode, em que a transportadora é dona do PIN e o operador da loja repassa ao motorista.

Este é o fluxo de pickup pincode tradicional, controlado por pickup_verification.pincode_owner = "carrier" no webhook de Requisição de entrega. A transportadora gera o PIN como parte de sua própria operação de coleta; o dashboard da filial apenas exibe o código para que o operador da loja possa repassá-lo ao motorista.

Este é o padrão para toda integração de transportadora que suporta pickup pincode hoje — nenhum opt-in é necessário. Para o modelo alternativo em que a Abbiamo é dona do PIN, consulte Pickup pincode — fluxo motorista para filial.

Quem valida o quê

Ator	Responsabilidade
Transportadora	Gera o PIN. Repassa-o à Abbiamo no primeiro evento de status. Valida o PIN digitado pelo motorista dentro do seu próprio aplicativo.
Abbiamo	Recebe o PIN da transportadora e exibe na visualização do pedido da filial. Não valida o PIN neste modelo.
Operador da loja	Lê o PIN no dashboard e repassa ao motorista (normalmente de forma verbal no balcão).
Motorista	Recebe o PIN do operador e digita no aplicativo da transportadora.

Passo a passo

Criação do pedido. O embarcador cria uma entrega pela Orders API. A integração embarcador × transportadora já está configurada pela Abbiamo com pickup_verification.pincode = true e pickup_verification.pincode_owner = "carrier".
Despacho. A Abbiamo envia o webhook de Requisição de entrega à transportadora. O bloco logistic_data.pickup_verification contém pincode: true e pincode_owner: "carrier". Nenhum pincode_value é enviado — a transportadora é quem o gera.
Transportadora gera o PIN. Internamente, em seus próprios sistemas.
Transportadora repassa o PIN. No próximo evento de status após o motorista se dirigir ao ponto de coleta — tipicamente At pickup point ou Collecting delivery — a transportadora inclui collect_verification_code no payload. Eventos de status que aceitam esse campo:
Dashboard exibe o PIN. A Abbiamo persiste o código e o exibe no sidepanel do pedido no dashboard da filial.
Entrega na loja. O motorista chega. O operador da loja lê o PIN no dashboard e o repassa ao motorista (verbalmente no balcão é o padrão mais comum).
Motorista digita no aplicativo da transportadora. A validação ocorre dentro do sistema da transportadora — a Abbiamo não participa neste ponto.
Coleta confirmada. Quando a transportadora aceita o código, ela envia um evento de status collected à Abbiamo, e a entrega transita para COLLECTED.

Exemplos de payload

Requisição de entrega da Abbiamo para a transportadora (bloco relevante apenas):

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

Atualização de status da transportadora repassando o PIN à Abbiamo (exemplo com 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 estiver ausente), a transportadora não deve enviar collect_verification_code nos eventos de status — o campo é ignorado de qualquer forma e gera ruído de auditoria.

As transportadoras devem persistir a decisão "enviar código sim/não" por delivery_id no momento em que recebem o webhook de Requisição de entrega. Isso evita omitir o código acidentalmente em um evento posterior ou enviá-lo em uma entrega que não habilitou o pickup pincode.

Armadilhas comuns

Enviar collect_verification_code em toda entrega. Envie apenas quando a Requisição de entrega sinalizou pickup_verification.pincode = true. Caso contrário, o campo é ignorado.
Validação apenas na transportadora — a Abbiamo não pode ajudar se o operador repassar o código errado. Se o operador ler o código incorretamente e o motorista digitá-lo errado, o aplicativo da transportadora rejeita a entrada. A Abbiamo só fica sabendo indiretamente (nenhum evento collecting-delivery chega).
Repassar o PIN somente no collected. Repasse o PIN em at-pickup-point ou collecting-delivery — quanto antes, melhor. Quando o collected chega, o código no dashboard já não é mais útil para o operador.

Pickup pincode — fluxo filial para motorista

Quem valida o quê

Passo a passo

Exemplos de payload

Armadilhas comuns

Referências relacionadas

Nesta página