# 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).
