Estrutura do pacote

Um Pacote (Package) representa um container de logística que agrupa itens de uma venda para rastreamento e entrega. Cada venda pode gerar N pacotes (dependendo da estratégia de empacotamento).

{
  "id": "698b8a825eaf8de7c5af8de7",
  "saleId": "698b8a805eaf8de7c5af1cb9",
  "status": "shipped",
  "trackingCode": "AA123456789BR",
  "trackingUrl": "https://tracking.correios.com.br/?code=AA123456789BR",
  "carrierKind": "sedex",
  "carrierId": "698b8a805eaf8de7c5af1cd0",
  "community": "test",
  "notifyEmail": true,
  "reversed": false,
  "expectedDeliveryDate": "2026-05-20T19:44:02.402Z",
  "pickUp": false,
  "statusChangedAt": "2026-02-10T19:44:03.149Z",
  "statusTransitions": [
    {
      "status": "ready_to_pack",
      "createdAt": "2026-02-10T19:44:03.149Z"
    },
    {
      "status": "packed",
      "createdAt": "2026-02-11T10:30:15.200Z"
    },
    {
      "status": "shipped",
      "createdAt": "2026-02-12T08:15:22.450Z"
    }
  ],
  "createdAt": "2026-02-10T19:44:02.328Z",
  "updatedAt": "2026-02-12T20:46:11.133Z",
  "items": [...],
  "carrier": {...},
  "sale": {...},
  "pickUpLocation": null
}

Campos principais

Campo	Tipo	Descrição
`id`	`string`	ID único do pacote
`saleId`	`string`	Identificador da venda associada
`status`	`string`	Status atual do pacote. Valores possíveis: `ready_to_pack`, `packed`, `shipped`, `out_for_delivery`, `ready_to_pick_up`, `delivered`, `delivery_attempted`, `canceled`
`trackingCode`	`string`	Código de rastreamento fornecido pela transportadora
`trackingUrl`	`string`	URL pública de rastreamento da transportadora
`carrierKind`	`string`	Tipo de transportadora. Ex: `sedex`, `pac`, `loggi`, `correios`
`carrierId`	`string`	ID único da transportadora
`community`	`string`	Comunidade (tenant) do pacote
`notifyEmail`	`boolean`	Indica se o cliente deve ser notificado por email sobre mudanças de status (padrão: `true`)
`reversed`	`boolean`	Indica se o pacote foi revertido/cancelado (padrão: `false`)
`expectedDeliveryDate`	`string (ISO 8601) \| null`	Data esperada de entrega. Caso não informada, `null`
`pickUp`	`boolean \| null`	Indica se será retirada no local de pickup. Caso não informado, `null`
`pickUpLocation`	`object \| null`	Endereço do local de retirada. Obrigatório se `pickUp=true`. Caso não aplicável, `null`
`statusChangedAt`	`string (ISO 8601)`	Data e hora da última mudança de status
`statusTransitions`	`array<object>`	Histórico completo de transições de status (ver abaixo)
`createdAt`	`string (ISO 8601)`	Data e hora de criação
`updatedAt`	`string (ISO 8601)`	Data e hora da última atualização
`items`	`array<object>`	Lista de produtos vinculados ao pacote (ver abaixo)
`carrier`	`object`	Informações da transportadora (desnormalizado para performance)
`sale`	`object`	Informações resumidas da venda (desnormalizado para performance)

`statusTransitions`

Histórico de todas as transições de status do pacote.

"statusTransitions": [
  {
    "status": "ready_to_pack",
    "createdAt": "2026-02-10T19:44:03.149Z"
  },
  {
    "status": "packed",
    "createdAt": "2026-02-11T10:30:15.200Z",
    "note": "Pacote empacotado e pronto para envio"
  },
  {
    "status": "shipped",
    "createdAt": "2026-02-12T08:15:22.450Z",
    "note": "Enviado para Correios"
  }
]

Campo	Tipo	Descrição
`status`	`string`	Nome do status atingido
`createdAt`	`string (ISO 8601)`	Data e hora da transição de status
`note`	`string \| null`	Nota opcional associada à mudança de status. Caso não informada, `null`

`pickUpLocation`

Informações sobre o local de retirada do pacote.

"pickUpLocation": {
  "address": "Rua das Flores",
  "number": "123",
  "address2": "Apto 42",
  "district": "Centro",
  "city": "São Paulo",
  "state": "SP",
  "country": "BR",
  "code": "01310100"
}

Campo	Tipo	Descrição
`address`	`string \| null`	Logradouro do local de retirada. Caso não informado, `null`
`number`	`string \| null`	Número do endereço. Caso não informado, `null`
`address2`	`string \| null`	Complemento do endereço. Caso não informado, `null`
`district`	`string \| null`	Bairro. Caso não informado, `null`
`city`	`string \| null`	Cidade. Caso não informado, `null`
`state`	`string \| null`	Estado (UF). Caso não informado, `null`
`country`	`string`	País no formato ISO 3166-1 alpha-2. Ex: `BR`
`code`	`string \| null`	CEP. Caso não informado, `null`

`items`

Lista de produtos vinculados ao pacote. Nota, esse objeto items não é o mesmo objeto que obtemos de uma rota /items/{id}

