Operação de etiquetas

Painel de acompanhamento das etiquetas do seller: lista com filtros, exportação em CSV e resumo por pedido.

A operação de etiquetas responde à pergunta do dia a dia: "quais etiquetas estão para vencer, quais ainda não foram emitidas, quais já imprimi?". Cada linha é um volume com a sua emissão atual.

Listar a operação

GET/api/v1/vendor/shipping/correios/operationsSeller

Lista a operação de etiquetas do seller

Parâmetros de consulta

qstring

Busca no número do pedido ou em qualquer código de rastreio do volume. Até 64 caracteres.

emission_statestring

not_issuedcreatinguncertainactivepdf_pendingcanceledpostedexpiredreplacederror

Estado da emissão: not_issued, creating, uncertain, active, pdf_pending, canceled, posted, expired, replaced ou error.

validitystring

expiringexpiredvalid

expiring (vence em até 3 dias), expired ou valid.

downloadedstring

yesno

yes se a etiqueta já foi baixada, no se nunca.

sortstring

validity

validity ordena pelo vencimento mais próximo. Sem ele, do mais novo para o mais antigo.

limitintegerpadrão: 25

Itens por página, de 1 a 100. Fora disso volta para 25.

offsetintegerpadrão: 0

Quantos itens pular (paginação por deslocamento).

Exemplo de requisição: listar

bash

curl "$BASE_URL/api/v1/vendor/shipping/correios/operations?validity=expiring&sort=validity" \
  -H "Authorization: Bearer $TOKEN"

Resposta: listar

200Linhas da operação

json

{
  "items": [
    {
      "volume_id": "4e5d6c7b-8a9f-4e1d-b2c3-a4b5c6d7e8f9",
      "order_id": "b4d2f0a8-6c1e-4b3d-9a7f-2e5c8d1b0a96",
      "order_number": "VD-20261001-0042",
      "vendor_id": "5f1c2d3e-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
      "package_index": 1,
      "service_code": "03298",
      "posting_id": "8f7e6d5c-4b3a-4291-a0b1-c2d3e4f5a6b7",
      "tracking_code": "AA123456789BR",
      "lifecycle_state": "active",
      "validity_expires_at": "2026-10-20T23:59:59Z",
      "label_downloaded_at": "2026-10-11T15:00:02Z",
      "label_downloaded_by": "Maria Souza",
      "validity_state": "valid",
      "validity_days_left": 9
    }
  ]
}

Campos da resposta

itemsarray

Volumes da página.

volume_id, order_id, order_numberstring

Volume e pedido.

package_indexinteger

Posição do volume no pedido.

service_codestring

Serviço Correios.

posting_id, tracking_codestring

Emissão atual e rastreio. Ausentes se não emitido.

lifecycle_statestring

Estado da emissão; not_issued se nunca emitiu.

validity_expires_atstring

Fim da validade, RFC 3339.

validity_statestring

validexpiringexpiredcanceledunknownposted

valid, expiring (3 dias ou menos), expired, canceled, unknown ou posted.

validity_days_leftinteger

Dias restantes, quando faz sentido.

pending_type, pending_message, recommended_action, pending_atstring

Pendência, texto em português e ação recomendada.

label_downloaded_at, label_downloaded_bystring

Última baixa da etiqueta e quem baixou.

Erros: listar

Status	Quando	Corpo de exemplo
400	Algum filtro com valor inválido.	`{"error":"Filtro inválido para a operação Correios."}`
401	Sem cabeçalho `Authorization`, ou token inválido ou expirado.	`{"error":"invalid or expired token"}`
403	O token não é de um usuário seller (por exemplo, é um token de administrador).	`{"error":"insufficient permissions"}`
403	O módulo `correios-shipping` está desligado na loja.	`{"error":"module_disabled","module":"correios-shipping"}`
403	O usuário não tem conta de seller.	`{"error":"no vendor account associated with this user"}`
403	O usuário não tem o privilégio necessário (qualquer privilégio de pedidos).	`{"error":"insufficient vendor privileges","privilege_required_any":["..."]}`
503	Falha ao consultar.	`{"error":"Não foi possível consultar a operação Correios."}`

