VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa/Correios

Volumes e emissão

Lista os volumes (pacotes) de um pedido e emite a pré-postagem de um volume nos Correios.

Listar volumes do pedido

Devolve os volumes do pedido que pertencem ao seller, cada um com a emissão atual e o histórico. Um pedido de outro seller, ou sem Correios, devolve lista vazia.

GET/api/v1/vendor/shipping/correios/orders/{orderId}/volumesSeller

Lista os volumes Correios de um pedido do seller

Parâmetros de caminho

orderIduuidobrigatório
Id do pedido.

Exemplo de requisição: listar

bash
curl "$BASE_URL/api/v1/vendor/shipping/correios/orders/b4d2f0a8-6c1e-4b3d-9a7f-2e5c8d1b0a96/volumes" \
  -H "Authorization: Bearer $TOKEN"

Resposta: listar

200Volumes
json
{
  "items": [
    {
      "id": "4e5d6c7b-8a9f-4e1d-b2c3-a4b5c6d7e8f9",
      "order_id": "b4d2f0a8-6c1e-4b3d-9a7f-2e5c8d1b0a96",
      "vendor_id": "5f1c2d3e-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
      "quote_snapshot_id": "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
      "shipping_method_id": "3a7d9e10-2b4c-4f6a-9c1d-5e8f7a6b4c21",
      "service_code": "03298",
      "acceptance_profile_id": "5d4c3b2a-1f0e-4d9c-8b7a-6f5e4d3c2b1a",
      "acceptance_profile_version": 3,
      "package_index": 1,
      "package_snapshot": {
        "items": [],
        "weight_grams": 1350,
        "length_mm": 300,
        "width_mm": 200,
        "height_mm": 100,
        "declared_value_cents": 18900,
        "box_name": "Caixa M"
      },
      "state": "open",
      "logistics_state": "pending",
      "created_at": "2026-10-11T13:30:00Z",
      "updated_at": "2026-10-11T14:00:05Z",
      "current_posting": {
        "id": "8f7e6d5c-4b3a-4291-a0b1-c2d3e4f5a6b7",
        "volume_id": "4e5d6c7b-8a9f-4e1d-b2c3-a4b5c6d7e8f9",
        "revision": 1,
        "provider_preposting_id": "PR1234567890",
        "tracking_code": "AA123456789BR",
        "provider_state": "ACTIVE",
        "lifecycle_state": "active",
        "validity_expires_at": "2026-10-20T23:59:59Z",
        "automatic_renewal_count": 0,
        "create_attempts": 1,
        "reconcile_attempts": 0,
        "document_attempts": 1,
        "manual_cancel_block": false,
        "has_label": true,
        "has_declaration": false,
        "has_ar": false,
        "created_at": "2026-10-11T14:00:00Z",
        "updated_at": "2026-10-11T14:00:05Z",
        "documents": [
          {
            "type": "label",
            "available": true,
            "downloads": []
          }
        ],
        "can_renew": false,
        "can_cancel": true,
        "can_download": true
      },
      "can_issue": false
    }
  ]
}

Campos da resposta

itemsarray

Volumes do pedido.

iduuid
Id do volume (pacote físico).
order_iduuid
Pedido do volume.
vendor_iduuid
Seller dono.
quote_snapshot_iduuid
Cotação do checkout que originou o volume.
shipping_method_iduuid
Forma de envio escolhida.
service_codestring
Código do serviço Correios contratado (ex.: 03298).
package_indexinteger
Posição do volume no pedido (1, 2, 3...).
package_snapshotobject
Dados físicos do volume quando foi cotado: weight_grams, length_mm, width_mm, height_mm, declared_value_cents (centavos), box_name e items. Use só para exibir.
statestring
Estado do volume.
logistics_statestring
Estado logístico, atualizado pelo rastreio.
shipment_iduuid
Envio do pedido ligado ao volume, quando existe.
current_postingobject

A emissão atual (campos em Emissões). Ausente se nunca emitiu.

