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

Lotes de documentos

Reúne as etiquetas (ou outros documentos) de vários volumes num único ZIP.

Para imprimir as etiquetas do dia de uma vez, crie um lote: a plataforma baixa o documento de cada volume, junta num ZIP e devolve um resumo do que entrou e do que foi pulado. O número máximo de volumes por lote é definido pela loja.

Criar o lote

POST/api/v1/vendor/shipping/correios/document-batchesSeller

Cria um lote de documentos

Corpo da requisição

posting_idsarray
Ids de emissões (strings UUID). Use este ou volume_ids.
volume_idsarray
Ids de volumes: usa a emissão atual de cada um e pula os que ainda não foram emitidos. Se enviado, posting_ids é ignorado.
document_typestringpadrão: label
labeldeclarationar
label, declaration ou ar.

Exemplo de requisição: criar

bash
curl -X POST "$BASE_URL/api/v1/vendor/shipping/correios/document-batches" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "volume_ids": [
      "4e5d6c7b-8a9f-4e1d-b2c3-a4b5c6d7e8f9"
    ],
    "document_type": "label"
  }'

Resposta: criar

201Lote criado
json
{
  "id": "2c3d4e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f",
  "state": "partial",
  "requested_count": 2,
  "delivered_count": 1,
  "skipped_count": 1,
  "failed_count": 0,
  "items": [
    {
      "posting_id": "8f7e6d5c-4b3a-4291-a0b1-c2d3e4f5a6b7",
      "status": "delivered",
      "file_name": "AA123456789BR.pdf",
      "tracking_code": "AA123456789BR",
      "order_id": "b4d2f0a8-6c1e-4b3d-9a7f-2e5c8d1b0a96",
      "order_number": "VD-20261001-0042",
      "volume_id": "4e5d6c7b-8a9f-4e1d-b2c3-a4b5c6d7e8f9",
      "package_index": 1
    },
    {
      "posting_id": "",
      "status": "skipped",
      "message": "Este volume ainda não possui pré-postagem.",
      "order_id": "b4d2f0a8-6c1e-4b3d-9a7f-2e5c8d1b0a96",
      "volume_id": "7b6a5948-3727-4f16-9a05-f4e3d2c1b0a9",
      "package_index": 2,
      "pending_type": "not_issued"
    }
  ],
  "created_at": "2026-10-11T15:00:00Z",
  "completed_at": "2026-10-11T15:00:02Z"
}

Campos da resposta

iduuid
Id do lote.
statestring
completepartialempty
complete (todos entregues), partial (alguns pulados ou com falha) ou empty (nenhum).
requested_count, delivered_count, skipped_count, failed_countinteger
Quantos volumes foram pedidos, entregues no ZIP, pulados e com falha.
itemsarray
Um item por volume: status (delivered, skipped ou failed), message, file_name, tracking_code, order_number, volume_id, package_index, pending_type, recommended_action e, se já foi baixado antes, previously_downloaded_at e previously_downloaded_by.
created_at, completed_atstring
Quando o lote foi criado e concluído, RFC 3339.

Erros: criar

StatusQuandoCorpo de exemplo
400Corpo que não é JSON.{"error":"invalid request body"}
409Nenhum id, tipo inválido, lote acima do limite da loja, módulo desligado para o fluxo ou nada selecionável. O detail explica.{"error":"failed to create Correios document batch","detail":"Correios batch exceeds the configured limit of 50 volumes"}
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":["..."]}
O ZIP é baixado à parte

A resposta é só o resumo. Para o arquivo, chame o archive com o id do lote.

Consultar o lote

GET/api/v1/vendor/shipping/correios/document-batches/{batchId}Seller

Consulta um lote de documentos

Parâmetros de caminho

batchIduuidobrigatório
Id do lote.

Exemplo de requisição: consultar

bash
curl "$BASE_URL/api/v1/vendor/shipping/correios/document-batches/2c3d4e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f" \
  -H "Authorization: Bearer $TOKEN"

Resposta: consultar

200Lote
json
{
  "id": "2c3d4e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f",
  "state": "partial",
  "requested_count": 2,
  "delivered_count": 1,
  "skipped_count": 1,
  "failed_count": 0,
  "items": [
    {
      "posting_id": "8f7e6d5c-4b3a-4291-a0b1-c2d3e4f5a6b7",
      "status": "delivered",
      "file_name": "AA123456789BR.pdf",
      "tracking_code": "AA123456789BR",
      "order_id": "b4d2f0a8-6c1e-4b3d-9a7f-2e5c8d1b0a96",
      "order_number": "VD-20261001-0042",
      "volume_id": "4e5d6c7b-8a9f-4e1d-b2c3-a4b5c6d7e8f9",
      "package_index": 1
    },
    {
      "posting_id": "",
      "status": "skipped",
      "message": "Este volume ainda não possui pré-postagem.",
      "order_id": "b4d2f0a8-6c1e-4b3d-9a7f-2e5c8d1b0a96",
      "volume_id": "7b6a5948-3727-4f16-9a05-f4e3d2c1b0a9",
      "package_index": 2,
      "pending_type": "not_issued"
    }
  ],
  "created_at": "2026-10-11T15:00:00Z",
  "completed_at": "2026-10-11T15:00:02Z"
}

Campos da resposta

iduuid
Id do lote.
statestring
completepartialempty
complete (todos entregues), partial (alguns pulados ou com falha) ou empty (nenhum).
requested_count, delivered_count, skipped_count, failed_countinteger
Quantos volumes foram pedidos, entregues no ZIP, pulados e com falha.
itemsarray
Um item por volume: status (delivered, skipped ou failed), message, file_name, tracking_code, order_number, volume_id, package_index, pending_type, recommended_action e, se já foi baixado antes, previously_downloaded_at e previously_downloaded_by.
created_at, completed_atstring
Quando o lote foi criado e concluído, RFC 3339.

Erros: consultar

StatusQuandoCorpo de exemplo
404Lote inexistente ou de outro seller.{"error":"Correios document batch not found"}
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":["..."]}

Baixar o ZIP

GET/api/v1/vendor/shipping/correios/document-batches/{batchId}/archiveSeller

Baixa o ZIP de um lote

Parâmetros de caminho

batchIduuidobrigatório
Id do lote.

Exemplo de requisição: baixar

bash
curl "$BASE_URL/api/v1/vendor/shipping/correios/document-batches/2c3d4e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f/archive" \
  -H "Authorization: Bearer $TOKEN" \
  -o lote-correios.zip

Resposta: baixar

200Arquivo ZIP
text
Content-Type: application/zip
Content-Disposition: attachment; filename="correios-lote-2c3d4e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f.zip"

(bytes do ZIP / ZIP bytes)

Erros: baixar

StatusQuandoCorpo de exemplo
404Lote inexistente, de outro seller, ou sem arquivo.{"error":"Correios batch archive not found"}
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":["..."]}

Veja também

  • Documentos da emissão
  • Operação de etiquetas
Anterior
Documentos da emissão
Próxima
Operação de etiquetas
Nesta página
  • Criar o lote
  • Exemplo de requisição: criar
  • Resposta: criar
  • Erros: criar
  • Consultar o lote
  • Exemplo de requisição: consultar
  • Resposta: consultar
  • Erros: consultar
  • Baixar o ZIP
  • Exemplo de requisição: baixar
  • Resposta: baixar
  • Erros: baixar
  • Veja também