# Autenticação e credenciais (/docs/autenticacao)
## Entenda o acesso [#entenda-o-acesso]
O dashboard, a API REST e o Meu Ecommerce MCP fazem parte da mesma plataforma. O acesso a uma operação depende de três fatores:
| Fator | O que determina | Exemplo |
| --------------- | ------------------------------------------------------------- | ---------------------------------------------------------------------- |
| Credencial | Como a conexão se identifica e a qual loja está vinculada | Chave da loja ou autorização OAuth |
| Permissão | Quais operações essa conexão pode executar | `pk_…` permite cotação; rastreamento REST exige `mk_…` |
| Disponibilidade | Se a conta e a configuração atendem aos requisitos do recurso | A emissão de etiquetas exige contrato próprio dos Correios autenticado |
Uma credencial válida não garante acesso a todos os recursos. Consulte os requisitos da capacidade e a referência da operação.
## API REST [#api-rest]
Envie a credencial no cabeçalho da requisição:
```http
Authorization: Bearer SUA_CHAVE
```
| Credencial | Onde usar | Acesso |
| -------------- | ---------------------- | --------------------------------------------------- |
| Pública `pk_…` | Navegador ou backend | Somente cotação |
| Secreta `mk_…` | Backend | Cotação e rastreio REST; ferramentas MCP do lojista |
| OAuth | Cliente MCP compatível | Acesso autorizado à loja pelo fluxo de login |
A chave pública foi desenhada para a cotação no navegador. Isso não elimina limites de uso: evite chamadas por tecla e proteja sua experiência contra requisições repetidas.
Guarde a chave secreta em variáveis de ambiente do backend. Não a inclua em bundles, URLs, mensagens de erro ou repositórios. Se uma chave for exposta, solicite a substituição pelo canal de suporte; este contrato não documenta endpoint público de rotação.
## Identificação da loja [#identificação-da-loja]
O servidor associa cada chave à loja correspondente. Enviar outro `instanceId` não muda a loja autenticada. Uma chave de plataforma tem permissões diferentes e não substitui a credencial do lojista.
## MCP com OAuth [#mcp-com-oauth]
O servidor remoto usa descoberta OAuth e o fluxo Authorization Code com PKCE. Um cliente compatível abre o login para o lojista autorizar a conexão. Consulte [como conectar ao Meu Ecommerce MCP](/docs/mcp/conectar).
## Disponibilidade na conta [#disponibilidade-na-conta]
Autenticação e acesso ao plano são verificações distintas. Uma credencial válida pode receber `subscription_required` se a loja não tiver acesso ativo. Quando a resposta fornecer `actionUrl`, direcione o lojista para concluir a configuração ou assinatura.
## CORS [#cors]
`/v1/rates` oferece CORS para cotação no navegador. `/v1/tracking` deve ser consumido pelo backend e exige `mk_…`. Não utilize um proxy público genérico para encaminhar essa chave.
# Changelog (/docs/changelog)
## 18 de setembro de 2026 — Documentação por capacidades [#18-de-setembro-de-2026--documentação-por-capacidades]
* Navegação por fretes e cotações, rastreamento, etiquetas e postagens.
* Apresentação unificada do dashboard, da API REST e do Meu Ecommerce MCP.
* Rastreamento identificado como capacidade relacionada ao Meu Rastreio.
* Requisitos de credencial, permissão e disponibilidade separados na documentação.
* Endpoints, ferramentas e contratos técnicos preservados; o antigo endereço `/docs/frete` redireciona para a capacidade de fretes.
Esta atualização reorganiza a documentação e não altera o comportamento dos serviços.
## 17 de setembro de 2026 — Primeira edição do portal [#17-de-setembro-de-2026--primeira-edição-do-portal]
* Portal Meu Ecommerce Developers com guias em português e busca.
* Referência REST de cotação e rastreio baseada no OpenAPI 3.1.
* Referência das quatro ferramentas MCP do lojista, extraída dos schemas do servidor.
* Guias de autenticação, checkout, rastreio, etiquetas e Base44.
* Exportação em Markdown e índices para agentes.
Esta entrada registra a publicação do conteúdo no repositório do portal. Não representa uma nova versão dos serviços ou a data de lançamento comercial das APIs.
# O ecossistema Meu Ecommerce (/docs/ecossistema)
## Uma marca, diferentes formas de usar [#uma-marca-diferentes-formas-de-usar]
O Meu Ecommerce reúne produtos que resolvem etapas da operação e da conversão de lojas brasileiras. Os apps oferecem experiências prontas para lojistas. A plataforma permite que desenvolvedores usem as capacidades disponíveis em suas próprias aplicações e agentes.
Para integrar, o ponto de entrada é o Meu Ecommerce: um [dashboard](https://app.meuecommerce.com.br/start), uma [API REST](/docs/api) e um [servidor MCP](/docs/mcp).
## Produtos e capacidades [#produtos-e-capacidades]
| Produto | Capacidade na plataforma | Interfaces documentadas |
| ---------------- | ---------------------------------------------------- | ----------------------------------------------- |
| Meu Frete | [Fretes e cotações](/docs/capacidades/fretes) | REST e MCP |
| Meu Frete | [Etiquetas e postagens](/docs/capacidades/etiquetas) | MCP |
| Meu Rastreio | [Rastreamento](/docs/capacidades/rastreamento) | REST e MCP |
| Meu Parcelamento | Exibição e simulação de parcelas no app | Sem integração pública documentada neste portal |
| Meu Desconto Pix | Desconto no checkout no app | Sem integração pública documentada neste portal |
O acesso a cada operação depende da credencial, das permissões e da disponibilidade na conta. Os recursos e as condições de um app instalado não devem ser presumidos como idênticos aos da integração direta.
## Apps e integrações próprias [#apps-e-integrações-próprias]
Para instalar uma experiência pronta, consulte a página do produto. Para construir, escolha a capacidade e siga sua referência REST ou MCP. A consulta de dados de rastreamento, por exemplo, não instala automaticamente os componentes visuais do app Meu Rastreio.
* [Meu Frete](https://www.meuecommerce.com.br/pt/meu-frete)
* [Meu Rastreio](https://www.meuecommerce.com.br/pt/meu-rastreio)
* [Meu Parcelamento](https://www.meuecommerce.com.br/pt/meu-parcelamento)
* [Meu Desconto Pix](https://www.meuecommerce.com.br/pt/meu-desconto-pix)
[Central de ajuda para lojistas](https://www.meuecommerce.com.br/pt/ajuda) · [Sobre o Meu Ecommerce](https://www.meuecommerce.com.br/pt/quem-somos)
# Erros e limites (/docs/erros-e-limites)
## Erros REST [#erros-rest]
```json
{
"error": {
"code": "invalid_api_key",
"message": "Chave de API inválida."
}
}
```
`actionUrl` pode aparecer dentro de `error` quando o lojista precisa concluir uma ação.
| Status | Exemplos de código | Ação |
| ------ | --------------------------------------------------------------------------------------------- | ----------------------------------------- |
| 400 | `invalid_json`, `invalid_body`, `invalid_destination_cep`, `too_many_items`, `too_many_codes` | Corrija a requisição |
| 401 | `missing_api_key`, `invalid_api_key` | Revise o header e a credencial |
| 403 | `secret_key_required`, `wrong_key_scope` | Use a credencial com o escopo correto |
| 402 | `subscription_required` | Confira o acesso ao plano e a `actionUrl` |
| 404 | `merchant_not_found` | Confira a loja vinculada à credencial |
| 405 | `method_not_allowed` | Use o método documentado |
| 413 | `payload_too_large` | Reduza o corpo JSON |
| 429 | `rate_limited` | Aguarde antes de tentar novamente |
| 502 | `quote_failed`, `track_failed` | Trate a indisponibilidade temporária |
## Respostas vazias [#respostas-vazias]
`200` não garante cotação disponível. Examine `rates`, `reason` e `actionUrl`. Exemplos incluem `no_services_enabled` e `correios_auth_failed`, que pedem revisão da configuração da loja.
No MCP, examine `structuredContent.reason` e o texto em `content`, mesmo quando a chamada ao protocolo foi concluída.
## Limites da implementação REST [#limites-da-implementação-rest]
| Limite | Valor |
| --------------------------------- | -------------------------------------------- |
| Itens por cotação | Até 50 linhas de itens |
| Códigos por rastreamento | Até 50 códigos |
| Corpo JSON | Até 32.000 bytes |
| Limitador configurado no servidor | 60 chamadas por 60 segundos, por loja e rota |
O limitador atual é mantido em memória por instância de servidor. O valor descreve a configuração da implementação, não uma garantia de quota global ou de capacidade. Sua integração deve sempre tratar `429`.
## Novas tentativas [#novas-tentativas]
Para cotação e rastreio, use espera progressiva com variação e um número máximo de tentativas em falhas transitórias. Não repita automaticamente erros de configuração ou autenticação.
`requestId` pode ajudar a correlacionar uma cotação. A implementação não documenta garantia de deduplicação por esse campo.
Na emissão de etiquetas, uma nova tentativa pode criar outra pré-postagem. Se já recebeu um identificador, use [get\_label\_pdf](/docs/mcp/ferramentas/get-label-pdf) para recuperar o PDF.
# Visão geral da plataforma (/docs)
## Uma plataforma para sua integração [#uma-plataforma-para-sua-integração]
Conecte sua aplicação ou seu agente às capacidades do Meu Ecommerce. Use o [dashboard](https://app.meuecommerce.com.br/start) para acessar sua conta e configurar a loja, a **API REST** para requisições HTTP e o **Meu Ecommerce MCP** para ferramentas de agentes.
A documentação é organizada pelo que você quer construir. Fretes, rastreamento e etiquetas fazem parte da mesma plataforma; cada operação informa a credencial e a configuração necessárias.
## Escolha seu ponto de partida [#escolha-seu-ponto-de-partida]
## Capacidades disponíveis [#capacidades-disponíveis]
| Capacidade | API REST | Meu Ecommerce MCP |
| ---------------------------------------------------- | -------------------------------------- | ---------------------------------- |
| [Fretes e cotações](/docs/capacidades/fretes) | `POST /v1/rates` | `get_shipping_rates` |
| [Rastreamento](/docs/capacidades/rastreamento) | `POST /v1/tracking` | `track_shipment` |
| [Etiquetas e postagens](/docs/capacidades/etiquetas) | Sem endpoint público no contrato atual | `generate_label` e `get_label_pdf` |
## Credencial, permissão e disponibilidade [#credencial-permissão-e-disponibilidade]
A **credencial** identifica a conexão e a loja. A **permissão** determina as operações que essa conexão pode executar. A **disponibilidade** depende do acesso da conta, da configuração da loja e da habilitação do recurso.
Uma conexão válida não libera automaticamente todas as operações. Por exemplo, a chave pública permite cotação, enquanto o rastreamento REST exige a chave secreta no backend. A emissão de etiquetas exige contrato próprio dos Correios autenticado.
[Entenda autenticação e acesso](/docs/autenticacao).
## Os produtos por trás das capacidades [#os-produtos-por-trás-das-capacidades]
Meu Frete oferece os recursos de cotação e etiquetas; Meu Rastreio oferece os recursos de rastreamento. Para integrar, utilize as interfaces comuns documentadas aqui. Conheça a relação entre os apps e a plataforma em [nosso ecossistema](/docs/ecossistema).
# Documentação para agentes (/docs/para-agentes)
## Formatos disponíveis [#formatos-disponíveis]
* [llms.txt](/llms.txt): índice da documentação.
* [llms-full.txt](/llms-full.txt): conteúdo completo em texto.
* [OpenAPI](/openapi.json): contrato das rotas REST.
* [Schemas MCP](/mcp-tools.json): entradas e saídas das ferramentas do lojista.
Cada página da documentação oferece cópia em Markdown. Você também pode adicionar `.md` ao caminho, como `/docs/primeiros-passos.md`, ou enviar `Accept: text/markdown` para a URL da página.
## Contexto útil para seu agente [#contexto-útil-para-seu-agente]
> Integre com o Meu Ecommerce usando a documentação de [https://dev.meuecommerce.com.br/llms.txt](https://dev.meuecommerce.com.br/llms.txt). A plataforma tem um dashboard, uma API REST e um único Meu Ecommerce MCP. Organize a integração por capacidades: fretes e etiquetas (Meu Frete) e rastreamento (Meu Rastreio). Use somente endpoints documentados. Cotação usa pk\_ no frontend; rastreio usa mk\_ no backend. Não invente endpoints REST de etiquetas. Trate respostas vazias, reason e actionUrl. Nunca inclua chaves secretas no navegador.
## Documentação e execução [#documentação-e-execução]
Os arquivos desta página fornecem contexto técnico. Para executar operações de negócio, conecte o [Meu Ecommerce MCP](/docs/mcp/conectar). Este portal não é o endpoint de execução MCP.
# Primeira integração (/docs/primeiros-passos)
Sua primeira integração usa a capacidade de [fretes e cotações](/docs/capacidades/fretes). Você fará uma requisição à API REST comum do Meu Ecommerce. Para conectar um agente, siga o [guia do Meu Ecommerce MCP](/docs/mcp/conectar).
## 1. Prepare sua loja [#1-prepare-sua-loja]
[Acesse o painel Meu Ecommerce](https://app.meuecommerce.com.br/start) para criar sua loja ou entrar na conta existente. Configure o CEP de origem, os serviços de envio e o acesso ao plano. O frete precisa dessas configurações para retornar opções válidas.
Obtenha a chave pública da loja (`pk_…`) pelo fluxo de configuração. Se a credencial não estiver disponível para sua conta, entre em contato com o suporte pelo painel.
As credenciais de integração identificam sua loja no Meu Ecommerce. Elas não são a senha nem o código de acesso do contrato Correios.
## 2. Faça uma requisição [#2-faça-uma-requisição]
Defina sua chave no terminal. O valor abaixo é um marcador: substitua pela chave da sua loja.
```bash
export MEUECOMMERCE_PUBLIC_KEY='pk_SUA_CHAVE'
```
```bash
curl --request POST 'https://api.meuecommerce.com.br/v1/rates' \
--header "Authorization: Bearer $MEUECOMMERCE_PUBLIC_KEY" \
--header 'Content-Type: application/json' \
--data '{
"destinationCep": "20040002",
"items": [{
"name": "Camiseta de algodão",
"quantity": 1,
"unitPriceBRL": 89.90,
"weightKg": 0.3
}]
}'
```
O peso é **unitário, em quilogramas**. O preço também é unitário, em reais. O CEP de origem vem da configuração da loja.
## 3. Leia a resposta [#3-leia-a-resposta]
Este é um exemplo ilustrativo. Valores, serviços e prazos reais dependem da configuração e da consulta aos Correios.
```json
{
"rates": [
{
"code": "SEDEX",
"serviceId": "correios_sedex",
"label": "SEDEX",
"deliveryDays": 3,
"price": 28.9
}
]
}
```
Uma resposta `200` pode trazer `rates: []` e um `reason`. Trate esse caso como ausência de cotação; não apresente frete grátis por padrão.
## 4. Continue a integração [#4-continue-a-integração]
* [Adicionar cotação ao checkout](/docs/guias/checkout)
* [Entender autenticação](/docs/autenticacao)
* [Consultar erros e limites](/docs/erros-e-limites)
* [Ver todos os campos de cotação](/docs/api/cotar-frete)
# Cotar frete (/docs/api/cotar-frete)
POST
/v1/rates
Retorna cada serviço habilitado com preço (BRL) e prazo. A loja vem da chave — não envie instanceId. Aceita chave pública (pk\_) ou secreta (mk\_). CORS habilitado para uso direto no frontend.
Capacidade: [Fretes e cotações](/docs/capacidades/fretes), disponível pela API REST do Meu Ecommerce.
## Autenticação [#autenticação]
Chave pública `pk_…` ou secreta `mk_…`. A cotação pode ser feita pelo navegador.
## Corpo da requisição [#corpo-da-requisição]
| Campo | Tipo | Obrigatório no objeto | Descrição |
| ---------------------- | ------- | --------------------- | ----------------------------------------------------------------- |
| `destinationCep` | string | Sim | CEP de destino (8 dígitos; traços/espaços são ignorados). |
| `items` | array | Sim | Mín. 1 itens. Máx. 50 itens. |
| `items[].name` | string | Sim | Product name. |
| `items[].quantity` | integer | Sim | Units of this product in the cart. Mínimo: 1. |
| `items[].unitPriceBRL` | number | Sim | Unit price in BRL (used for free-shipping thresholds). Mínimo: 0. |
| `items[].weightKg` | number | Não | Unit weight in kg. Defaults to 0.3kg if omitted. Maior que 0. |
| `requestId` | string | Não | Id de correlação/idempotência. Gerado automaticamente se omitido. |
### Exemplo [#exemplo]
```json
{
"destinationCep": "20040002",
"items": [
{
"name": "Camiseta de algodão",
"quantity": 1,
"unitPriceBRL": 89.9,
"weightKg": 0.3
}
]
}
```
## Resposta de sucesso [#resposta-de-sucesso]
Cotação (pode vir vazia com um `reason` informativo, ex.: CEP sem cobertura).
| Campo | Tipo | Obrigatório no objeto | Descrição |
| ---------------------- | ------- | --------------------- | --------------------------------------------- |
| `rates` | array | Sim | — |
| `rates[].code` | string | Sim | — |
| `rates[].serviceId` | string | Sim | — |
| `rates[].label` | string | Sim | — |
| `rates[].deliveryDays` | integer | Sim | — |
| `rates[].price` | number | Sim | — |
| `rates[].free` | boolean | Não | — |
| `reason` | string | Não | Por que a lista veio vazia, quando aplicável. |
| `actionUrl` | string | Não | — |
## Códigos HTTP do contrato [#códigos-http-do-contrato]
| Status | Descrição |
| ------ | ----------------------------------------------------------------------------- |
| 200 | Cotação (pode vir vazia com um `reason` informativo, ex.: CEP sem cobertura). |
| 400 | Corpo inválido. |
| 401 | Chave ausente ou inválida. |
| 402 | Assinatura necessária. |
| 404 | Loja não encontrada. |
| 413 | Corpo grande demais. |
| 429 | Limite de requisições excedido. |
| 502 | Falha ao consultar os Correios. |
Consulte [erros e limites](/docs/erros-e-limites) para os erros de autenticação e escopo, incluindo `403`, e o formato de falha.
## Schema completo [#schema-completo]
[Baixar OpenAPI](/openapi.json) · [Primeira integração](/docs/primeiros-passos)
`requestId`
pode ser usado para correlação; não há garantia documentada de deduplicação. Uma resposta vazia precisa ser tratada pela aplicação.
# API REST (/docs/api)
## Uma API para a plataforma [#uma-api-para-a-plataforma]
Use o mesmo endereço base para as capacidades disponíveis via REST. Os endpoints abaixo mantêm seus requisitos de credencial e acesso; não é necessário escolher uma API por app.
## Endereço base [#endereço-base]
```text
https://api.meuecommerce.com.br
```
## Operações por capacidade [#operações-por-capacidade]
| Capacidade | Endpoint | Credencial | Referência |
| ---------------------------------------------- | ------------------- | ---------------- | -------------------------------------- |
| [Fretes e cotações](/docs/capacidades/fretes) | `POST /v1/rates` | `pk_…` ou `mk_…` | [Cotar frete](/docs/api/cotar-frete) |
| [Rastreamento](/docs/capacidades/rastreamento) | `POST /v1/tracking` | `mk_…` | [Rastrear objetos](/docs/api/rastrear) |
Envie JSON com `Content-Type: application/json` e autenticação Bearer. O rastreio deve ser chamado do backend. Consulte [autenticação e credenciais](/docs/autenticacao) para distinguir permissão da conexão e disponibilidade na conta.
## Contrato para importar [#contrato-para-importar]
[Baixar o OpenAPI versionado neste portal](/openapi.json). Você pode importá-lo em ferramentas compatíveis com OpenAPI 3.1.
[Consultar o contrato servido pela API](https://api.meuecommerce.com.br/openapi.json).
## Como ler esta referência [#como-ler-esta-referência]
As páginas de endpoints são geradas da especificação versionada. Os guias complementam o contrato com exemplos e tratamento de cenários operacionais. A versão da API é identificada pelo caminho `/v1`.
A emissão e o download de etiquetas estão documentados pelo
[Meu Ecommerce MCP](/docs/mcp)
. Não existe endpoint REST público de etiquetas no contrato atual.
# Rastrear objetos (/docs/api/rastrear)
POST
/v1/tracking
Retorna o histórico de eventos e o status atual de cada código. Exige chave secreta (mk\_); chame do backend, não do frontend (sem CORS).
Capacidade: [Rastreamento](/docs/capacidades/rastreamento), disponível pela API REST do Meu Ecommerce.
## Autenticação [#autenticação]
Chave secreta `mk_…`, somente no backend.
## Corpo da requisição [#corpo-da-requisição]
| Campo | Tipo | Obrigatório no objeto | Descrição |
| ------- | ----- | --------------------- | ----------------------------------------------------------------------------------- |
| `codes` | array | Sim | Códigos de rastreio dos Correios (até 50 por chamada). Mín. 1 itens. Máx. 50 itens. |
### Exemplo [#exemplo]
```json
{
"codes": [
"AA123456789BR"
]
}
```
## Resposta de sucesso [#resposta-de-sucesso]
Resultados de rastreio.
| Campo | Tipo | Obrigatório no objeto | Descrição |
| ---------------------------------- | ------- | --------------------- | --------- |
| `results` | array | Sim | — |
| `results[].code` | string | Sim | — |
| `results[].found` | boolean | Sim | — |
| `results[].delivered` | boolean | Sim | — |
| `results[].lastStatus` | object | Não | — |
| `results[].lastStatus.code` | string | Sim | — |
| `results[].lastStatus.type` | string | Não | — |
| `results[].lastStatus.timestamp` | string | Não | — |
| `results[].lastStatus.description` | string | Sim | — |
| `results[].lastStatus.origin` | string | Não | — |
| `results[].lastStatus.destination` | string | Não | — |
| `results[].events` | array | Sim | — |
| `results[].events[].code` | string | Sim | — |
| `results[].events[].type` | string | Não | — |
| `results[].events[].timestamp` | string | Não | — |
| `results[].events[].description` | string | Sim | — |
| `results[].events[].origin` | string | Não | — |
| `results[].events[].destination` | string | Não | — |
| `results[].message` | string | Não | — |
| `reason` | string | Não | — |
| `actionUrl` | string | Não | — |
## Códigos HTTP do contrato [#códigos-http-do-contrato]
| Status | Descrição |
| ------ | ------------------------------------------------------ |
| 200 | Resultados de rastreio. |
| 400 | Corpo inválido. |
| 401 | Chave ausente ou inválida. |
| 402 | Assinatura necessária. |
| 403 | Chave pública não pode rastrear — use a chave secreta. |
| 413 | Corpo grande demais. |
| 429 | Limite de requisições excedido. |
| 502 | Falha ao consultar os Correios. |
Consulte [erros e limites](/docs/erros-e-limites) para os erros de autenticação e escopo, incluindo `403`, e o formato de falha.
## Schema completo [#schema-completo]
[Baixar OpenAPI](/openapi.json) · [Guia de rastreamento](/docs/guias/rastreio)
Os códigos no exemplo são ilustrativos. Um objeto não encontrado deve ser tratado por
`found`
, sem assumir falha de toda a chamada.
# Etiquetas e postagens (/docs/capacidades/etiquetas)
## O que você pode construir [#o-que-você-pode-construir]
Prepare uma postagem a partir dos dados do pedido e obtenha o PDF da etiqueta. Essa capacidade está disponível pelo **Meu Ecommerce MCP**.
Produto relacionado: **Meu Frete**.
## Como acessar [#como-acessar]
| Interface | Operação | Uso |
| ----------------- | ------------------------------------------------------- | --------------------------------------------- |
| Meu Ecommerce MCP | [generate\_label](/docs/mcp/ferramentas/generate-label) | Criar uma pré-postagem e tentar obter o PDF |
| Meu Ecommerce MCP | [get\_label\_pdf](/docs/mcp/ferramentas/get-label-pdf) | Recuperar o PDF de uma pré-postagem existente |
Não há endpoint REST público de emissão ou download de etiquetas no contrato atual. Use a [mesma conexão MCP da plataforma](/docs/mcp/conectar).
## Antes de começar [#antes-de-começar]
A loja precisa de acesso ativo, contrato próprio dos Correios autenticado e conexão MCP com permissão de lojista. A integração de etiquetas deve estar habilitada, e as ferramentas precisam aparecer no catálogo retornado pelo servidor.
Configure os requisitos da loja pelo [dashboard](https://app.meuecommerce.com.br/start). Uma conexão MCP autorizada, por si só, não habilita a emissão.
## Dados e unidades [#dados-e-unidades]
Informe peso do pacote em **gramas**, dimensões em **centímetros**, remetente, destinatário, declaração de conteúdo e código contratual do serviço. O peso da cotação, por outro lado, é informado em quilogramas por unidade.
## Da criação ao PDF [#da-criação-ao-pdf]
`generate_label` cria uma pré-postagem real nos Correios. Se a criação retornar `prepostagemId` antes de o PDF estar pronto, use `get_label_pdf` com esse identificador. Repetir a criação pode gerar outra pré-postagem.
[Veja o fluxo completo de emissão e recuperação](/docs/guias/etiquetas).
Depois da postagem, use a capacidade de [rastreamento](/docs/capacidades/rastreamento) para acompanhar a entrega.
# Fretes e cotações (/docs/capacidades/fretes)
## O que você pode construir [#o-que-você-pode-construir]
Apresente preço e prazo de entrega na página de produto, no carrinho ou em um fluxo de atendimento por agente. A plataforma usa o CEP de origem e os serviços habilitados na loja para consultar as opções disponíveis.
Produto relacionado: **Meu Frete**.
## Como acessar [#como-acessar]
| Interface | Operação | Credencial |
| ----------------- | ---------------------------------------------------------------- | -------------------------------------- |
| API REST | [POST /v1/rates](/docs/api/cotar-frete) | Chave pública `pk_…` ou secreta `mk_…` |
| Meu Ecommerce MCP | [get\_shipping\_rates](/docs/mcp/ferramentas/get-shipping-rates) | OAuth ou chave secreta da loja |
A cotação REST pode ser consumida pelo navegador com a chave pública. Para agentes, use a [conexão única do MCP](/docs/mcp/conectar).
## Antes de começar [#antes-de-começar]
No [dashboard](https://app.meuecommerce.com.br/start), configure a loja, o CEP de origem e os serviços de envio. Confira o acesso da conta e as condições disponíveis para sua integração.
## Unidades e formatos [#unidades-e-formatos]
| Campo | Unidade ou formato |
| ---------------- | ----------------------------------------------------------------- |
| `destinationCep` | CEP brasileiro de 8 dígitos; pontuação e espaços são normalizados |
| `unitPriceBRL` | Reais por unidade, como número decimal |
| `weightKg` | Quilogramas por unidade |
| `deliveryDays` | Prazo retornado em dias úteis |
Uma resposta `200` pode conter `rates: []`. Trate esse cenário como ausência de cotação, sem apresentar frete grátis por padrão. Examine `reason` e `actionUrl`, quando retornados.
## Continue a integração [#continue-a-integração]
* [Faça sua primeira cotação](/docs/primeiros-passos).
* [Adicione cotação ao checkout](/docs/guias/checkout).
* [Emita etiquetas quando o pedido estiver pronto](/docs/capacidades/etiquetas).
# Rastreamento (/docs/capacidades/rastreamento)
## O que você pode construir [#o-que-você-pode-construir]
Exiba o status de uma entrega na sua aplicação, crie uma experiência de pós-venda ou permita que um agente consulte o histórico de um objeto.
Produto relacionado: **Meu Rastreio**. O rastreamento é acessado pela API REST e pelo MCP comuns do Meu Ecommerce.
## Como acessar [#como-acessar]
| Interface | Operação | Credencial |
| ----------------- | ------------------------------------------------------- | ---------------------------------------- |
| API REST | [POST /v1/tracking](/docs/api/rastrear) | Chave secreta `mk_…`, somente no backend |
| Meu Ecommerce MCP | [track\_shipment](/docs/mcp/ferramentas/track-shipment) | OAuth ou chave secreta da loja |
A chave pública de cotação não permite rastrear objetos. Configure a credencial no backend ou autorize seu agente pela [conexão única do MCP](/docs/mcp/conectar). Confira o acesso da conta no [dashboard](https://app.meuecommerce.com.br/start).
## Dados disponíveis [#dados-disponíveis]
Consulte `found`, `delivered`, `events` e `lastStatus`, quando presentes. Um objeto recém-criado pode ainda não ter eventos. Trate cada resultado individualmente e não confunda ausência de eventos com entrega concluída.
A API fornece dados para sua aplicação apresentar. A consulta não instala automaticamente a página de rastreio ou os componentes do app Meu Rastreio na loja.
## Continue a integração [#continue-a-integração]
* [Implemente o acompanhamento de entregas](/docs/guias/rastreio).
* [Consulte campos e limites do endpoint](/docs/api/rastrear).
* [Trate erros e novas tentativas](/docs/erros-e-limites).
# Integrar com Base44 (/docs/guias/base44)
## Cotação na aplicação publicada [#cotação-na-aplicação-publicada]
Uma aplicação pode chamar a API REST sempre que seu cliente informar o CEP. Oriente o construtor com o contrato e a chave pública da loja:
> Adicione um campo de CEP e um botão de cálculo de frete. Use POST [https://api.meuecommerce.com.br/v1/rates](https://api.meuecommerce.com.br/v1/rates) com Authorization Bearer usando a chave pública da loja. Envie destinationCep e items, com name, quantity, unitPriceBRL e weightKg por unidade. Mostre label, price e deliveryDays. Trate carregamento, falha e rates vazio. Recalcule ao alterar o carrinho ou destino.
[Baixe o OpenAPI](/openapi.json) para usar como referência do construtor. Os valores devem vir do carrinho real.
## Rastreio pelo backend [#rastreio-pelo-backend]
Guarde `MEUECOMMERCE_SECRET_KEY` como secret da plataforma e faça a consulta por uma função de backend. A chave `mk_…` nunca deve aparecer no navegador ou no prompt compartilhado do projeto.
[Exemplo de rastreamento](/docs/guias/rastreio).
## Ferramentas para o agente [#ferramentas-para-o-agente]
Quando o cliente do agente oferecer suporte a MCP remoto, conecte o servidor e autorize a loja conforme [o guia MCP](/docs/mcp/conectar). Isso permite ao agente operar as ferramentas disponibilizadas pela credencial.
Conectar o agente ao MCP não instala automaticamente a integração REST na aplicação publicada. Configure e valide o fluxo que o comprador vai utilizar.
## Antes de publicar sua aplicação [#antes-de-publicar-sua-aplicação]
Teste um CEP válido, um CEP inválido, ausência de cotação e falha de autenticação. Confirme que a chave secreta não está no código do navegador e que o total do pedido é validado pelo backend.
# Calcular frete no checkout (/docs/guias/checkout)
## Faça a chamada no navegador [#faça-a-chamada-no-navegador]
A cotação aceita chave pública e oferece CORS. Substitua o marcador pela chave da loja e obtenha os itens do carrinho real.
```javascript
export async function cotarFrete(destinationCep, items) {
const response = await fetch('https://api.meuecommerce.com.br/v1/rates', {
method: 'POST',
headers: {
Authorization: 'Bearer pk_SUA_CHAVE',
'Content-Type': 'application/json',
},
body: JSON.stringify({ destinationCep, items }),
});
const data = await response.json();
if (!response.ok) {
throw new Error(data.error?.message ?? 'Não foi possível cotar o frete.');
}
return data;
}
const quote = await cotarFrete('20040002', [{
name: 'Camiseta de algodão', quantity: 1,
unitPriceBRL: 89.90, weightKg: 0.3,
}]);
if (!quote.rates.length) {
// Mostre uma mensagem de indisponibilidade. Examine quote.reason.
} else {
// Mostre label, price e deliveryDays para cada serviço.
}
```
## Estados da interface [#estados-da-interface]
Mostre o carregamento enquanto a consulta estiver em andamento. Desabilite envios repetidos, valide o CEP e ignore uma resposta antiga se o cliente já alterou o endereço ou o carrinho.
Recalcule ao mudar quantidade, itens ou destino. Uma lista vazia não equivale a frete grátis. Para formatar preços, use `Intl.NumberFormat('pt-BR', { style: 'currency', currency: 'BRL' })`.
## Finalização do pedido [#finalização-do-pedido]
A cotação apresenta opções; ela não cria um pedido nem adiciona automaticamente uma taxa à sua plataforma. Integre a opção selecionada ao mecanismo de checkout da aplicação e valide preço e serviço no backend antes de concluir a compra. Não confie em um total enviado pelo navegador.
[Referência completa](/docs/api/cotar-frete) · [Erros e limites](/docs/erros-e-limites)
# Emitir etiquetas pelo MCP (/docs/guias/etiquetas)
## Pré-requisitos [#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 [#prepare-os-dados]
Informe o código do serviço, peso do pacote em **gramas**, dimensões em centímetros, remetente, destinatário e declaração de conteúdo. Confira nomes, endereços e dados do pedido antes da emissão.
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](/docs/mcp/ferramentas/generate-label).
## Crie a pré-postagem [#crie-a-pré-postagem]
O agente chama `generate_label`. 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 [#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.
```json
{
"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 [#trate-falhas-de-negócio]
`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](/docs/mcp/ferramentas/get-label-pdf)
# Guias de integração (/docs/guias)
# Consultar rastreamento (/docs/guias/rastreio)
Este guia usa a capacidade de [rastreamento](/docs/capacidades/rastreamento), relacionada ao Meu Rastreio, pela API REST do Meu Ecommerce.
## Mantenha a chave no servidor [#mantenha-a-chave-no-servidor]
Configure `MEUECOMMERCE_SECRET_KEY` no ambiente do backend. Nunca utilize uma variável com prefixo público do framework para essa credencial.
```javascript
// Execute somente no backend, em Node.js 22+.
export async function rastrear(codes) {
const key = process.env.MEUECOMMERCE_SECRET_KEY;
if (!key) throw new Error('Configure MEUECOMMERCE_SECRET_KEY no backend.');
const response = await fetch('https://api.meuecommerce.com.br/v1/tracking', {
method: 'POST',
headers: {
Authorization: `Bearer ${key}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ codes }),
signal: AbortSignal.timeout(15000),
});
const data = await response.json();
if (!response.ok) {
throw new Error(data.error?.message ?? 'Não foi possível rastrear.');
}
return data.results;
}
```
## Interprete cada resultado [#interprete-cada-resultado]
* `found` indica se o objeto foi encontrado.
* `delivered` indica entrega concluída.
* `events` contém os eventos disponíveis.
* `lastStatus`, quando presente, descreve o status atual.
* `message` pode trazer informação sobre a consulta do objeto.
Um objeto recém-criado pode ainda não ter eventos. Não confunda esse cenário com entrega concluída. Respeite o timestamp retornado, sem atribuir um fuso que não esteja informado.
## Proteja sua rota [#proteja-sua-rota]
Se sua aplicação expuser uma rota de rastreio para clientes, valide que eles podem consultar aquele pedido e aplique limites de uso. O endpoint não retorna uma página pronta: sua aplicação é responsável pela apresentação dos dados.
[Referência de rastreamento](/docs/api/rastrear)
# Conecte seu agente (/docs/mcp/conectar)
## Um servidor para todas as capacidades [#um-servidor-para-todas-as-capacidades]
Adicione o **Meu Ecommerce MCP** uma única vez ao seu cliente. Fretes, rastreamento e etiquetas usam essa mesma conexão. As ferramentas disponíveis dependem da credencial e da habilitação dos recursos na conta.
## Conexão por OAuth [#conexão-por-oauth]
1. Abra a área de conectores ou servidores MCP do seu cliente.
2. Adicione um servidor remoto chamado **Meu Ecommerce**, com a URL abaixo.
3. Inicie a conexão e conclua o login e a autorização da loja no navegador.
4. Retorne ao cliente e confira as ferramentas disponíveis.
```text
https://app.meuecommerce.com.br/mcp
```
Esse é o fluxo indicado para clientes compatíveis com a descoberta OAuth do servidor, como o Claude. Os nomes dos menus podem variar entre clientes e planos.
## Prepare a operação [#prepare-a-operação]
Concluir a autorização conecta o agente à loja. Antes de cotar, finalize CEP de origem, serviços de envio e acesso ao plano pelo painel. Antes de emitir etiquetas, configure também o contrato próprio dos Correios.
## Primeiro teste [#primeiro-teste]
Peça ao agente:
> Cote o envio para o CEP 20040-002 de uma camiseta de algodão, quantidade 1, preço unitário R$ 89,90 e peso unitário 0,3 kg. Mostre os serviços, preços e prazos retornados.
O CEP de origem será o da loja autenticada. O resultado vem de uma consulta real.
## Clientes que aceitam headers [#clientes-que-aceitam-headers]
Configure o transporte Streamable HTTP e envie a chave secreta da loja:
```http
Authorization: Bearer mk_SUA_CHAVE
```
O formato do arquivo de configuração depende do cliente. Guarde a chave no gerenciador de segredos do ambiente; não inclua uma credencial real em prompts compartilhados.
## Descoberta e depuração [#descoberta-e-depuração]
* Recurso protegido: `https://app.meuecommerce.com.br/.well-known/oauth-protected-resource/mcp`
* Servidor de autorização: `https://app.meuecommerce.com.br/.well-known/oauth-authorization-server`
* O fluxo implementa Authorization Code com PKCE S256 e registro dinâmico de clientes.
Um `401` antes da autorização pode ser parte da descoberta. Depois da autorização, revise a conexão se ele persistir. Para `subscription_required`, siga a `actionUrl` retornada.
# Meu Ecommerce MCP (/docs/mcp)
## Uma conexão com a plataforma [#uma-conexão-com-a-plataforma]
Conecte seu agente ao **Meu Ecommerce MCP**. O mesmo servidor reúne as ferramentas das capacidades documentadas e será o ponto de entrada para novas capacidades da plataforma. Não é necessário configurar um servidor por app.
```text
https://app.meuecommerce.com.br/mcp
```
O transporte é **Streamable HTTP**. Clientes compatíveis com OAuth podem conectar pelo fluxo de autorização do lojista. Clientes com suporte a headers podem usar a chave secreta da loja.
[Conecte seu agente](/docs/mcp/conectar) · [Entenda autenticação e acesso](/docs/autenticacao)
## Ferramentas por capacidade [#ferramentas-por-capacidade]
| Capacidade | Ferramentas documentadas |
| ---------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| [Fretes e cotações](/docs/capacidades/fretes) | [get\_shipping\_rates](/docs/mcp/ferramentas/get-shipping-rates) |
| [Rastreamento](/docs/capacidades/rastreamento) | [track\_shipment](/docs/mcp/ferramentas/track-shipment) |
| [Etiquetas e postagens](/docs/capacidades/etiquetas) | [generate\_label](/docs/mcp/ferramentas/generate-label) e [get\_label\_pdf](/docs/mcp/ferramentas/get-label-pdf) |
## Permissões e disponibilidade [#permissões-e-disponibilidade]
A conexão identifica a loja e seu acesso. O catálogo retornado pelo servidor pode variar conforme a credencial e a configuração. Conectar o MCP não libera automaticamente todas as ferramentas ou operações.
Para cotar, configure origem e serviços da loja. As ferramentas de etiquetas exigem integração de etiquetas habilitada e contrato próprio autenticado. Confira os requisitos na página de cada capacidade.
Este catálogo descreve as ferramentas disponíveis na referência atual. Novas capacidades serão documentadas à medida que forem disponibilizadas.
## Respostas [#respostas]
O MCP retorna conteúdo para leitura pelo agente em `content` e dados estruturados em `structuredContent`. Sempre examine `reason` e `actionUrl`, quando presentes.
## Próximos passos [#próximos-passos]
* [Referência das ferramentas](/docs/mcp/ferramentas)
* [Gerar e recuperar etiquetas](/docs/guias/etiquetas)
* [Provisionamento para parceiros](/docs/mcp/parceiros)
# Provisionamento para parceiros (/docs/mcp/parceiros)
## Um acesso específico [#um-acesso-específico]
As ferramentas `create_merchant` e `get_merchant_status` pertencem ao escopo de **plataforma**. Elas não fazem parte do acesso comum do lojista via OAuth ou chave `mk_…`.
Seu uso requer um relacionamento de integração e credencial própria de plataforma. [Fale com o Meu Ecommerce](https://www.meuecommerce.com.br/pt#contact) para avaliar esse acesso.
## Fluxo de integração [#fluxo-de-integração]
1. A plataforma provisiona uma loja com `create_merchant`.
2. O lojista abre o endereço de onboarding retornado e conclui sua configuração.
3. A plataforma acompanha o progresso com `get_merchant_status`.
4. A aplicação utiliza a credencial vinculada à loja para suas operações.
As chaves de plataforma devem permanecer no backend do parceiro. Nunca devem ser distribuídas para visitantes ou usadas no lugar de uma chave pública de cotação.
O catálogo comum deste portal documenta as ferramentas do lojista. O contrato e as condições de provisionamento devem ser alinhados antes da integração do parceiro.
# generate_label (/docs/mcp/ferramentas/generate-label)
## Gerar etiqueta [#gerar-etiqueta]
Ferramenta do **Meu Ecommerce MCP**, na capacidade de [Etiquetas e postagens](/docs/capacidades/etiquetas). A loja é vinculada à credencial da conexão remota. Confira os requisitos de permissão e disponibilidade na página da capacidade.
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.
## Entrada [#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 | Sim | Package dimensions in centimeters. |
| `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.). |
| `declaredItems` | array | Sim | Declaração de conteúdo — required by Correios (at least one item). 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 [#saída-estruturada]
| Campo | Tipo | Obrigatório no objeto | Descriçã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. |
| `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 [#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](/docs/guias/etiquetas) e [erros e limites](/docs/erros-e-limites).
## Contrato JSON [#contrato-json]
```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."
},
"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)."
},
"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 by Correios (at least one item)."
}
},
"required": [
"serviceCode",
"weightGrams",
"dimensions",
"sender",
"recipient",
"declaredItems"
],
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
}
```
[Baixar todos os schemas](/mcp-tools.json).
Referência gerada dos schemas do servidor. Os nomes de campos e as descrições técnicas originais são preservados.
# get_label_pdf (/docs/mcp/ferramentas/get-label-pdf)
## Baixar etiqueta [#baixar-etiqueta]
Ferramenta do **Meu Ecommerce MCP**, na capacidade de [Etiquetas e postagens](/docs/capacidades/etiquetas). A loja é vinculada à credencial da conexão remota. Confira os requisitos de permissão e disponibilidade na página da capacidade.
## Entrada [#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. |
| `prepostagemId` | string | Sim | Correios pré-postagem id, as returned by generate\_label in the `prepostagemId` field. |
## Saída estruturada [#saída-estruturada]
| Campo | Tipo | Obrigatório no objeto | Descrição |
| ---------------- | ------ | --------------------- | -------------------------------------------------------------------------------------- |
| `prepostagemId` | string | Não | The pré-postagem id the PDF belongs to. |
| `status` | string | Não | Correios status/business message, when the label isn't printable. |
| `labelPdfBase64` | string | Não | Base64-encoded label PDF, once ready. |
| `reason` | string | Não | Why the PDF wasn't returned. |
| `actionUrl` | string | Não | When set (e.g. reason=subscription\_required), send the merchant here to finish setup. |
## Tratamento da resposta [#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](/docs/guias/etiquetas) e [erros e limites](/docs/erros-e-limites).
## Contrato JSON [#contrato-json]
```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."
},
"prepostagemId": {
"type": "string",
"description": "Correios pré-postagem id, as returned by generate_label in the `prepostagemId` field."
}
},
"required": [
"prepostagemId"
],
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
}
```
[Baixar todos os schemas](/mcp-tools.json).
Referência gerada dos schemas do servidor. Os nomes de campos e as descrições técnicas originais são preservados.
# get_shipping_rates (/docs/mcp/ferramentas/get-shipping-rates)
## Cotar frete [#cotar-frete]
Ferramenta do **Meu Ecommerce MCP**, na capacidade de [Fretes e cotações](/docs/capacidades/fretes). A loja é vinculada à credencial da conexão remota. Confira os requisitos de permissão e disponibilidade na página da capacidade.
## Entrada [#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. |
| `destinationCep` | string | Sim | Destination Brazilian postal code (CEP). 8 digits; dashes/spaces are ignored. |
| `items` | array | Sim | Cart line items. Mín. 1 itens. |
| `items[].name` | string | Sim | Product name. |
| `items[].quantity` | integer | Sim | Units of this product in the cart. Maior que 0. |
| `items[].unitPriceBRL` | number | Sim | Unit price in BRL (used for free-shipping thresholds). Mínimo: 0. |
| `items[].weightKg` | number | Não | Unit weight in kg. Defaults to 0.3kg if omitted. Maior que 0. |
| `requestId` | string | Não | Idempotency/correlation id. Auto-generated when omitted. |
## Saída estruturada [#saída-estruturada]
| Campo | Tipo | Obrigatório no objeto | Descrição |
| ---------------------- | ------- | --------------------- | -------------------------------------------------------------------------------------- |
| `rates` | array | Sim | — |
| `rates[].code` | string | Sim | — |
| `rates[].serviceId` | string | Sim | — |
| `rates[].label` | string | Sim | — |
| `rates[].deliveryDays` | number | Sim | — |
| `rates[].price` | number | Sim | — |
| `rates[].free` | boolean | Não | — |
| `reason` | string | Não | Why no rates were returned, when the list is empty. |
| `actionUrl` | string | Não | When set (e.g. reason=subscription\_required), send the merchant here to finish setup. |
## Tratamento da resposta [#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](/docs/guias/etiquetas) e [erros e limites](/docs/erros-e-limites).
## Contrato JSON [#contrato-json]
```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."
},
"destinationCep": {
"type": "string",
"description": "Destination Brazilian postal code (CEP). 8 digits; dashes/spaces are ignored."
},
"items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Product name."
},
"quantity": {
"type": "integer",
"exclusiveMinimum": 0,
"description": "Units of this product in the cart."
},
"unitPriceBRL": {
"type": "number",
"minimum": 0,
"description": "Unit price in BRL (used for free-shipping thresholds)."
},
"weightKg": {
"type": "number",
"exclusiveMinimum": 0,
"description": "Unit weight in kg. Defaults to 0.3kg if omitted."
}
},
"required": [
"name",
"quantity",
"unitPriceBRL"
],
"additionalProperties": false
},
"minItems": 1,
"description": "Cart line items."
},
"requestId": {
"type": "string",
"description": "Idempotency/correlation id. Auto-generated when omitted."
}
},
"required": [
"destinationCep",
"items"
],
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
}
```
[Baixar todos os schemas](/mcp-tools.json).
Referência gerada dos schemas do servidor. Os nomes de campos e as descrições técnicas originais são preservados.
# Ferramentas por capacidade (/docs/mcp/ferramentas)
Todas as ferramentas abaixo usam a [mesma conexão MCP](/docs/mcp/conectar). Confira o catálogo disponibilizado para sua credencial e os requisitos da conta antes de executar operações.
## Fretes e cotações [#fretes-e-cotações]
[Configuração e unidades da cotação](/docs/capacidades/fretes).
## Rastreamento [#rastreamento]
[Conheça a capacidade de rastreamento](/docs/capacidades/rastreamento).
## Etiquetas e postagens [#etiquetas-e-postagens]
[Requisitos para emissão de etiquetas](/docs/capacidades/etiquetas).
## Schemas [#schemas]
[Baixar os schemas MCP](/mcp-tools.json).
A referência inclui `instanceId` porque o schema também atende execução local. Em conexões remotas autenticadas, a loja vem da credencial e esse campo é ignorado.
# track_shipment (/docs/mcp/ferramentas/track-shipment)
## Rastrear objetos [#rastrear-objetos]
Ferramenta do **Meu Ecommerce MCP**, na capacidade de [Rastreamento](/docs/capacidades/rastreamento). A loja é vinculada à credencial da conexão remota. Confira os requisitos de permissão e disponibilidade na página da capacidade.
## Entrada [#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. |
| `codes` | array | Sim | Correios tracking codes, e.g. "AA123456789BR". Spaces are ignored; up to 50 per call. Mín. 1 itens. |
## Saída estruturada [#saída-estruturada]
| Campo | Tipo | Obrigatório no objeto | Descrição |
| ---------------------------------- | ------- | --------------------- | -------------------------------------------------------------------------------------- |
| `results` | array | Sim | — |
| `results[].code` | string | Sim | — |
| `results[].found` | boolean | Sim | — |
| `results[].delivered` | boolean | Sim | — |
| `results[].lastStatus` | object | Não | — |
| `results[].lastStatus.code` | string | Sim | — |
| `results[].lastStatus.type` | string | Não | — |
| `results[].lastStatus.timestamp` | string | Não | — |
| `results[].lastStatus.description` | string | Sim | — |
| `results[].lastStatus.origin` | string | Não | — |
| `results[].lastStatus.destination` | string | Não | — |
| `results[].events` | array | Sim | — |
| `results[].events[].code` | string | Sim | — |
| `results[].events[].type` | string | Não | — |
| `results[].events[].timestamp` | string | Não | — |
| `results[].events[].description` | string | Sim | — |
| `results[].events[].origin` | string | Não | — |
| `results[].events[].destination` | string | Não | — |
| `results[].message` | string | Não | — |
| `reason` | string | Não | Why no lookup could be performed, when results is empty. |
| `actionUrl` | string | Não | When set (e.g. reason=subscription\_required), send the merchant here to finish setup. |
## Tratamento da resposta [#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](/docs/guias/etiquetas) e [erros e limites](/docs/erros-e-limites).
## Contrato JSON [#contrato-json]
```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."
},
"codes": {
"type": "array",
"items": {
"type": "string"
},
"minItems": 1,
"description": "Correios tracking codes, e.g. \"AA123456789BR\". Spaces are ignored; up to 50 per call."
}
},
"required": [
"codes"
],
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
}
```
[Baixar todos os schemas](/mcp-tools.json).
Referência gerada dos schemas do servidor. Os nomes de campos e as descrições técnicas originais são preservados.