tray-carrinho-compras

name	tray-carrinho-compras
description	API de carrinho de compras da Tray. Permite criar, consultar, atualizar e excluir carrinhos, incluindo suporte a kits de produtos. Contém 6 endpoints.
when_to_use	Use quando o desenvolvedor mencionar: carrinho, cart, adicionar ao carrinho, GET /carts, POST /carts, PUT /carts, remover do carrinho, carrinho abandonado, carrinho de compras ou checkout.
when_not_to_use	Não use para listar todos os carrinhos da loja (use tray-listagem-carrinho). Não use para pedidos já finalizados (use tray-pedidos).

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=carrinho-compras "<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).

Carrinho de Compras

API para gerenciamento de carrinhos de compras na plataforma Tray.

Referência oficial: https://developers.tray.com.br/#apis-de-carrinho-de-compra

Autenticação

Todas as requisições utilizam query string para autenticação:

?access_token={token}

Endpoints

Método	Endpoint	Descrição
GET	/carts/{session_id}?access_token={token}	Obter dados do carrinho
GET	/carts/{session_id}/complete?access_token={token}	Obter dados completos do carrinho
POST	/carts?access_token={token}	Criar carrinho
POST	/carts/kit?access_token={token}	Criar carrinho com kit de produtos
PUT	/carts/{session_id}?access_token={token}	Atualizar carrinho
DELETE	/carts/{session_id}?access_token={token}	Excluir carrinho

Campos Principais

Campo	Tipo	Descrição
customer_id	integer	ID do cliente associado ao carrinho
product_id	integer	ID do produto
variant_id	integer	ID da variação do produto
quantity	integer	Quantidade do item
session_id	string	Identificador da sessão do carrinho
total	decimal	Valor total do carrinho
subtotal	decimal	Subtotal do carrinho (sem frete e descontos)
shipping_cost	decimal	Custo do frete
coupon_code	string	Código do cupom de desconto aplicado

Exemplos

Obter dados do carrinho

GET /carts/abc123session?access_token={token}

Resposta:

{
  "Cart": {
    "session_id": "abc123session",
    "customer_id": "456",
    "subtotal": "250.00",
    "shipping_cost": "15.00",
    "total": "265.00",
    "coupon_code": "",
    "Products": [
      {
        "product_id": "789",
        "variant_id": "101",
        "quantity": "2",
        "price": "125.00"
      }
    ]
  }
}

Criar carrinho

POST /carts?access_token={token}
Content-Type: application/json

{
  "Cart": {
    "customer_id": 456,
    "product_id": 789,
    "variant_id": 101,
    "quantity": 2
  }
}

Criar carrinho com kit

POST /carts/kit?access_token={token}
Content-Type: application/json

{
  "Cart": {
    "customer_id": 456,
    "kit_id": 10,
    "products": [
      {"product_id": 789, "variant_id": 101, "quantity": 1},
      {"product_id": 790, "variant_id": 102, "quantity": 1}
    ]
  }
}

Atualizar carrinho

PUT /carts/abc123session?access_token={token}
Content-Type: application/json

{
  "Cart": {
    "product_id": 789,
    "variant_id": 101,
    "quantity": 5
  }
}

Excluir carrinho

DELETE /carts/abc123session?access_token={token}

Boas Práticas

• Utilize o endpoint /carts/{session_id}/complete quando precisar de todas as informações do carrinho, incluindo detalhes de produtos e frete.
• O session_id é o identificador único do carrinho — armazene-o de forma segura na sessão do usuário.
• Ao criar carrinhos com kit, certifique-se de que todos os produtos do kit estão disponíveis em estoque.
• Antes de aplicar um cupom via coupon_code, valide se o cupom existe e está ativo utilizando a API de cupons.
• Ao atualizar quantidades, verifique o estoque disponível para evitar erros.
• Exclua carrinhos abandonados periodicamente para manter a base limpa.

Como Usar no Claude Code

Exemplos de Prompt

• "cria um carrinho para o cliente 456 com 2 unidades do produto 789 variação M"
• "busca os dados completos do carrinho da sessão abc123"
• "cria um carrinho com o kit ID 10 incluindo todos os seus componentes"
• "implementa a lógica de recuperação de carrinho abandonado"

O que o Claude faz

1. Gera o código de criação de carrinho com wrapper Cart e os campos necessários
2. Diferencia POST /carts (produto simples) de POST /carts/kit (bundle)
3. Usa /carts/{session_id}/complete para consultas com dados completos de produtos e frete
4. Implementa lógica de persistência do session_id na sessão do usuário

O que você recebe

• Código de criação de carrinho com customer_id, product_id e quantity
• Código para carrinho com kit e múltiplos componentes
• Código de consulta completa com dados de produtos, frete e cupom
• Exemplo de fluxo de atualização de quantidade

Pré-requisitos

• access_token configurado
• customer_id do cliente (ou sessão anônima)
• product_id e variant_id dos produtos