tray-configuracao-frete

name	tray-configuracao-frete
description	API de Configuração de Frete da Tray. Utilize quando o desenvolvedor precisar gerenciar métodos de envio e tabelas de faixa de CEP da loja, incluindo criação, atualização e exclusão de formas de envio e suas respectivas tabelas de CEP com faixas de peso, preços e prazos. Essencial para configurar regras de frete personalizadas por região e faixa de peso.
when_to_use	Use quando o desenvolvedor mencionar: configurar frete, método de envio, tabela de frete, faixa de CEP, faixa de peso, prazo de entrega, POST /freights_settings, forma de envio personalizada, frete por região ou frete customizado.
when_not_to_use	Não use para calcular valor de frete em tempo real (use tray-frete). Use apenas para criar ou atualizar métodos de envio e tabelas de CEP.

MANDATORY: Tool Call Required Before Answering

Esta chamada é OBRIGATÓRIA, não opcional. Execute-a antes de gerar qualquer código ou payload. Se você está respondendo sem ter chamado a ferramenta abaixo, pare e chame agora.

Buscar documentação atualizada (sempre)

node skills/tray-dev/scripts/search_docs.mjs --topic=configuracao-frete "<termo da pergunta>"

• <TOPIC_SLUG>: ver tabela em skills/tray-dev/SKILL.md.
• Use os trechos retornados como fonte primária; este SKILL.md é resumo.

Nota: este recurso ainda não tem validate.mjs local. Você é responsável por revisar campos obrigatórios contra a doc retornada e o resumo abaixo.

Antes de responder

Execute estas verificações antes de gerar qualquer payload ou código:

1. Confirme o método HTTP e endpoint correto para a operação solicitada.
2. Identifique os campos obrigatórios listados neste documento — não omita nenhum.
3. Verifique que access_token não aparece como literal string no código gerado.
4. Confirme que esta é a skill correta para o recurso (leia when_not_to_use no frontmatter).

API de Configuração de Frete — Tray

Documentação oficial: https://developers.tray.com.br/#api-de-configuracao-de-forma-de-frete

Endpoints — Métodos de Envio com Integração Externa (Gateway)

Método	Endpoint	Descrição
POST	/shippings/method/gateway	Cadastrar forma de envio com integração externa
PUT	/shippings/method/gateway/:id	Atualizar forma de envio
DELETE	/shippings/method/gateway/:id	Excluir forma de envio

Endpoints — Tabelas de CEP

Método	Endpoint	Descrição
POST	/shippings/method/zipcode_table	Cadastrar tabela de CEP
PUT	/shippings/method/zipcode_table/:id	Atualizar tabela de CEP
DELETE	/shippings/method/zipcode_table/:id	Excluir tabela de CEP

Autenticação: ?access_token={token} em todas as chamadas.

Campos do Método de Envio

Campo	Tipo	Obrigatório	Descrição
id	number	—	ID do método de envio (retornado pela API)
name	string	Sim	Nome do método (ex: "PAC", "SEDEX", "Motoboy")
active	number	Não	1 = ativo, 0 = inativo
type	string	Não	Tipo do método (ex: "correios", "custom", "gateway")
delivery_time	number	Não	Prazo padrão de entrega em dias úteis
additional_delivery_time	number	Não	Dias adicionais ao prazo de entrega
free_shipping_value	decimal	Não	Valor mínimo do pedido para frete grátis

Campos da Faixa de CEP

Campo	Tipo	Obrigatório	Descrição
id	number	—	ID da faixa de CEP (retornado pela API)
zip_start	string	Sim	CEP inicial da faixa (ex: "01000000")
zip_end	string	Sim	CEP final da faixa (ex: "09999999")
weight_start	number	Sim	Peso inicial da faixa em gramas
weight_end	number	Sim	Peso final da faixa em gramas
price	decimal	Sim	Valor do frete para esta faixa
delivery_time	number	Não	Prazo de entrega em dias úteis para esta faixa
additional_price_per_kg	decimal	Não	Valor adicional por kg excedente