Mesmos filtros da lista, sem paginação: devolve até 5000 linhas num arquivo CSV (UTF-8 com BOM, separador ;, datas no formato brasileiro e valores com vírgula decimal). Colunas: Pedido, Volume, Serviço, Código de rastreio, Estado da emissão, Validade, Dias restantes, Baixada em, Baixada por, Pendência, Frete declarado do pedido, Data de postagem, Data efetiva de entrega.

GET/api/v1/vendor/shipping/correios/operations/export.csvSeller

Exporta a operação de etiquetas em CSV

Parâmetros de consulta

qstring

Busca no número do pedido ou em qualquer código de rastreio do volume. Até 64 caracteres.

emission_statestring

not_issuedcreatinguncertainactivepdf_pendingcanceledpostedexpiredreplacederror

Estado da emissão: not_issued, creating, uncertain, active, pdf_pending, canceled, posted, expired, replaced ou error.

validitystring

expiringexpiredvalid

expiring (vence em até 3 dias), expired ou valid.

downloadedstring

yesno

yes se a etiqueta já foi baixada, no se nunca.

sortstring

validity

validity ordena pelo vencimento mais próximo. Sem ele, do mais novo para o mais antigo.

Exemplo de requisição: exportar

bash

curl "$BASE_URL/api/v1/vendor/shipping/correios/operations/export.csv?validity=expired" \
  -H "Authorization: Bearer $TOKEN" \
  -o correios-operacao.csv

Resposta: exportar

200Arquivo CSV

text

Content-Type: text/csv; charset=utf-8
Content-Disposition: attachment; filename="correios-operacao-20261011-1500.csv"

Pedido;Volume;Serviço;Código de rastreio;...
VD-20261001-0042;1;03298;AA123456789BR;...

Erros: exportar

Status	Quando	Corpo de exemplo
400	Algum filtro com valor inválido.	`{"error":"Filtro inválido para a operação Correios."}`
401	Sem cabeçalho `Authorization`, ou token inválido ou expirado.	`{"error":"invalid or expired token"}`
403	O token não é de um usuário seller (por exemplo, é um token de administrador).	`{"error":"insufficient permissions"}`
403	O módulo `correios-shipping` está desligado na loja.	`{"error":"module_disabled","module":"correios-shipping"}`
403	O usuário não tem conta de seller.	`{"error":"no vendor account associated with this user"}`
403	O usuário não tem o privilégio necessário (qualquer privilégio de pedidos).	`{"error":"insufficient vendor privileges","privilege_required_any":["..."]}`
503	Falha ao exportar.	`{"error":"Não foi possível exportar a operação Correios."}`

Resumo por pedido

Para mostrar, numa lista de pedidos, o rastreio, a validade da etiqueta e as datas de postagem e entrega. Pedidos sem volume Correios do seller não aparecem em items.

GET/api/v1/vendor/shipping/correios/orders/summarySeller

Resume o Correios de vários pedidos do seller

Parâmetros de consulta

order_idsstringobrigatório

Ids de pedidos (UUID) separados por vírgula, no máximo 100 distintos. Brancos e repetidos são ignorados.

Exemplo de requisição: resumo

bash

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

Resposta: resumo

200Resumos

json

{
  "items": [
    {
      "order_id": "b4d2f0a8-6c1e-4b3d-9a7f-2e5c8d1b0a96",
      "volumes_count": 1,
      "tracking_code": "AA123456789BR",
      "tracking_url": "https://rastreamento.correios.com.br/app/index.php?objetos=AA123456789BR",
      "tracking_codes": [
        "AA123456789BR"
      ],
      "emission_state": "active",
      "validity_expires_at": "2026-10-20T23:59:59Z",
      "validity_days_left": 9,
      "validity_state": "valid",
      "last_label_download_at": "2026-10-11T15:00:02Z",
      "last_label_download_by": "Maria Souza",
      "pending_type": "",
      "pending_message": "",
      "recommended_action": "",
      "automatic_renewal_count": 0,
      "posted_at": null,
      "delivered_at": null,
      "all_volumes_delivered": false,
      "volume_ids": [
        "4e5d6c7b-8a9f-4e1d-b2c3-a4b5c6d7e8f9"
      ]
    }
  ]
}