"items": [
  {
    "lineItemId": "698b8a815eaf8de7c5af1f7b",
    "itemKind": "product",
    "name": "Camiseta Premium",
    "caption": "Branco | Tamanho M",
    "quantity": 2,
    "variantId": "0001",
    "price": {
      "amount": 10000,
      "currency": "BRL"
    },
    "subtotal": {
      "amount": 20000,
      "currency": "BRL"
    },
    "media": {
      "url": "https://cdn.layers.digital/uploads/.../camiseta.png",
      "path": "/uploads/.../camiseta.png",
      "mime": "image/png",
      "width": 456,
      "height": 783,
      "size": 379264,
      "name": "camiseta.png",
      "orientation": null
    }
  }
]

Campo	Tipo	Descrição
`lineItemId`	`string`	Identificador único do item de linha
`itemKind`	`string`	Tipo do item. Valores possíveis: `product`, `service`
`name`	`string`	Nome do item
`caption`	`string`	Descrição curta do item com atributos. Ex: `Branco \| Tamanho M`
`quantity`	`integer`	Quantidade do item no pacote
`variantId`	`string`	Identificador da variante do produto
`price.amount`	`integer`	Valor unitário em centavos
`price.currency`	`string`	Moeda no formato ISO 4217. Ex: `BRL`
`subtotal.amount`	`integer`	Valor total do item em centavos (price × quantity)
`subtotal.currency`	`string`	Moeda no formato ISO 4217
`media.url`	`string \| null`	URL pública da imagem do item. Caso não informada, `null`
`media.path`	`string \| null`	Caminho interno da imagem. Caso não informado, `null`
`media.mime`	`string`	Tipo MIME da imagem. Ex: `image/png`, `image/jpeg`
`media.width`	`integer \| null`	Largura da imagem em pixels. Caso não informada, `null`
`media.height`	`integer \| null`	Altura da imagem em pixels. Caso não informada, `null`
`media.size`	`integer \| null`	Tamanho do arquivo em bytes. Caso não informado, `null`
`media.name`	`string`	Nome do arquivo da imagem
`media.orientation`	`string \| null`	Orientação da imagem. Caso não informada, `null`

`carrier`

Informações da transportadora (desnormalizado para performance).

"carrier": {
  "name": "Correios"
}

Campo	Tipo	Descrição
`name`	`string`	Nome da transportadora

`sale`

Informações resumidas da venda associada ao pacote (desnormalizado para performance).

"sale": {
  "code": "LP-P444M-LANGG",
  "customer": {
    "name": "John Doe"
  },
  "channel": {
    "_id": "698b8a805eaf8de7c5af1cd1",
    "name": "Loja Online",
    "template": {
      "cover": {
        "url": "https://cdn.layers.digital/uploads/.../template-cover.png",
        "path": "/uploads/.../template-cover.png",
        "mime": "image/png",
        "width": 1200,
        "height": 600,
        "size": 245678,
        "name": "template-cover.png",
        "orientation": null
      }
    }
  }
}

Campo	Tipo	Descrição
`code`	`string`	Código legível da venda. Ex: `LP-P444M-LANGG`
`customer.name`	`string`	Nome completo do cliente
`channel._id`	`string`	ID único do canal de vendas
`channel.name`	`string`	Nome do canal de vendas
`channel.template.cover.url`	`string \| null`	URL pública da imagem de capa do template. Caso não informada, `null`
`channel.template.cover.path`	`string \| null`	Caminho interno da imagem. Caso não informado, `null`
`channel.template.cover.mime`	`string`	Tipo MIME da imagem
`channel.template.cover.width`	`integer \| null`	Largura da imagem em pixels. Caso não informada, `null`
`channel.template.cover.height`	`integer \| null`	Altura da imagem em pixels. Caso não informada, `null`
`channel.template.cover.size`	`integer \| null`	Tamanho do arquivo em bytes. Caso não informado, `null`
`channel.template.cover.name`	`string`	Nome do arquivo da imagem
`channel.template.cover.orientation`	`string \| null`	Orientação da imagem. Caso não informada, `null`

Statuses

Ordenados por prioridade (mais importante primeiro):

Valores possíveis: delivered, canceled, delivery_attempted, out_for_delivery, ready_to_pick_up, shipped, packed, ready_to_pack

Status	Descrição
`ready_to_pack`	Pronto para empacotar - status inicial do pacote
`packed`	Empacotado e pronto para envio
`shipped`	Enviado/em trânsito com a transportadora
`out_for_delivery`	Saiu para entrega (último local de onde saiu)
`ready_to_pick_up`	Pronto para retirada no local de pickup
`delivered`	Entregue com sucesso
`delivery_attempted`	Tentativa de entrega realizada (pode ter falhado)
`canceled`	Pacote cancelado

Guias

Marketplace integrado

Referência

Referências

Cobranças

Entregas

Formulários

Inventários

Itens

Kits

Vendas

Webhooks

Guia

Referência

Estrutura do pacote

Campos principais

`statusTransitions`

`pickUpLocation`

`items`

`carrier`

`sale`

Statuses

Referência

Cobranças

Entregas

Formulários

Inventários

Itens

Kits

Vendas

Guia

Referência

Estrutura do pacote ​

Campos principais ​

statusTransitions ​

pickUpLocation ​

items ​

carrier ​

sale ​

Statuses ​

Estrutura do pacote

Campos principais

`statusTransitions`

`pickUpLocation`

`items`

`carrier`

`sale`

Statuses