iduuid
Id da emissão (pré-postagem).
volume_iduuid
Volume ao qual a emissão pertence.
revisioninteger
Número da emissão no volume: 1 é a primeira; uma renovação cria a 2 e assim por diante.
provider_preposting_idstring
Id da pré-postagem nos Correios. Ausente até criar.
tracking_codestring
Código de rastreio do objeto (ex.: AA123456789BR). Ausente até criar.
provider_statestring
Estado informado pelos Correios.
lifecycle_statestring
creatinguncertainactivepdf_pendingcanceledpostedexpiredreplacederror
Estado da emissão na plataforma: creating, uncertain, active, pdf_pending, canceled, posted, expired, replaced ou error.
validity_expires_atstring
Até quando a pré-postagem vale (RFC 3339). Depois disso o objeto não pode mais ser postado sem renovar. Ausente quando desconhecido.
automatic_renewal_countinteger
Quantas vezes a plataforma renovou sozinha.
create_attempts, reconcile_attempts, document_attemptsinteger
Contadores de tentativas.
next_attempt_atstring
Próxima tentativa automática, quando há uma agendada.
manual_cancel_blockboolean
true quando um cancelamento pede confirmação humana antes de qualquer reemissão.
pending_type, pending_code, pending_message, recommended_actionstring
Pendência que exige atenção, em português, e a ação recomendada. Ausentes quando não há pendência.
has_label, has_declaration, has_arboolean
Quais documentos existem: etiqueta, declaração de conteúdo e aviso de recebimento.
label_downloaded_atstring
Última vez que a etiqueta foi baixada.
replaced_by_iduuid
Emissão que substituiu esta. Ausente se não foi substituída.
documentsarray
Por tipo (label, declaration, ar): available e a lista downloads (quem baixou e quando).
eventsarray
Linha do tempo da emissão. Aparece no detalhe do volume.
can_renew, can_cancel, can_downloadboolean
O que a interface pode oferecer agora para esta emissão.
created_at, updated_atstring
Criação e última alteração, RFC 3339.
historyarray
Emissões anteriores do volume (renovadas ou canceladas).
can_issueboolean
true quando faz sentido mostrar "Emitir": não há emissão viva e a anterior (se houve) falhou antes de chegar aos Correios.
created_at, updated_atstring
Criação e alteração, RFC 3339.

Erros: listar

StatusQuandoCorpo de exemplo
401Sem cabeçalho Authorization, ou token inválido ou expirado.{"error":"invalid or expired token"}
403O token não é de um usuário seller (por exemplo, é um token de administrador).{"error":"insufficient permissions"}
403O módulo correios-shipping está desligado na loja.{"error":"module_disabled","module":"correios-shipping"}
403O usuário não tem conta de seller.{"error":"no vendor account associated with this user"}
403O usuário não tem o privilégio necessário (qualquer privilégio de pedidos).{"error":"insufficient vendor privileges","privilege_required_any":["..."]}
503Falha ao consultar.{"error":"failed to list Correios volumes","detail":"..."}

Emitir a pré-postagem

Cria a pré-postagem do volume nos Correios usando as credenciais do seller e devolve a emissão com o código de rastreio. Só funciona se o pedido estiver num status que a loja configurou como "pode emitir" e o volume ainda não tiver uma emissão viva. O corpo é vazio.

POST/api/v1/vendor/shipping/correios/volumes/{volumeId}/prepostingSeller

Emite a pré-postagem de um volume

Parâmetros de caminho

volumeIduuidobrigatório
Id do volume.

Exemplo de requisição: emitir

bash
curl -X POST "$BASE_URL/api/v1/vendor/shipping/correios/volumes/4e5d6c7b-8a9f-4e1d-b2c3-a4b5c6d7e8f9/preposting" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

Resposta: emitir

201Emissão criada
json
{
  "id": "8f7e6d5c-4b3a-4291-a0b1-c2d3e4f5a6b7",
  "volume_id": "4e5d6c7b-8a9f-4e1d-b2c3-a4b5c6d7e8f9",
  "revision": 1,
  "provider_preposting_id": "PR1234567890",
  "tracking_code": "AA123456789BR",
  "provider_state": "ACTIVE",
  "lifecycle_state": "active",
  "validity_expires_at": "2026-10-20T23:59:59Z",
  "automatic_renewal_count": 0,
  "create_attempts": 1,
  "reconcile_attempts": 0,
  "document_attempts": 1,
  "manual_cancel_block": false,
  "has_label": true,
  "has_declaration": false,
  "has_ar": false,
  "created_at": "2026-10-11T14:00:00Z",
  "updated_at": "2026-10-11T14:00:05Z",
  "documents": [
    {
      "type": "label",
      "available": true,
      "downloads": []
    }
  ],
  "can_renew": false,
  "can_cancel": true,
  "can_download": true
}