Campos da resposta

itemsarray

Um resumo por pedido que tem volume Correios.

order_iduuid

Pedido.

volumes_countinteger

Quantidade de volumes.

tracking_code, tracking_urlstring

Rastreio principal e o link dos Correios.

tracking_codesarray

Todos os códigos de rastreio.

emission_statestring

Estado da emissão do volume principal.

validity_expires_at, validity_days_left, validity_statevarious

Validade da etiqueta (mesmos valores de "Listar a operação").

last_label_download_at, last_label_download_bystring

Última baixa da etiqueta.

pending_type, pending_message, recommended_actionstring

Pendência, se houver.

automatic_renewal_countinteger

Renovações automáticas feitas.

posted_at, delivered_atstring | null

Datas de postagem e de entrega efetiva (do rastreio).

all_volumes_deliveredboolean

true quando todos os volumes foram entregues.

volume_idsarray

Ids dos volumes.

Erros: resumo

Status	Quando	Corpo de exemplo
400	Algum id não é UUID.	`{"error":"Identificador de pedido inválido."}`
400	Mais de 100 pedidos.	`{"error":"Informe no máximo 100 pedidos por consulta."}`
401	Sem cabeçalho `Authorization`, ou token inválido ou expirado.	`{"error":"invalid or expired token"}`
403	O token não é de um usuário seller (por exemplo, é um token de administrador).	`{"error":"insufficient permissions"}`
403	O módulo `correios-shipping` está desligado na loja.	`{"error":"module_disabled","module":"correios-shipping"}`
403	O usuário não tem conta de seller.	`{"error":"no vendor account associated with this user"}`
403	O usuário não tem o privilégio necessário (qualquer privilégio de pedidos).	`{"error":"insufficient vendor privileges","privilege_required_any":["..."]}`
503	Falha ao consultar.	`{"error":"Não foi possível consultar os dados Correios dos pedidos."}`

Veja também

API atual/Referência completa/Correios

Operação de etiquetas

Painel de acompanhamento das etiquetas do seller: lista com filtros, exportação em CSV e resumo por pedido.

Listar a operação

GET/api/v1/vendor/shipping/correios/operationsSeller

Lista a operação de etiquetas do seller

Parâmetros de consulta

qstring

Busca no número do pedido ou em qualquer código de rastreio do volume. Até 64 caracteres.

emission_statestring

not_issuedcreatinguncertainactivepdf_pendingcanceledpostedexpiredreplacederror

Estado da emissão: not_issued, creating, uncertain, active, pdf_pending, canceled, posted, expired, replaced ou error.

validitystring

expiringexpiredvalid

expiring (vence em até 3 dias), expired ou valid.

downloadedstring

yesno

yes se a etiqueta já foi baixada, no se nunca.

sortstring

validity

validity ordena pelo vencimento mais próximo. Sem ele, do mais novo para o mais antigo.

limitintegerpadrão: 25

Itens por página, de 1 a 100. Fora disso volta para 25.

offsetintegerpadrão: 0

Quantos itens pular (paginação por deslocamento).

Exemplo de requisição: listar

bash

curl "$BASE_URL/api/v1/vendor/shipping/correios/operations?validity=expiring&sort=validity" \
  -H "Authorization: Bearer $TOKEN"

Resposta: listar

200Linhas da operação

json