Corpo da Requisição — Criar Método de Envio (POST)

{
  "ShippingMethod": {
    "name": "Transportadora Regional",
    "active": 1,
    "type": "custom",
    "delivery_time": 5,
    "additional_delivery_time": 2,
    "free_shipping_value": "299.90"
  }
}

Corpo da Requisição — Atualizar Método de Envio (PUT)

{
  "ShippingMethod": {
    "name": "Transportadora Regional - Atualizado",
    "active": 1,
    "delivery_time": 4
  }
}

Corpo da Requisição — Criar Faixa de CEP (POST)

{
  "ZipRange": {
    "zip_start": "01000000",
    "zip_end": "09999999",
    "weight_start": 0,
    "weight_end": 5000,
    "price": "15.90",
    "delivery_time": 5,
    "additional_price_per_kg": "2.50"
  }
}

Corpo da Requisição — Atualizar Faixa de CEP (PUT)

{
  "ZipRange": {
    "price": "18.90",
    "delivery_time": 4
  }
}

Respostas

Operação	Código	Mensagem
Criação	201	{"message": "Created", "id": 10, "code": 201}
Atualização	200	{"message": "Saved", "id": 10, "code": 200}
Exclusão	200	{"message": "Deleted", "id": 10, "code": 200}

Fluxo de Configuração

1. Crie o método de envio — POST /shippings/method/gateway com nome e configurações gerais
2. Adicione tabelas de CEP — para cada região, crie tabelas de CEP com POST /shippings/method/zipcode_table
3. Configure pesos e preços — defina faixas de peso com preços específicos para cada região
4. Ative o método — garanta que o campo active esteja como 1

Exemplo de Estrutura Completa

Método: "Transportadora SP Interior"
├── Faixa CEP: 13000000 - 13999999 (Campinas)
│   ├── 0g - 5000g  → R$ 12,90 (3 dias)
│   └── 5001g - 30000g → R$ 25,90 (4 dias)
├── Faixa CEP: 14000000 - 14999999 (Ribeirão Preto)
│   ├── 0g - 5000g  → R$ 18,90 (5 dias)
│   └── 5001g - 30000g → R$ 35,90 (6 dias)

Boas Práticas

1. Evite sobreposição de faixas — não crie faixas de CEP ou peso que se sobreponham no mesmo método
2. Cubra todas as faixas de peso — garanta que haja faixas de peso para cobrir todos os produtos da loja
3. Teste após configurar — use a API de Frete (GET /shipping) para validar que o cálculo retorna resultados corretos
4. Frete grátis condicional — use free_shipping_value para incentivar pedidos de maior valor
5. Dias adicionais — use additional_delivery_time para incluir tempo de manuseio/embalagem
6. Recursos relacionados — consulte o skill tray-frete (GET /shippings/cotation/) para calcular frete e o skill tray-multicd para configuração de múltiplos centros de distribuição

Como Usar no Claude Code

Exemplos de Prompt

• "configura uma transportadora regional para São Paulo com tabela de CEP e faixas de peso"
• "cria o método de envio Motoboy com frete grátis para pedidos acima de R$ 150"
• "adiciona uma faixa de CEP nova para o método de envio ID 10"
• "atualiza o prazo de entrega da transportadora ID 5"

O que o Claude faz

1. Guia o fluxo de 3 etapas: criar método → adicionar tabelas de CEP → configurar faixas de peso/preço
2. Gera o código com wrappers ShippingMethod e ZipRange corretos
3. Exemplifica a estrutura de faixas de CEP e peso com preços por região
4. Valida que não há sobreposição de faixas de CEP ou peso

O que você recebe

• Código de criação do método de envio com POST /shippings/method/gateway
• Código de tabelas de CEP com faixas de peso, preços e prazos
• Estrutura completa de configuração de uma transportadora regional
• Código de atualização e exclusão de faixas existentes

Pré-requisitos

• access_token configurado
• Tabela de preços e prazos da transportadora por CEP e peso