Pickup pincode — fluxo motorista para filial

Quem valida o quê

Passo a passo

1. Criação do pedido. O embarcador cria uma entrega pela Orders API. A integração embarcador × transportadora está configurada pela Abbiamo com pickup_verification.pincode = true e pickup_verification.pincode_owner = "abbiamo". A Abbiamo gera um PIN de 4 dígitos e o persiste na entrega.
2. Despacho. A Abbiamo envia o webhook de Requisição de entrega à transportadora. O bloco logistic_data.pickup_verification contém pincode: true, pincode_owner: "abbiamo" e pincode_value com o código de 4 dígitos.
3. Transportadora exibe o PIN ao motorista. O aplicativo do motorista mostra o código recebido em pincode_value junto com as demais informações de coleta.
4. Motorista chega à loja. Informa verbalmente o PIN ao operador no balcão.
5. Operador digita o PIN no dashboard. A Abbiamo valida o código localmente contra a cópia armazenada na criação do pedido.
6. Abbiamo solicita à transportadora que libere o motorista. Se o PIN coincidir, a Abbiamo dispara o webhook de Validação do pin de coleta à transportadora. Esta chamada é síncrona — a Abbiamo aguarda a resposta da transportadora na mesma requisição HTTP, com timeout de 5 segundos.
7. Transportadora libera o motorista e responde. Na mesma resposta HTTP, a transportadora retorna 200 / driver_unlocked (ou 200 / already_unlocked para uma nova tentativa idempotente). O aplicativo do motorista para de bloquear a coleta.
8. Coleta confirmada. A Abbiamo transita a entrega para COLLECTED, retorna sucesso ao dashboard e o operador libera fisicamente o pacote ao motorista.

Se o PIN não coincidir, o operador vê um erro no dashboard. A transportadora não é chamada, o motorista permanece bloqueado e o status da entrega não muda. Se a transportadora responder com 4xx/5xx ou expirar o timeout, o dashboard exibe um erro de "transportadora indisponível" e o operador pode tentar novamente ou recorrer a um canal manual.

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": "abbiamo",
      "pincode_value": "8745"
    }
  }
}

Webhook síncrono da Abbiamo para a transportadora quando o operador envia o PIN:

{
  "event_type": "PICKUP_PIN_VALIDATION_REQUEST",
  "event_at": "2026-05-12T14:34:17.890Z",
  "delivery_id": "851dc274-e090-4881-8f3c-5b660cecf059"
}

Resposta esperada da transportadora na mesma requisição HTTP:

{
  "code": "driver_unlocked",
  "delivery_id": "851dc274-e090-4881-8f3c-5b660cecf059",
  "unlocked_at": "2026-05-12T14:34:18.014Z",
  "driver": {
    "id": "MOTO-5544",
    "name": "Carlos Silva",
    "document_number": "12345678900"
  }
}

Habilitando este fluxo

A escolha do modelo faz parte do acordo comercial entre embarcador e transportadora, e é configurada pelo lado da Abbiamo — o embarcador não escolhe o modelo por pedido. Para habilitar o fluxo motorista para filial em um par embarcador × transportadora:

1. A transportadora deve suportar a leitura de pickup_verification.pincode_value no webhook de Requisição de entrega e exibi-lo ao motorista.
2. A transportadora deve expor o handler do webhook de Validação do pin de coleta, respeitando os requisitos de idempotência e timeout de 5 segundos documentados ali.
3. Ambos os lados entram em contato com carrier@abbiamolog.com para migrar a integração para pincode_owner = "abbiamo".

Enquanto ambos os lados não estiverem prontos, a integração permanece no fluxo padrão pincode_owner = "carrier" — sem quebra de contrato.

Armadilhas comuns

• Transportadora ignora pincode_value e gera seu próprio PIN. Neste modelo, a transportadora deve exibir o pincode_value recebido — o operador digitará esse código, não o que a transportadora gerou. PINs divergentes aparecem como erros INVALID_PIN no dashboard.
• Handler da transportadora muito lento no webhook síncrono. O timeout padrão da Abbiamo é de 5 segundos. Se a lógica de liberação da transportadora for mais pesada, ela deve responder 200 / driver_unlocked assim que o desbloqueio for confirmado em seu banco de dados e concluir o restante do trabalho de forma assíncrona.
• Handler da transportadora não é idempotente. A Abbiamo realiza uma nova tentativa em caso de 5xx / timeout. O handler deve retornar 200 / already_unlocked (sem reexecutar os efeitos colaterais) ao receber uma segunda chamada para o mesmo delivery_id.

Validação via API (sem o dashboard)

Operações que usam ferramenta própria (em vez do dashboard da Abbiamo) executam os passos 5–6 via API pública:

• Verificações do pedido (coleta e retorno) — informa se o pedido exige o PIN de coleta (e o código de retorno, quando houver).
• Confirmar pincode de coleta — valida o PIN digitado, libera o motorista na transportadora e transita a entrega para COLLECTED.

Referências relacionadas

• Pickup pincode (visão geral dos dois modelos)
• Webhook de requisição de entrega
• Webhook de validação do pin de coleta