generate_label · Meu Ecommerce Developers

Gerar etiqueta

Ferramenta do Meu Ecommerce MCP, na capacidade de Etiquetas e postagens. A loja é vinculada à credencial da conexão remota. Confira os requisitos de permissão e disponibilidade na página da capacidade.

Operação real

Esta ferramenta cria uma pré-postagem nos Correios e exige contrato próprio autenticado. Revise os dados antes da emissão. Se já houver prepostagemId, recupere o PDF sem repetir a criação.

Documento fiscal

Envie invoiceKey com a chave completa da NF-e ou, sem ela, ao menos um item em declaredItems para DC-e. Se a chave informada for inválida, a emissão é bloqueada com invalid_invoice_key. Veja o guia de etiquetas.

Entrada

Campo	Tipo	Obrigatório no objeto	Descrição
`instanceId`	string	Não	Merchant/store id. Ignored on authenticated servers (the merchant comes from the API key); used only on local/unauthenticated servers.
`serviceCode`	string	Sim	Correios product code, e.g. '03220' (SEDEX) or '03298' (PAC).
`weightGrams`	number	Sim	Package weight in grams. Maior que 0.
`dimensions`	object	Não	Package dimensions in centimeters. Optional: when omitted, the store's own registered packaging box is used if it has exactly one; ask the merchant for dimensions when the store has none or more than one box registered (the call fails with reason dimensions_required_no_box / dimensions_required_multiple_boxes).
`dimensions.comprimento`	number	Sim	Length in cm. Maior que 0.
`dimensions.largura`	number	Sim	Width in cm. Maior que 0.
`dimensions.altura`	number	Sim	Height in cm. Maior que 0.
`objectFormat`	"1" / "2" / "3"	Não	Object format: '1' envelope, '2' package/box (default), '3' roll.
`sender`	object	Sim	Remetente (sender / store).
`sender.nome`	string	Sim	Full name or company name.
`sender.cpfCnpj`	string	Não	CPF or CNPJ, digits only.
`sender.telefone`	string	Não	Phone number.
`sender.email`	string	Não	Email address.
`sender.endereco`	object	Sim	—
`sender.endereco.cep`	string	Sim	CEP (8 digits; dashes/spaces ignored).
`sender.endereco.logradouro`	string	Sim	Street name.
`sender.endereco.numero`	string	Sim	Street number.
`sender.endereco.bairro`	string	Sim	Neighborhood.
`sender.endereco.cidade`	string	Sim	City.
`sender.endereco.uf`	string	Sim	Two-letter state, e.g. 'SP'.
`sender.endereco.complemento`	string	Não	Address complement (apt, etc.).
`recipient`	object	Sim	Destinatário (recipient / customer).
`recipient.nome`	string	Sim	Full name or company name.
`recipient.cpfCnpj`	string	Não	CPF or CNPJ, digits only.
`recipient.telefone`	string	Não	Phone number.
`recipient.email`	string	Não	Email address.
`recipient.endereco`	object	Sim	—
`recipient.endereco.cep`	string	Sim	CEP (8 digits; dashes/spaces ignored).
`recipient.endereco.logradouro`	string	Sim	Street name.
`recipient.endereco.numero`	string	Sim	Street number.
`recipient.endereco.bairro`	string	Sim	Neighborhood.
`recipient.endereco.cidade`	string	Sim	City.
`recipient.endereco.uf`	string	Sim	Two-letter state, e.g. 'SP'.
`recipient.endereco.complemento`	string	Não	Address complement (apt, etc.).
`invoiceKey`	string	Não	Complete NF-e access key (44 digits). Spaces, dots, hyphens and slashes are ignored. When supplied, emits with NF-e instead of DC-e; never invent or complete missing digits.
`declaredItems`	array	Não	Declaração de conteúdo — required when invoiceKey is omitted (at least one item). Ignored when a valid NF-e is supplied. Mín. 1 itens.
`declaredItems[].conteudo`	string	Sim	Item description.
`declaredItems[].quantidade`	integer	Sim	Quantity. Maior que 0.
`declaredItems[].valor`	number	Sim	Declared unit value in BRL. Mínimo: 0.

Saída estruturada

Campo	Tipo	Obrigatório no objeto	Descrição
`supportCode`	string	Não	Código de atendimento para diagnose_label_issue.
`recoveryAction`	"manual_review" / "recover_label_pdf" / "correct_cause"	Não	—
`journalUnavailable`	boolean	Não	—
`prepostagemId`	string	Não	Correios pré-postagem id. Pass it to get_label_pdf to fetch the PDF later if it wasn't ready.
`trackingCode`	string	Não	Código de rastreamento, once the pré-postagem exists.
`status`	string	Não	Correios pré-postagem status.
`labelPdfBase64`	string	Não	Base64-encoded label PDF, once ready.
`labelPdfUrl`	string	Não	Clickable link to download the label PDF — share this with the merchant/customer in chat. Works even before the PDF finishes rendering (it waits and streams it once ready).
`reason`	string	Não	Why the label wasn't (fully) produced.
`actionUrl`	string	Não	When set (e.g. reason=subscription_required), send the merchant here to finish setup.

Tratamento da resposta

Examine reason e actionUrl quando presentes. As ferramentas de etiqueta podem retornar uma pré-postagem criada antes de o PDF estar disponível. Consulte o fluxo de etiquetas e erros e limites.

Contrato JSON

