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

Consultar, renovar e cancelar emissão

Consulta o estado de uma pré-postagem nos Correios, renova uma vencida ou cancelada e cancela uma ativa.

Depois de emitida, a pré-postagem tem vida própria nos Correios: vence, é cancelada, é postada. Estas três ações mantêm a plataforma em sintonia. As três usam o id da emissão (o campo id de current_posting de um volume).

Consultar

Pergunta aos Correios o estado real da pré-postagem e atualiza a emissão. Não cria nem renova nada: é seguro chamar sempre que houver dúvida.

POST/api/v1/vendor/shipping/correios/postings/{postingId}/reconcileSeller

Consulta o estado de uma emissão nos Correios

Parâmetros de caminho

postingIduuidobrigatório
Id da emissão (campo id de current_posting).

Exemplo de requisição: consultar

bash
curl -X POST "$BASE_URL/api/v1/vendor/shipping/correios/postings/8f7e6d5c-4b3a-4291-a0b1-c2d3e4f5a6b7/reconcile" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

Resposta: consultar

200Estado atualizado
json
{
  "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
  },
  "decision": {
    "action": "preserve",
    "message": "Etiqueta válida preservada.",
    "clear_pending": true
  }
}

Campos da resposta

postingobject

A emissão já atualizada.

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.
decisionobject

O que a plataforma decidiu.

actionstring
preserverecover_documentrenewreconcileblock
O que a plataforma decidiu: preserve (nada a fazer), recover_document (baixar de novo o PDF), renew (emitir outra), reconcile (consultar de novo) ou block (exige ação humana).
pending_typestring
Código da pendência, quando há (por exemplo label_missing, already_posted, canceled_requires_human, provider_unknown).
messagestring
Explicação em português.
recommended_actionstring
Ação recomendada, em português.
clear_pendingboolean
Se a pendência anterior foi resolvida.

Erros: consultar

StatusQuandoCorpo de exemplo
409Não foi possível seguir (por exemplo objeto já postado, pedido sem elegibilidade, resposta ambígua dos Correios). O corpo traz error e o decision.{"error":"O objeto já foi postado e não pode ser reemitido.","decision":{"action":"block","pending_type":"already_posted","message":"O objeto já foi postado e não pode ser reemitido.","clear_pending":false}}
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":["..."]}

Renovar

Consulta os Correios e, se a pré-postagem venceu ou foi cancelada e o pedido ainda é elegível, emite uma nova (a antiga vira replaced). É também a única ação que destrava uma emissão cancelada, por ser uma decisão humana explícita. Se a etiqueta ainda é válida, nada é emitido (preserve).

POST/api/v1/vendor/shipping/correios/postings/{postingId}/renewSeller

Renova uma emissão vencida ou cancelada

Parâmetros de caminho

postingIduuidobrigatório
Id da emissão (campo id de current_posting).

Exemplo de requisição: renovar

bash
curl -X POST "$BASE_URL/api/v1/vendor/shipping/correios/postings/8f7e6d5c-4b3a-4291-a0b1-c2d3e4f5a6b7/renew" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

Resposta: renovar

200Emissão preservada ou renovada
json
{
  "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
  },
  "decision": {
    "action": "preserve",
    "message": "Etiqueta válida preservada.",
    "clear_pending": true
  }
}

Campos da resposta

postingobject

A emissão já atualizada.

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.
decisionobject

O que a plataforma decidiu.

actionstring
preserverecover_documentrenewreconcileblock
O que a plataforma decidiu: preserve (nada a fazer), recover_document (baixar de novo o PDF), renew (emitir outra), reconcile (consultar de novo) ou block (exige ação humana).
pending_typestring
Código da pendência, quando há (por exemplo label_missing, already_posted, canceled_requires_human, provider_unknown).
messagestring
Explicação em português.
recommended_actionstring
Ação recomendada, em português.
clear_pendingboolean
Se a pendência anterior foi resolvida.

Erros: renovar

StatusQuandoCorpo de exemplo
409Não foi possível seguir (por exemplo objeto já postado, pedido sem elegibilidade, resposta ambígua dos Correios). O corpo traz error e o decision.{"error":"O objeto já foi postado e não pode ser reemitido.","decision":{"action":"block","pending_type":"already_posted","message":"O objeto já foi postado e não pode ser reemitido.","clear_pending":false}}
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":["..."]}
Gera um novo código de rastreio

Quando renova, a nova emissão tem outro código de rastreio e outra etiqueta. A etiqueta antiga já impressa deixa de servir.

Cancelar

Cancela a pré-postagem nos Correios sem emitir outra. Responde 204, sem corpo. A emissão fica bloqueada para reemissão automática até que alguém use Renovar.

POST/api/v1/vendor/shipping/correios/postings/{postingId}/cancelSeller

Cancela uma emissão

Parâmetros de caminho

postingIduuidobrigatório
Id da emissão (campo id de current_posting).

Exemplo de requisição: cancelar

bash
curl -X POST "$BASE_URL/api/v1/vendor/shipping/correios/postings/8f7e6d5c-4b3a-4291-a0b1-c2d3e4f5a6b7/cancel" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

Resposta: cancelar

204Cancelada
text
sem corpo / no body

Erros: cancelar

StatusQuandoCorpo de exemplo
409Não pôde cancelar (por exemplo já postada, ou não é sua).{"error":"failed to cancel Correios preposting","detail":"..."}
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":["..."]}
Objeto postado não cancela

Depois de postado nos Correios, o cancelamento deixa de ser possível por aqui.

Veja também

  • Documentos da emissão
  • Volumes e emissão
Anterior
Volumes e emissão
Próxima
Documentos da emissão
Nesta página
  • Consultar
  • Exemplo de requisição: consultar
  • Resposta: consultar
  • Erros: consultar
  • Renovar
  • Exemplo de requisição: renovar
  • Resposta: renovar
  • Erros: renovar
  • Cancelar
  • Exemplo de requisição: cancelar
  • Resposta: cancelar
  • Erros: cancelar
  • Veja também