{
  "items": [
    {
      "volume_id": "4e5d6c7b-8a9f-4e1d-b2c3-a4b5c6d7e8f9",
      "order_id": "b4d2f0a8-6c1e-4b3d-9a7f-2e5c8d1b0a96",
      "order_number": "VD-20261001-0042",
      "vendor_id": "5f1c2d3e-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
      "package_index": 1,
      "service_code": "03298",
      "posting_id": "8f7e6d5c-4b3a-4291-a0b1-c2d3e4f5a6b7",
      "tracking_code": "AA123456789BR",
      "lifecycle_state": "active",
      "validity_expires_at": "2026-10-20T23:59:59Z",
      "label_downloaded_at": "2026-10-11T15:00:02Z",
      "label_downloaded_by": "Maria Souza",
      "validity_state": "valid",
      "validity_days_left": 9
    }
  ]
}

Campos da resposta

itemsarray

Volumes da página.

volume_id, order_id, order_numberstring

Volume e pedido.

package_indexinteger

Posição do volume no pedido.

service_codestring

Serviço Correios.

posting_id, tracking_codestring

Emissão atual e rastreio. Ausentes se não emitido.

lifecycle_statestring

Estado da emissão; not_issued se nunca emitiu.

validity_expires_atstring

Fim da validade, RFC 3339.

validity_statestring

validexpiringexpiredcanceledunknownposted

valid, expiring (3 dias ou menos), expired, canceled, unknown ou posted.

validity_days_leftinteger

Dias restantes, quando faz sentido.

pending_type, pending_message, recommended_action, pending_atstring

Pendência, texto em português e ação recomendada.

label_downloaded_at, label_downloaded_bystring

Última baixa da etiqueta e quem baixou.

Erros: listar

Status	Quando	Corpo de exemplo
400	Algum filtro com valor inválido.	`{"error":"Filtro inválido para a operação Correios."}`
401	Sem cabeçalho `Authorization`, ou token inválido ou expirado.	`{"error":"invalid or expired token"}`
403	O token não é de um usuário seller (por exemplo, é um token de administrador).	`{"error":"insufficient permissions"}`
403	O módulo `correios-shipping` está desligado na loja.	`{"error":"module_disabled","module":"correios-shipping"}`
403	O usuário não tem conta de seller.	`{"error":"no vendor account associated with this user"}`
403	O usuário não tem o privilégio necessário (qualquer privilégio de pedidos).	`{"error":"insufficient vendor privileges","privilege_required_any":["..."]}`
503	Falha ao consultar.	`{"error":"Não foi possível consultar a operação Correios."}`

Exportar em CSV

GET/api/v1/vendor/shipping/correios/operations/export.csvSeller

Exporta a operação de etiquetas em CSV

Parâmetros de consulta

qstring

Busca no número do pedido ou em qualquer código de rastreio do volume. Até 64 caracteres.

emission_statestring

not_issuedcreatinguncertainactivepdf_pendingcanceledpostedexpiredreplacederror

Estado da emissão: not_issued, creating, uncertain, active, pdf_pending, canceled, posted, expired, replaced ou error.

validitystring

expiringexpiredvalid

expiring (vence em até 3 dias), expired ou valid.

downloadedstring

yesno

yes se a etiqueta já foi baixada, no se nunca.

sortstring

validity

validity ordena pelo vencimento mais próximo. Sem ele, do mais novo para o mais antigo.

Exemplo de requisição: exportar

bash

curl "$BASE_URL/api/v1/vendor/shipping/correios/operations/export.csv?validity=expired" \
  -H "Authorization: Bearer $TOKEN" \
  -o correios-operacao.csv

Resposta: exportar

200Arquivo CSV

text

Content-Type: text/csv; charset=utf-8
Content-Disposition: attachment; filename="correios-operacao-20261011-1500.csv"

Pedido;Volume;Serviço;Código de rastreio;...
VD-20261001-0042;1;03298;AA123456789BR;...

Erros: exportar

