Emitir etiquetas pelo MCP

Pré-requisitos

A loja precisa de acesso ativo, contrato próprio dos Correios autenticado e conexão MCP com permissão de lojista. A ferramenta deve aparecer no catálogo retornado pelo servidor.

Prepare os dados

Informe o código do serviço, peso do pacote em gramas, remetente e destinatário. Envie as dimensões em centímetros ou use a única embalagem cadastrada da loja; se houver nenhuma ou mais de uma, informe as dimensões. Confira nomes, endereços e dados do pedido antes da emissão.

Para o documento fiscal, escolha um dos caminhos:

• NF-e: envie invoiceKey com a chave de acesso completa de 44 dígitos. Espaços, quebras de linha, pontos, hífens e barras são removidos antes da validação. A chave não é cortada nem completada automaticamente. Se houver declaredItems junto com uma chave válida, a emissão usa a NF-e e ignora os itens.
• Declaração de conteúdo eletrônica (DC-e): omita invoiceKey e envie ao menos um item em declaredItems, com descrição, quantidade e valor unitário.

Uma chave informada, porém inválida, retorna invalid_invoice_key antes da emissão. Confira a chave completa na NF-e. Não mude para DC-e automaticamente por causa desse erro.

Os códigos contratuais de serviço usados na etiqueta não são os mesmos identificadores de apresentação da cotação. Por exemplo, não envie o texto SEDEX no lugar do código de produto exigido por serviceCode.

Consultar todos os campos de generate_label.

Crie a pré-postagem

O agente chama generate_label com os dados conferidos. Essa é uma operação real: ela cria uma pré-postagem nos Correios. Ela pode retornar:

• prepostagemId, identificador da pré-postagem;
• trackingCode, código de rastreio;
• labelPdfBase64, quando o PDF estiver pronto;
• reason, quando houver falha ou o processamento ainda não estiver concluído.

Se o PDF ainda não estiver pronto

Ao receber label_pdf_timeout com prepostagemId, aguarde e use get_label_pdf com o identificador retornado. Não repita a criação para tentar obter o PDF: isso pode criar outra pré-postagem.

Se não tiver o prepostagemId ou não souber se a emissão foi concluída, use diagnose_label_issue com o supportCode devolvido por generate_label. A ferramenta mostra o estado da tentativa e a ação indicada. Quando a pré-postagem estiver confirmada, recover_label_pdf obtém o PDF sem nova emissão. Ausência de registro não prova que nenhuma etiqueta foi criada: confira nos Correios antes de emitir novamente.

{
  "prepostagemId": "ID_RETORNADO_NA_EMISSAO"
}

O PDF também pode ser entregue no conteúdo MCP como recurso embutido application/pdf. A forma de exibição depende do cliente.

Trate falhas de negócio

invalid_invoice_key pede a chave completa de 44 dígitos; a emissão não começa nesse caso. declaration_required pede ao menos um item quando não há NF-e. own_contract_required pede configuração do contrato. prepostagem_rejected indica recusa pelos Correios. label_not_printable indica que o rótulo ainda não pode ser impresso. Examine a mensagem e o status antes de uma nova tentativa.

Em caso de timeout de rede com resultado desconhecido, confira o histórico da operação antes de reenviar. Este portal não promete idempotência na criação de etiquetas.

Referência de get_label_pdf · diagnose_label_issue · recover_label_pdf