Campos da resposta

iduuid
Id da emissão (pré-postagem).
volume_iduuid
Volume ao qual a emissão pertence.
revisioninteger
Número da emissão no volume: 1 é a primeira; uma renovação cria a 2 e assim por diante.
provider_preposting_idstring
Id da pré-postagem nos Correios. Ausente até criar.
tracking_codestring
Código de rastreio do objeto (ex.: AA123456789BR). Ausente até criar.
provider_statestring
Estado informado pelos Correios.
lifecycle_statestring
creatinguncertainactivepdf_pendingcanceledpostedexpiredreplacederror
Estado da emissão na plataforma: creating, uncertain, active, pdf_pending, canceled, posted, expired, replaced ou error.
validity_expires_atstring
Até quando a pré-postagem vale (RFC 3339). Depois disso o objeto não pode mais ser postado sem renovar. Ausente quando desconhecido.
automatic_renewal_countinteger
Quantas vezes a plataforma renovou sozinha.
create_attempts, reconcile_attempts, document_attemptsinteger
Contadores de tentativas.
next_attempt_atstring
Próxima tentativa automática, quando há uma agendada.
manual_cancel_blockboolean
true quando um cancelamento pede confirmação humana antes de qualquer reemissão.
pending_type, pending_code, pending_message, recommended_actionstring
Pendência que exige atenção, em português, e a ação recomendada. Ausentes quando não há pendência.
has_label, has_declaration, has_arboolean
Quais documentos existem: etiqueta, declaração de conteúdo e aviso de recebimento.
label_downloaded_atstring
Última vez que a etiqueta foi baixada.
replaced_by_iduuid
Emissão que substituiu esta. Ausente se não foi substituída.
documentsarray
Por tipo (label, declaration, ar): available e a lista downloads (quem baixou e quando).
eventsarray
Linha do tempo da emissão. Aparece no detalhe do volume.
can_renew, can_cancel, can_downloadboolean
O que a interface pode oferecer agora para esta emissão.
created_at, updated_atstring
Criação e última alteração, RFC 3339.

Erros: emitir

StatusQuandoCorpo de exemplo
409Qualquer recusa: o volume não existe ou não é seu, o pedido não está num status de emissão, os dados do destinatário ou do pacote estão incompletos, o volume já tem emissão, ou os Correios recusaram. O detail explica em português.{"error":"failed to create Correios preposting","detail":"O volume já possui uma emissão. Use Consultar ou Renovar conforme o estado."}
401Sem cabeçalho Authorization, ou token inválido ou expirado.{"error":"invalid or expired token"}
403O token não é de um usuário seller (por exemplo, é um token de administrador).{"error":"insufficient permissions"}
403O módulo correios-shipping está desligado na loja.{"error":"module_disabled","module":"correios-shipping"}
403O usuário não tem conta de seller.{"error":"no vendor account associated with this user"}
403O usuário não tem o privilégio necessário (vendor_orders, vendor_manage_orders, vendor_manage_fulfillments).{"error":"insufficient vendor privileges","privilege_required_any":["..."]}
Tudo é 409

Esta rota responde 409 para qualquer falha, até volume inexistente. Leia o detail para saber a causa. Se o lifecycle_state ficar uncertain, não emita de novo: use Consultar primeiro.

Veja também

  • Consultar, renovar e cancelar
  • Documentos da emissão
  • Caixas de embalagem
Anterior
Credenciais dos Correios
Próxima
Consultar, renovar e cancelar emissão
Nesta página
  • Listar volumes do pedido
  • Exemplo de requisição: listar
  • Resposta: listar
  • Erros: listar
  • Emitir a pré-postagem
  • Exemplo de requisição: emitir
  • Resposta: emitir
  • Erros: emitir
  • Veja também