Objeto `delivery`

As previously discussed on the create-order-V2 (link to the page), the delivery object is a powerful tool that enables the automation of order dispatches during the order creation process.

There are four different ways to compose the delivery object, and we will explore them from the simplest and least detailed approach to the most specific option you can choose.

1 - Preference Rule (minimal Object)

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 - By Carrier Name

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": "VAPT-VUPT",
  "schedule_at": "2025-03-28T15:08:00.000Z",
  "preference_rule": "fastest" //optional
}

3 - By Carrier Name + Carrier Method Type

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": "VAPT-VUPT",
  "method_type": "CONVENCIONAL",
  "schedule_at": "2025-03-28T15:08:00.000Z"
}

4 - By Logistic_id

This is the most precise and specific way to request a pickup using the delivery object. There are two ways to compose this object, both of which require the use of the Quotation Endpoint.

Both the logistic_id and method_id can be retrieved from the quotation endpoint. The logistic_id represents the carrier and the method_type, while the method_id reflects the time frame for the delivery.

There are two types of method_ids:

• The first type is D(n), which is commonly used for conventional methods, where n represents the number of days (e.g. A carrier with a conventional method_type have a method_id D3, which means conventional delivery in 3 days).
• The second type is EXP(n), which is used for express methods, where n represents the time in minutes (e.g. A carrier with a Express method_type have a method_id EXP120 , which means express delivery in 120 minutes).

Assembling the Logistics Object

Because this delivery object is the most specific possible, it is necessary to provide the logistic_id along with the method_id (time frame).

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.

Quick disclaimer: In rare cases, the quotation_endpoint might return the method_id as a UUID. Don't worry about this, these methods are being deprecated but will continue to function for now. You can still use them without issue.

{
  "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" //fastest
}