Um assistente de IA que trabalha no seu computador e executa tarefas por comando em português, como o Claude Code, o ChatGPT com Codex, o Cursor, o GitHub Copilot ou o Gemini CLI, pode operar a sua conta EnvioEcom pela nossa API pública: cotar frete, criar envios (um ou vários de uma vez), gerar as etiquetas, acompanhar a entrega e cancelar quando precisar. Este guia usa o Claude Code como exemplo; o arquivo de regras e as orientações valem para qualquer agente de IA.
Ele usa exatamente a mesma API que qualquer integração, com o token da sua conta. Tudo o que ele faz aparece no painel como se você tivesse feito, e debita o seu saldo de verdade. Por isso este guia tem duas partes: como colocar para funcionar e como fazer isso com segurança.
Resumo em uma frase: gere o token no painel, guarde fora do chat, cole o nosso arquivo de regras no projeto e peça ao Claude o que precisa, confirmando antes de qualquer ação que gaste saldo.
O que o assistente de IA pode fazer na sua conta
- Cotar frete para um CEP com peso e medidas, e comparar as opções (transportadora, preço, prazo).
- Criar envios, um por vez ou em lote a partir de uma planilha ou da exportação da sua loja.
- Gerar as etiquetas em PDF dos envios criados, prontas para imprimir.
- Listar e consultar envios por período, status, CPF do destinatário ou código de rastreio.
- Acompanhar o rastreio e avisar quais envios ainda não foram postados ou estão parados.
- Cancelar um envio (automático com estorno até 10 minutos depois da criação; depois vira solicitação para o nosso suporte).
- Receber notificações de mudança de status no seu sistema, se você registrar uma URL de webhook.
O que continua no painel
A API cobre a operação de envios. O que é da sua conta, do seu dinheiro ou do atendimento fica no painel, e o Claude vai sugerir que você abra o site quando for o caso:
- Saldo e recarga: menu Carteira.
- Chamados e suporte: botão Fale conosco.
- Pagar envios que ficaram em "Aguardando pagamento".
- Endereço de origem, dados da conta e configurações.
- Conectar sua loja (Shopify, Yampi, WooCommerce, Tray e outras) em Integrações.
- Relatórios, exportações e extrato.
- Gerar ou trocar o token da API.
Passo 1: gere o token no painel
- Entre no painel e abra Integrações.
- Escolha Desenvolvedores API e ative a integração.
- Copie o token mostrado na tela. Ele é único por conta e vale para todas as chamadas.
Esse token é a chave da sua conta na API: quem tem o token cria envios e gasta o seu saldo. Trate como senha.
Nunca dê o seu e-mail e a sua senha ao Claude. Ele não precisa deles: o token basta. Se um assistente pedir a senha da conta, recuse.
Passo 2: guarde o token fora do chat
O token não deve aparecer em conversa, em arquivo do projeto nem em commit. Ele fica numa variável de ambiente chamada ENVIOECOM_TOKEN, e o Claude usa a variável sem nunca ver o valor.
macOS ou Linux (no terminal, antes de abrir o Claude Code):
export ENVIOECOM_TOKEN="cole-aqui-o-seu-token"
Windows (PowerShell):
$env:ENVIOECOM_TOKEN = "cole-aqui-o-seu-token"
Se preferir deixar salvo, coloque a linha num arquivo .env na pasta do projeto e adicione .env ao .gitignore, para que ele nunca vá para o Git.
Passo 3: coloque o arquivo de regras no projeto
Todo assistente de IA lê um arquivo de instruções na pasta do projeto e segue o que está escrito nele: CLAUDE.md no Claude Code, AGENTS.md no Codex, no Cursor, no Gemini CLI e em outros, .github/copilot-instructions.md no Copilot. Preparamos um com as regras certas para a nossa API: onde está a documentação, como usar o token sem expor, o que confirmar com você antes de gastar saldo, como tratar erro e timeout, e quando mandar você para o painel.
Baixar como CLAUDE.md (Claude Code) ou baixar como AGENTS.md (Codex, Cursor, Gemini CLI e outros) e salvar na pasta do seu projeto. Ou copie o conteúdo abaixo:
# EnvioEcom pela API: regras para o assistente de IA (Claude Code, Codex, Cursor, Copilot, Gemini e outros)
Este projeto usa a API pública da EnvioEcom para operar a conta do dono deste projeto:
cotar frete, criar envios, gerar etiquetas, acompanhar e cancelar. Você, assistente ou
agente de IA, age em nome dele, com o saldo real da conta dele. Siga estas regras em toda
tarefa. O arquivo serve para qualquer modelo: salve como `CLAUDE.md` (Claude Code),
`AGENTS.md` (Codex, Cursor, Gemini CLI e outros) ou no arquivo de instruções da sua ferramenta.
## Fonte da verdade
- Documentação: https://envioecom.com.br/api/v1/whitelabel/docs
- OpenAPI (JSON): https://envioecom.com.br/api/v1/whitelabel/docs.json
- Base da API: https://envioecom.com.br/api/v1/whitelabel
- Em dúvida sobre um campo ou uma regra, leia a documentação antes de supor.
## Token: regras sem exceção
- O token fica na variável de ambiente `ENVIOECOM_TOKEN`. Use nas chamadas:
`-H "X-Partner-Token: $ENVIOECOM_TOKEN"`.
- Nunca imprima, registre em log, grave em arquivo, cole em resposta nem inclua em commit
o valor do token. Se precisar mostrar um comando, deixe `$ENVIOECOM_TOKEN` como está.
- Se a variável não existir, peça ao dono para definir. Não peça e-mail nem senha da conta
e não chame `POST /token`: o token é gerado pelo dono no painel.
- Só envie o token para `envioecom.com.br`. Nunca para outro domínio ou serviço.
## Antes de gastar dinheiro, confirme
Criar envio debita o saldo da conta na hora. Antes de chamar `POST /shipping/create` ou
`POST /shipments/{id}/cancel`:
1. Mostre um resumo: número do pedido, destinatário (nome e cidade/UF), serviço, preço,
prazo, quantidade de envios e valor total.
2. Espere o dono responder "ok" ou equivalente. Sem confirmação explícita, não envie.
3. Em lote, mostre o total de envios e o valor somado. Envie no máximo 50 envios por
chamada; acima disso, divida em partes e confirme cada parte.
Gerar etiqueta, cotar, listar e consultar não custam nada e não precisam de confirmação.
## Rotas que você não chama
O token da conta alcança mais do que o fluxo de envios. Estas rotas ficam fora do seu
alcance, mesmo que a documentação as mostre:
- `DELETE /user/me` (apaga a conta): nunca, em hipótese alguma.
- `PUT /user`, `PATCH /user/me/settings`, `/account/*` (dados da conta e contas vinculadas):
só se o dono pedir isso explicitamente, e mostrando antes o que vai mudar.
- `POST /webhook` (troca a URL de notificação da conta): só com pedido explícito do dono.
- `POST /shipments/{id}/duplicate`: não use; crie pelo fluxo normal, com `orderId` próprio.
## Fluxo padrão
1. Cotar: `POST /shipping/quote`. Apresente as opções com `carrier`, `price` e
`delivery_time`.
2. Criar: `POST /shipping/create` com `shipping_company` igual a `quotes[].carrier` e
`freight_cost` igual a `quotes[].price`. Preencha `orderId` com o número do pedido
(um por pedido, sempre o mesmo para o mesmo pedido, nunca inventado por você). Não envie
`external_order_number` nem `orderName` com valor diferente de `orderId`: é o `orderId`
que impede o mesmo pedido de virar dois envios. Guarde o `shipping_id` de cada item em
`shipping_create.results`.
3. Etiqueta: `POST /shipments/generate-labels` com `ids`. Se vier 400 `LABEL_PROCESSING`,
espere 2 minutos e tente de novo, no máximo 5 vezes. Salve o PDF em `./etiquetas/`.
4. Acompanhar: `GET /shipments/by-id/{id}` ou `GET /shipments` com filtros
(`status`, `created_from`, `created_to`, `cpf`, `barcode`). O `status` é texto livre.
5. Cancelar: `POST /shipments/{id}/cancel`. Até 10 minutos depois da criação o cancelamento
é automático, com estorno no saldo. Depois disso vira uma solicitação que o suporte da
EnvioEcom analisa. Sempre confirme antes.
## Erro e retentativa
- Erro vem como `error.code` e `error.message`. Mostre a `message` ao dono; decida pelo `code`.
- 403 (token inválido ou conta bloqueada): pare e avise o dono. 401 ou 429: espere, não insista.
- Timeout, resposta sem corpo ou `CREATE_SHIPMENT_ERROR` em `POST /shipping/create`: o envio
pode ter sido criado mesmo assim. Não repita às cegas. Consulte
`GET /shipments?created_from=<hoje>&cpf=<CPF do destinatário>` para ver se já existe. Se
precisar tentar de novo, use exatamente o mesmo `orderId` e com nova confirmação.
- `DUPLICATE_ORDER` na resposta quer dizer que o pedido já tem envio. Não troque o `orderId`
para contornar: localize o envio existente pela listagem e siga com ele.
- Cancelamento repetido devolve 409 `SHIPMENT_ALREADY_CANCELLED` ou `CANCELLATION_PENDING`:
já está feito, não insista.
- Nunca envie o mesmo pedido duas vezes. Antes de um lote, confira se algum pedido já tem
envio criado.
## Dados pessoais
- Nome, CPF, endereço, telefone e e-mail dos destinatários ficam neste projeto. Não envie
para outros serviços, não cole em issues, commits ou mensagens fora desta conversa.
- Não guarde planilhas de destinatários em pastas públicas.
## O que é no painel web, não na API
Quando a tarefa for uma destas, diga ao dono para abrir o painel em
https://envioecom.com.br em vez de tentar pela API:
- ver ou adicionar saldo (menu Carteira);
- abrir ou responder chamado de suporte (botão Fale conosco);
- pagar envios em "Aguardando pagamento";
- configurar endereço de origem e dados da conta;
- conectar uma loja (Shopify, Yampi, WooCommerce, Tray e outras) em Integrações;
- relatórios, exportações e extrato;
- gerar ou trocar o token (Integrações > Desenvolvedores API).
Se já tiver um arquivo de instruções, cole este conteúdo no fim dele.
Passo 4: peça em português
Com o token na variável e o arquivo na pasta, abra o Claude Code na pasta do projeto e peça o que precisa. Exemplos que funcionam bem:
- "Cote um envio para o CEP 01456-010, caixa 20x15x10 cm, 300 g, valor R$ 110."
- "Crie os envios da planilha pedidos.csv. Me mostre o resumo com preço e total antes de criar."
- "Gere as etiquetas de todos os envios criados hoje e salve em uma pasta."
- "Quais envios da semana ainda não foram postados?"
- "Cancele o envio 853500."
Antes de criar ou cancelar, o Claude mostra o resumo (pedido, destinatário, serviço, preço, total) e espera o seu "ok". Isso está nas regras do arquivo. Se ele não mostrar, peça: "me mostre o resumo antes".
Regras de segurança
- Token é senha. Não cole no chat, não mande por e-mail ou WhatsApp, não compartilhe com terceiros, não suba para o Git.
- Um token por conta. Se suspeitar de vazamento, vá em Integrações, remova a integração Desenvolvedores API e ative de novo: isso gera um token novo e o antigo para de funcionar na hora.
- Confirme antes de gastar. Criar envio debita o saldo imediatamente. Peça sempre o resumo e confira destinatário, serviço e preço.
- Comece com um envio. Faça um envio real de teste e confira no painel antes de rodar um lote. Se precisar, cancele nos primeiros 10 minutos e o valor volta para o saldo.
- Timeout não é erro. Se a criação de um envio não responder, não mande de novo: peça ao Claude para listar os envios de hoje e conferir se já foi criado. Repetir às cegas pode criar e cobrar duas vezes.
- Dados dos seus clientes. Nome, CPF, endereço e telefone dos destinatários ficam no seu computador. Não deixe o assistente enviar esses dados para outros serviços.
- O token faz tudo que a sua conta faz, inclusive alterar dados da conta e até excluí-la. O arquivo de regras proíbe o Claude de tocar nessas rotas; mantenha essas regras no arquivo.
- Não divida o token com a equipe. Cada pessoa que precisa operar a conta deve usar o próprio acesso ao painel. A API é da conta, não de uma pessoa.
Se algo der errado
- "Token inválido" (403): a variável não está definida, o token foi trocado ou a conta está com cadastro incompleto. Confira em Integrações e defina a variável de novo.
- "LABEL_PROCESSING" ao gerar etiqueta: o envio ainda está sendo registrado na transportadora. Espere alguns minutos e peça de novo.
- Erro de validação (422): a mensagem diz o campo com problema (CEP, CPF, medidas). Corrija na planilha e refaça só aquele pedido.
- Saldo insuficiente: o envio fica em "Falha pagamento" e o sistema tenta de novo. Adicione saldo no painel.
- Dúvida ou algo estranho: abra o painel, confira o envio na lista e fale com a gente pelo Fale conosco. Nunca mande o seu token no chamado.
Perguntas frequentes
Usar o Claude Code tem custo na EnvioEcom?
Não. Você paga só os envios que criar, pelo preço da cotação, como no painel. O Claude Code é um produto da Anthropic e tem a própria assinatura.
Funciona com ChatGPT, Codex, Cursor, Copilot ou Gemini?
Sim. A API é a mesma e o arquivo de regras serve para qualquer assistente de IA que execute comandos no seu computador: salve como AGENTS.md (Codex, Cursor, Gemini CLI), .github/copilot-instructions.md (Copilot) ou no arquivo de instruções da sua ferramenta. O que não muda: token em variável de ambiente, confirmar antes de gastar, não repetir criação em timeout. O ChatGPT no navegador, sem acesso ao seu computador, não consegue chamar a API por você.
O token vence?
O token gerado no painel não vence. Ele só deixa de valer se você remover a integração ou gerar um novo.
Posso deixar o Claude criando envios sozinho, sem confirmar?
Dá para tirar a confirmação do arquivo de regras, mas não recomendamos. Um erro na planilha vira envios criados e cobrados. Mantenha a confirmação pelo menos nos lotes.
O Claude consegue ver o meu saldo?
A documentação pública não cobre saldo. Consulte, adicione e acompanhe o saldo no painel, no menu Carteira. Se um envio ficar em "Falha pagamento", é saldo insuficiente.
Preciso de ajuda para começar?
Fale com a gente pelo Fale conosco no painel. A documentação completa da API está em Desenvolvedores API.