{
  "type": "object",
  "properties": {
    "instanceId": {
      "type": "string",
      "description": "Merchant/store id. Ignored on authenticated servers (the merchant comes from the API key); used only on local/unauthenticated servers."
    },
    "serviceCode": {
      "type": "string",
      "description": "Correios product code, e.g. '03220' (SEDEX) or '03298' (PAC)."
    },
    "weightGrams": {
      "type": "number",
      "exclusiveMinimum": 0,
      "description": "Package weight in grams."
    },
    "dimensions": {
      "type": "object",
      "properties": {
        "comprimento": {
          "type": "number",
          "exclusiveMinimum": 0,
          "description": "Length in cm."
        },
        "largura": {
          "type": "number",
          "exclusiveMinimum": 0,
          "description": "Width in cm."
        },
        "altura": {
          "type": "number",
          "exclusiveMinimum": 0,
          "description": "Height in cm."
        }
      },
      "required": [
        "comprimento",
        "largura",
        "altura"
      ],
      "additionalProperties": false,
      "description": "Package dimensions in centimeters. Optional: when omitted, the store's own registered packaging box is used if it has exactly one; ask the merchant for dimensions when the store has none or more than one box registered (the call fails with reason dimensions_required_no_box / dimensions_required_multiple_boxes)."
    },
    "objectFormat": {
      "type": "string",
      "enum": [
        "1",
        "2",
        "3"
      ],
      "description": "Object format: '1' envelope, '2' package/box (default), '3' roll."
    },
    "sender": {
      "type": "object",
      "properties": {
        "nome": {
          "type": "string",
          "description": "Full name or company name."
        },
        "cpfCnpj": {
          "type": "string",
          "description": "CPF or CNPJ, digits only."
        },
        "telefone": {
          "type": "string",
          "description": "Phone number."
        },
        "email": {
          "type": "string",
          "description": "Email address."
        },
        "endereco": {
          "type": "object",
          "properties": {
            "cep": {
              "type": "string",
              "description": "CEP (8 digits; dashes/spaces ignored)."
            },
            "logradouro": {
              "type": "string",
              "description": "Street name."
            },
            "numero": {
              "type": "string",
              "description": "Street number."
            },
            "bairro": {
              "type": "string",
              "description": "Neighborhood."
            },
            "cidade": {
              "type": "string",
              "description": "City."
            },
            "uf": {
              "type": "string",
              "minLength": 2,
              "maxLength": 2,
              "description": "Two-letter state, e.g. 'SP'."
            },
            "complemento": {
              "type": "string",
              "description": "Address complement (apt, etc.)."
            }
          },
          "required": [
            "cep",
            "logradouro",
            "numero",
            "bairro",
            "cidade",
            "uf"
          ],
          "additionalProperties": false
        }
      },
      "required": [
        "nome",
        "endereco"
      ],
      "additionalProperties": false,
      "description": "Remetente (sender / store)."
    },
    "recipient": {
      "type": "object",
      "properties": {
        "nome": {
          "type": "string",
          "description": "Full name or company name."
        },
        "cpfCnpj": {
          "type": "string",
          "description": "CPF or CNPJ, digits only."
        },
        "telefone": {
          "type": "string",
          "description": "Phone number."
        },
        "email": {
          "type": "string",
          "description": "Email address."
        },
        "endereco": {
          "type": "object",
          "properties": {
            "cep": {
              "type": "string",
              "description": "CEP (8 digits; dashes/spaces ignored)."
            },
            "logradouro": {
              "type": "string",
              "description": "Street name."
            },
            "numero": {
              "type": "string",
              "description": "Street number."
            },
            "bairro": {
              "type": "string",
              "description": "Neighborhood."
            },
            "cidade": {
              "type": "string",
              "description": "City."
            },
            "uf": {
              "type": "string",
              "minLength": 2,
              "maxLength": 2,
              "description": "Two-letter state, e.g. 'SP'."
            },
            "complemento": {
              "type": "string",
              "description": "Address complement (apt, etc.)."
            }
          },
          "required": [
            "cep",
            "logradouro",
            "numero",
            "bairro",
            "cidade",
            "uf"
          ],
          "additionalProperties": false
        }
      },
      "required": [
        "nome",
        "endereco"
      ],
      "additionalProperties": false,
      "description": "Destinatário (recipient / customer)."
    },
    "invoiceKey": {
      "type": "string",
      "description": "Complete NF-e access key (44 digits). Spaces, dots, hyphens and slashes are ignored. When supplied, emits with NF-e instead of DC-e; never invent or complete missing digits."
    },
    "declaredItems": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "conteudo": {
            "type": "string",
            "description": "Item description."
          },
          "quantidade": {
            "type": "integer",
            "exclusiveMinimum": 0,
            "description": "Quantity."
          },
          "valor": {
            "type": "number",
            "minimum": 0,
            "description": "Declared unit value in BRL."
          }
        },
        "required": [
          "conteudo",
          "quantidade",
          "valor"
        ],
        "additionalProperties": false
      },
      "minItems": 1,
      "description": "Declaração de conteúdo — required when invoiceKey is omitted (at least one item). Ignored when a valid NF-e is supplied."
    }
  },
  "required": [
    "serviceCode",
    "weightGrams",
    "sender",
    "recipient"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Baixar todos os schemas.

Referência gerada dos schemas do servidor. Os nomes de campos e as descrições técnicas originais são preservados.

Gerar etiqueta

Entrada

Saída estruturada

Tratamento da resposta

Contrato JSON

Nesta página