❗️
Optional fields
This payload mirrors the order information provided by the seller. Therefore, some fields must not appear or be null when the information was not provided since some fields are optional in the Order API
Read the order documentation to understand about the required fields

📘
Fields unit of measurement

amount: cents

weight: grams

height: cm

width: cm

length: cm

cubic_volume: cm3

🚧
carrier_additional_information

keep_prescription: whether the courier must get the prescription with the patient when delivering (most common for pharma)

thermolabile: whether the product items among the purchase are thermolabile and require special treatments

pos_terminal_required: whether the courier must bring with him the pos terminal

return_to_origin: whether the courier assigned to this order should get back to origin

observation: string field for comments or notes regarding the delivery

🚧
logistic_data.pickup_verification
Optional block sent only when the seller × carrier integration has pickup pincode enabled. The carrier must inspect pincode_owner to decide which flow to run.

pincode: true when pickup pincode is required for this delivery.

pincode_owner: "carrier" — traditional model, the carrier generates the PIN and echoes it back via at-pickup-point / collecting-delivery events using collect_verification_code. "abbiamo" — driver to seller pincode model, Abbiamo owns the PIN and sends it pre-generated in pincode_value. The carrier must display it to the driver in its own app and wait for a PICKUP_PIN_VALIDATION_REQUEST webhook to unlock the collection (see Pickup pin validation request).

pincode_value: 4-digit string, unique per delivery. Present only when pincode_owner = "abbiamo". Must be shown to the driver in the carrier's app exactly as received.

Step-by-step walkthroughs of each flow (operator/driver perspective, common pitfalls): Pickup pincode — seller-to-driver flow (traditional) and Pickup pincode — driver-to-seller flow (Abbiamo-owned).

Whenever a seller requests a delivery to a carrier, this event is triggered. A payload with order details and the delivery method information is shown below:

{
  "event_type": "DELIVERY_REQUEST",
  "seller": {
    "seller_name": "Go Go Fruits",
    "seller_id": "eb064ede-08f3-470e-a37c-5b796a17cca8",
    "seller_document_number": "88399480000156",
    "seller_group_id": "b7d56bca-606e-405e-bf4d-9b0a3291b61d",
    "seller_contacts": [ // optinal array. It depends wheter the seller has it configured or not
      {
        "name": "Eduardo Silveira",
        "phone": "21999999999",
        "phone_country_code": "55",
        "email": "silveiradudu@gmail.com"
      }
    ],
  },
  "carrier": {
    "name": "CARRIER_BRAND_NAME",
    "max_dispatched_time": "14:00:00-03",
    "expected_delivery_date": "2022-12-22T23:59:00.000-03:00",
    "total_expected_delivery_price": 1200,
    "method": {
      "external_id": "name/id",
      "id": "e84b2788-5b78-40dd-95cf-75807f70aaaa",
      "name": "CARRIER_BRAND_NAME_D0",
      "type": "D0"
    }
  },
  "logistic_data": {
    "headers": {
      "Authorization": "Bearer xxx"
    },
    "pickup_verification": { // optional · see callout above
      "pincode": true,
      "pincode_owner": "abbiamo", // "carrier" | "abbiamo"
      "pincode_value": "8745" // present only when pincode_owner = "abbiamo"
    }
  },
  "source_address": {
    "zip_code": "04029904",
    "country": "BRA",
    "state": "SP",
    "city": "São Paulo",
    "neighborhood": "Indianópolis",
    "street": "Avenida Ibirapuera",
    "street_number": "3407",
    "complement": null,
    "reference": null,
    "latitude": -23.52045997445427,
    "longitude": -46.438805678513575
  },
  "make_route": false,
  "courier_must_return": true,
  "route_id": null, // exists when make_route is true
  "route_name": null, // exists when make_route is true
  "deliveries": [
    {
      "invoice_number": "example_invoice_number_1",
      "invoice_access_key": "42081183123141000200550010000007010046403276",
      "invoice_created_at": "2023-06-22T18:59:37.024Z",
      "delivery_id": "851dc274-e090-4881-8f3c-5b660cecf059",
      "order_number": "example_carrier_payload_1",
      "tracking": "a-vBGOS",
      "amount": 6909,
      "expected_delivery_price": 1000,
      "carrier_additional_information": {
        "keep_prescription": true,
        "thermolabile": true,
        "pos_terminal_required": true,
        "return_to_origin": true,
        "observation": "pegar maquina com Walmir no caixa"
      },
      "volumes": [
        {
          "id": "4754cd99-3378-4e6c-bdaf-53db23ac5a4f",
          "weight": 0,
          "height": null,
          "width": null,
          "length": null,
          "cubic_volume": 0
        }
      ],
      "customer": {
        "name": "Machado de Assis",
        "phone": "911111111",
        "phone_country_code": "55",
        "document_number": "07073877014"
      },
      "destination_address": {
        "zip_code": "08050360",
        "country": "BRA",
        "state": "SP",
        "city": "São Paulo",
        "neighborhood": "Jardim das Camélias",
        "street": "Rua Doutor Alfredo Sales",
        "street_number": "931",
        "complement": "sala 2",
        "reference": null,
        "latitude": -23.834499518193947,
        "longitude": -45.37406370734008
      }
    }
  ]
}