Status	Quando	Corpo de exemplo
400	Algum filtro com valor inválido.	`{"error":"Filtro inválido para a operação Correios."}`
401	Sem cabeçalho `Authorization`, ou token inválido ou expirado.	`{"error":"invalid or expired token"}`
403	O token não é de um usuário seller (por exemplo, é um token de administrador).	`{"error":"insufficient permissions"}`
403	O módulo `correios-shipping` está desligado na loja.	`{"error":"module_disabled","module":"correios-shipping"}`
403	O usuário não tem conta de seller.	`{"error":"no vendor account associated with this user"}`
403	O usuário não tem o privilégio necessário (qualquer privilégio de pedidos).	`{"error":"insufficient vendor privileges","privilege_required_any":["..."]}`
503	Falha ao exportar.	`{"error":"Não foi possível exportar a operação Correios."}`

Resumo por pedido

Para mostrar, numa lista de pedidos, o rastreio, a validade da etiqueta e as datas de postagem e entrega. Pedidos sem volume Correios do seller não aparecem em items.

GET/api/v1/vendor/shipping/correios/orders/summarySeller

Resume o Correios de vários pedidos do seller

Parâmetros de consulta

order_idsstringobrigatório

Ids de pedidos (UUID) separados por vírgula, no máximo 100 distintos. Brancos e repetidos são ignorados.

Exemplo de requisição: resumo

bash

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

Resposta: resumo

200Resumos

json

{
  "items": [
    {
      "order_id": "b4d2f0a8-6c1e-4b3d-9a7f-2e5c8d1b0a96",
      "volumes_count": 1,
      "tracking_code": "AA123456789BR",
      "tracking_url": "https://rastreamento.correios.com.br/app/index.php?objetos=AA123456789BR",
      "tracking_codes": [
        "AA123456789BR"
      ],
      "emission_state": "active",
      "validity_expires_at": "2026-10-20T23:59:59Z",
      "validity_days_left": 9,
      "validity_state": "valid",
      "last_label_download_at": "2026-10-11T15:00:02Z",
      "last_label_download_by": "Maria Souza",
      "pending_type": "",
      "pending_message": "",
      "recommended_action": "",
      "automatic_renewal_count": 0,
      "posted_at": null,
      "delivered_at": null,
      "all_volumes_delivered": false,
      "volume_ids": [
        "4e5d6c7b-8a9f-4e1d-b2c3-a4b5c6d7e8f9"
      ]
    }
  ]
}

Campos da resposta

itemsarray

Um resumo por pedido que tem volume Correios.

order_iduuid

Pedido.

volumes_countinteger

Quantidade de volumes.

tracking_code, tracking_urlstring

Rastreio principal e o link dos Correios.

tracking_codesarray

Todos os códigos de rastreio.

emission_statestring

Estado da emissão do volume principal.

validity_expires_at, validity_days_left, validity_statevarious

Validade da etiqueta (mesmos valores de "Listar a operação").

last_label_download_at, last_label_download_bystring

Última baixa da etiqueta.

pending_type, pending_message, recommended_actionstring

Pendência, se houver.

automatic_renewal_countinteger

Renovações automáticas feitas.

posted_at, delivered_atstring | null

Datas de postagem e de entrega efetiva (do rastreio).

all_volumes_deliveredboolean

true quando todos os volumes foram entregues.

volume_idsarray

Ids dos volumes.

Erros: resumo

Status	Quando	Corpo de exemplo
400	Algum id não é UUID.	`{"error":"Identificador de pedido inválido."}`
400	Mais de 100 pedidos.	`{"error":"Informe no máximo 100 pedidos por consulta."}`
401	Sem cabeçalho `Authorization`, ou token inválido ou expirado.	`{"error":"invalid or expired token"}`
403	O token não é de um usuário seller (por exemplo, é um token de administrador).	`{"error":"insufficient permissions"}`
403	O módulo `correios-shipping` está desligado na loja.	`{"error":"module_disabled","module":"correios-shipping"}`
403	O usuário não tem conta de seller.	`{"error":"no vendor account associated with this user"}`
403	O usuário não tem o privilégio necessário (qualquer privilégio de pedidos).	`{"error":"insufficient vendor privileges","privilege_required_any":["..."]}`
503	Falha ao consultar.	`{"error":"Não foi possível consultar os dados Correios dos pedidos."}`