Abbiamo DocsTransportadora — Quick Guide - Código de Coleta
Esclarecimentos sobre quando informar collect_verification_code nos endpoints de status
Quick Guide - Código de Coleta
Este guia explica especificamente quando informar collect_verification_code nos endpoints de status da API de transportadoras.
Visibilidade do código no dashboard
Quando o envio está com código de coleta habilitado, o cliente consegue ver essa informação no dashboard. Depois que a transportadora prover o código, ele fica visível no sidepanel do pedido para que a operação possa disponibilizá-lo ao motorista.
Quando informar o collect_verification_code
Você pode enviar collect_verification_code nos endpoints de status:
Mas esse campo só deve ser enviado quando o webhook de entrega indicar que verificação por código está habilitada, isto é:
logistic_data.pickup_verification.pincode = true
Regra prática
- Receba o webhook Delivery request.
- Leia
logistic_data.pickup_verification.pincode. - Se for
true, incluacollect_verification_codenas chamadas de status permitidas. - Se for
false(ou ausente), não enviecollect_verification_code.
Exemplo mínimo do webhook (campo relevante)
Este payload é uma simplificação apenas para destacar os campos necessários nesta regra. O payload completo possui mais campos na documentação oficial.
{
"event_type": "DELIVERY_REQUEST",
// ... outros campos
"seller": {
// ... outros campos
},
"carrier": {
// ... outros campos
},
"deliveries": [
{
"delivery_id": "851dc274-e090-4881-8f3c-5b660cecf059",
"content_declaration": {
"key": "52060433009911002506990010000007800267301619",
"serie": "001",
"number": "000000780"
}
// ... outros campos da entrega
}
],
"logistic_data": {
// ... outros campos de logística
"pickup_verification": {
"pincode": true
}
}
}Exemplo de status com código (quando pincode = true)
{
"delivery_id": "851dc274-e090-4881-8f3c-5b660cecf059",
"event_at": "2026-03-13T15:10:00.000Z",
"collect_verification_code": "123456"
}Exemplo de status sem código (quando pincode = false)
{
"delivery_id": "851dc274-e090-4881-8f3c-5b660cecf059",
"event_at": "2026-03-13T15:10:00.000Z"
}Boa prática de implementação
Persista por delivery_id a decisão de enviar ou não collect_verification_code, com base no webhook de entrada. Isso evita envio indevido do campo em etapas subsequentes.