{
  "event_type": "DELIVERY_REQUEST",
  "seller": {
    "seller_name": "Go Go Fruits",
    "seller_id": "eb064ede-08f3-470e-a37c-5b796a17cca8",
    "seller_document_number": "88399480000156",
    "seller_group_id": "b7d56bca-606e-405e-bf4d-9b0a3291b61d",
    "seller_contacts": [
      {
        "name": "Eduardo Silveira",
        "phone": "21999999999",
        "phone_country_code": "55",
        "email": "silveiradudu@gmail.com"
      }
    ],
  },
  "carrier": {
    "name": "CARRIER_BRAND_NAME",
    "max_dispatched_time": "14:00:00-03",
    "expected_delivery_date": "2022-12-22T23:59:00.000-03:00",
    "total_expected_delivery_price": 1200,
    "method": {
      "id": "e84b2788-5b78-40dd-95cf-75807f70aaaa",
      "name": "CARRIER_BRAND_NAME_D0",
      "type": "D0"
    }
  },
  "logistic_data": {
    "headers": {
      "Authorization": "Bearer xxx"
    },
    "pickup_verification": { // optional · see callout above
      "pincode": true,
      "pincode_owner": "abbiamo", // "carrier" | "abbiamo"
      "pincode_value": "8745" // present only when pincode_owner = "abbiamo"
    }
  },
  "source_address": {
    "zip_code": "04029904",
    "country": "BRA",
    "state": "SP",
    "city": "São Paulo",
    "neighborhood": "Indianópolis",
    "street": "Avenida Ibirapuera",
    "street_number": "3407",
    "complement": null,
    "reference": null,
    "latitude": -23.52045997445427,
    "longitude": -46.438805678513575
  },
  "make_route": true,
  "courier_must_return": false,
  "route_id": "7ed34417-b51f-4d98-bec8-3ccb41290575", // exists when make_route is true
  "route_name": "GPT-2LkRo", // exists when make_route is true
  "deliveries": [
    {
      "invoice_number": "example_invoice_number_1",
      "invoice_access_key": "42081183123141000200550010000007010046403276",
      "invoice_created_at": "2023-06-22T18:59:37.024Z",
      "delivery_id": "851dc274-e090-4881-8f3c-5b660cecf059",
      "order_number": "example_carrier_payload_1",
      "tracking": "a-vBGOS",
      "amount": 6909,
      "expected_delivery_price": 1000,
      "carrier_additional_information": {
        "keep_prescription": true,
        "thermolabile": true,
        "pos_terminal_required": true,
        "return_to_origin": true,
        "observation": "pegar maquina com Walmir no caixa"
      },
      "volumes": [
        {
          "id": "4754cd99-3378-4e6c-bdaf-53db23ac5a4f",
          "weight": 0,
          "height": null,
          "width": null,
          "length": null,
          "cubic_volume": 0
        }
      ],
      "customer": {
        "name": "Machado de Assis",
        "phone": "911111111",
        "phone_country_code": "55",
        "document_number": "07073877014"
      },
      "destination_address": {
        "zip_code": "08050360",
        "country": "BRA",
        "state": "SP",
        "city": "São Paulo",
        "neighborhood": "Jardim das Camélias",
        "street": "Rua Doutor Alfredo Sales",
        "street_number": "931",
        "complement": "sala 2",
        "reference": null,
        "latitude": -23.834499518193947,
        "longitude": -45.37406370734008
      }
    }
  ]
}