Objeto `delivery`

Como mencionado em Criar pedido (v2), o objeto delivery é uma ferramenta poderosa que automatiza o despacho do pedido pra transportadora já no momento da criação.

Existem quatro formas de montar o objeto delivery. Abaixo elas aparecem da mais simples (menos específica) pra mais específica.

1 - Preference Rule (objeto mínimo)

A forma mais simples de montar o delivery object é especificando apenas preference_rule. A regra escolhida determina qual delivery_method, entre as opções cadastradas, é usado no despacho. Existem duas preference_rules: cheapest e fastest.

{
  "preference_rule": "fastest"
}

Você pode usar esta forma do delivery object mesmo sem utilizar o endpoint de cotação ou as opções de entrega.

2 - Por nome da transportadora

Outra forma menos específica é informar o nome da transportadora escolhida. Como o nome da transportadora não basta para definir o método exato, este formato permite incluir o nome junto com um preference_rule opcional. Sem preference_rule, o valor padrão é cheapest. Para listar os nomes das transportadoras disponíveis para um pedido, use o endpoint Opções de entrega.

{
  "carrier_name": "TRANSPORTADORA-B",
  "schedule_at": "2025-03-28T15:08:00.000Z",
  "preference_rule": "fastest" //opcional
}

3 - Por nome da transportadora + tipo de método

Este formato é um pouco mais específico do que apenas carrier_name porque também leva em conta o method_type da transportadora. Para listar os nomes das transportadoras e métodos disponíveis, use o endpoint Opções de entrega.

{
  "carrier_name": "TRANSPORTADORA-B",
  "method_type": "CONVENCIONAL",
  "schedule_at": "2025-03-28T15:08:00.000Z"
}

4 - Por logistic_id

Esta é a forma mais precisa e específica de solicitar uma coleta usando o objeto delivery. Existem duas formas de compor este objeto e ambas exigem o uso do endpoint de cotação.

Tanto o logistic_id quanto o method_id são retornados pelo endpoint de cotação. O logistic_id representa a transportadora e o method_type, enquanto o method_id reflete o prazo de entrega.

Existem dois tipos de method_id:

• O primeiro é D(n), normalmente usado pra métodos convencionais, onde n é o número de dias (ex.: uma transportadora com método convencional pode ter method_id D3, ou seja, entrega convencional em 3 dias).
• O segundo é EXP(n), usado pra métodos expressos, onde n é o tempo em minutos (ex.: uma transportadora com método Express pode ter method_id EXP120, ou seja, entrega expressa em 120 minutos).

Montando o objeto Logistics

Como este é o formato mais específico, é necessário informar o logistic_id junto com o method_id (prazo).

Alternativamente, você pode enviar apenas o logistic_id — o comportamento é equivalente ao formato 3 (Carrier Name + Method Type), com o desempate definido pelo preference_rule.

{
  "logistic_id": "9edc4f36-0444-47a7-a8e1-3ba0ba9deb45",
  "method_id": "D1",
  "schedule_at": "2025-03-28T15:08:00.000Z"
}

{
  "logistic_id": "9edc4f36-0444-47a7-a8e1-3ba0ba9deb45",
  "schedule_at": "2025-03-28T15:08:00.000Z",
  "preference_rule": "cheapest" //ou "fastest"
}