Tray Multicd

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 Multi-CD (Centros de Distribuição) — Tray

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

Endpoints — Centros de Distribuição

Endpoints — Estoque por CD

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

Campos do Centro de Distribuição

Campos do Estoque por CD

Paginação

Resposta inclui: total, page, offset, limit, maxLimit

Corpo da Requisição — Criar CD (POST)

{
  "DistributionCenter": {
    "name": "CD São Paulo",
    "zip_code": "01310100",
    "address": "Av. Paulista, 1000",
    "city": "São Paulo",
    "state": "SP",
    "priority": 1,
    "active": 1
  }
}

Corpo da Requisição — Atualizar CD (PUT)

{
  "DistributionCenter": {
    "name": "CD São Paulo - Matriz",
    "priority": 1,
    "active": 1
  }
}

Corpo da Requisição — Atualizar Estoque no CD (PUT)

Produto:

{
  "DistributionCenterProduct": {
    "stock": 150
  }
}

Variação:

{
  "DistributionCenterVariant": {
    "stock": 75
  }
}

Respostas

Exemplo de Resposta — Listar CDs

{
  "paging": {
    "total": 3,
    "page": 1,
    "offset": 0,
    "limit": 30,
    "maxLimit": 50
  },
  "DistributionCenters": [
    {
      "DistributionCenter": {
        "id": "1",
        "name": "CD São Paulo",
        "zip_code": "01310100",
        "address": "Av. Paulista, 1000",
        "city": "São Paulo",
        "state": "SP",
        "priority": "1",
        "active": "1"
      }
    },
    {
      "DistributionCenter": {
        "id": "2",
        "name": "CD Belo Horizonte",
        "zip_code": "30130000",
        "address": "Av. Afonso Pena, 500",
        "city": "Belo Horizonte",
        "state": "MG",
        "priority": "2",
        "active": "1"
      }
    }
  ]
}

Exemplo de Resposta — Estoque por CD

{
  "DistributionCenterProducts": [
    {
      "DistributionCenterProduct": {
        "product_id": "100",
        "stock": "50",
        "distribution_center_id": "1"
      }
    },
    {
      "DistributionCenterProduct": {
        "product_id": "101",
        "stock": "30",
        "distribution_center_id": "1"
      }
    }
  ]
}

Lógica de Seleção do CD

Quando um pedido é realizado, a Tray seleciona o CD com base nos seguintes critérios:

1. Disponibilidade — o CD deve ter estoque suficiente para todos os itens
2. Prioridade — CDs com menor número de prioridade são preferidos
3. Proximidade — o CEP do CD é comparado com o CEP de entrega para otimizar frete e prazo
4. Status ativo — apenas CDs com active: 1 são considerados

Webhooks de Estoque

Quando o MultiCD está ativo, a Tray dispara webhooks nos escopos product_stock e variant_stock para qualquer alteração de estoque em qualquer CD, permitindo sincronização em tempo real com ERPs e sistemas externos.

Payload do Webhook

O formato é application/x-www-form-urlencoded (igual a todos os webhooks da Tray):

seller_id=391250&scope_id=100&scope_name=product_stock&act=update&app_code=718&url_notification=https://suaurldenotificacao

O scope_id corresponde ao ID do produto ou variação alterada. Após receber o webhook, consulte GET /multicd/stock/detailed/product/:id para obter os estoques atualizados por CD.

Para detalhes completos sobre formato de payload, campos e lógica de retry, consulte o skill tray-webhooks.

Boas Práticas

1. CEP do CD é fundamental — o CEP do CD é usado para calcular frete; informe o CEP correto do endereço físico
2. Prioridade planejada — defina prioridades estrategicamente (ex: CD mais central com prioridade 1)
3. Estoque sincronizado — mantenha o estoque de cada CD atualizado em tempo real via integração
4. Estoque total — o estoque exibido na vitrine é a soma do estoque de todos os CDs ativos
5. Variações por CD — se o produto tem variações, gerencie o estoque de cada variação individualmente por CD
6. Desative antes de excluir — mude active para 0 antes de excluir um CD para evitar impacto em pedidos
7. Teste o cálculo de frete — após configurar CDs, teste o frete com diferentes CEPs usando o skill tray-frete (GET /shippings/cotation/)
8. Recursos relacionados — consulte os skills tray-frete, tray-configuracao-frete e tray-webhooks

Como Usar no Claude Code

Exemplos de Prompt

• "cadastra os centros de distribuição de SP (prioritário) e MG"
• "atualiza o estoque do produto 100 para 150 unidades no CD de São Paulo"
• "implementa a sincronização de estoque por CD via webhook"
• "consulta o estoque detalhado do produto 100 em todos os CDs"

O que o Claude faz

1. Gera o código de criação de CD com wrapper DistributionCenter e configuração de prioridade
2. Gera o código de atualização de estoque por CD (produto ou variação)
3. Implementa o fluxo de recebimento de webhook product_stock e atualização via API
4. Demonstra a consulta de estoque detalhado por CD

O que você recebe

• Código de criação de CDs com prioridade e cobertura regional
• Código de atualização de estoque: PUT /multicd/distribution-centers/:id/stock
• Fluxo de sincronização via webhook product_stock + consulta detalhada
• Consulta de estoque por produto em todos os CDs

Pré-requisitos

• access_token configurado
• MultiCD ativo na loja (configurado no painel Tray)
• Produtos já cadastrados com product_id disponível