| name | tray-perfis-cliente |
| description | API de Perfis de Clientes da Tray. Utilize quando o desenvolvedor precisar gerenciar perfis (grupos/segmentos) de clientes da loja, incluindo criação, consulta, atualização, exclusão e associação/desassociação de clientes a perfis. Útil para segmentação de clientes, preços diferenciados (B2B/B2C) e regras de desconto por grupo.
|
| when_to_use | Use quando o desenvolvedor mencionar: perfil de cliente, grupo de clientes, segmento, customer profile, GET /customer_profiles, POST /customer_profiles, B2B vs B2C, associar cliente a perfil ou desconto por grupo de clientes.
|
| when_not_to_use | Não use para dados cadastrais do cliente (use tray-clientes) nem para listas de preço B2B (use tray-listas-preco-b2b).
|
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=clientes "<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:
- Confirme o método HTTP e endpoint correto para a operação solicitada.
- Identifique os campos obrigatórios listados neste documento — não omita nenhum.
- Verifique que
access_token não aparece como literal string no código gerado.
- Confirme que esta é a skill correta para o recurso (leia
when_not_to_use no frontmatter).
API de Perfis de Clientes — Tray
Documentação oficial: https://developers.tray.com.br/#api-de-clientes
Endpoints
| Método | Endpoint | Descrição |
|---|
| GET | /customers/profiles | Listar perfis de clientes |
| GET | /customers/profiles/:id | Consultar dados de um perfil por ID |
| POST | /customers/profiles | Cadastrar novo perfil |
| PUT | /customers/profiles/:id | Atualizar dados do perfil |
| DELETE | /customers/profiles/:id | Excluir perfil |
| POST | /customers/:customer_id/profiles/:profile_id | Associar cliente a um perfil |
| DELETE | /customers/:customer_id/profiles/:profile_id | Desassociar cliente de um perfil |
Autenticação: ?access_token={token} em todas as chamadas.
Campos do Perfil
| Campo | Tipo | Obrigatório | Descrição |
|---|
id | number | — | ID do perfil (retornado pela API) |
name | string | Sim | Nome do perfil (ex: "Atacado", "VIP", "Revendedor") |
description | string | Não | Descrição do perfil |
approved | number | Não | 1 = perfil ativo/aprovado, 0 = inativo |
Paginação
| Parâmetro | Descrição |
|---|
limit | Itens por página (máximo 50, padrão 30) |
page | Número da página |
Corpo da Requisição — Criar/Atualizar Perfil (POST/PUT)
{
"Profile": {
"name": "Atacado",
"description": "Clientes com volume de compra acima de R$ 5.000/mês",
"approved": 1
}
}
Associar Cliente a Perfil
Endpoint: POST /customers/:customer_id/profiles/:profile_id
Não requer corpo na requisição. O cliente é associado ao perfil informado na URL.
Exemplo:
POST /customers/50/profiles/3?access_token={token}
Desassociar Cliente de Perfil
Endpoint: DELETE /customers/:customer_id/profiles/:profile_id
Remove a associação entre o cliente e o perfil.
Exemplo:
DELETE /customers/50/profiles/3?access_token={token}
Respostas
| Operação | Código | Mensagem |
|---|
| Criação de perfil | 201 | {"message": "Created", "id": 3, "code": 201} |
| Atualização de perfil | 200 | {"message": "Saved", "id": 3, "code": 200} |
| Exclusão de perfil | 200 | {"message": "Deleted", "id": 3, "code": 200} |
| Associação | 200 | {"message": "Saved", "code": 200} |
| Desassociação | 200 | {"message": "Deleted", "code": 200} |
Exemplo de Resposta — Listar Perfis
{
"Profiles": [
{
"Profile": {
"id": "1",
"name": "Varejo",
"description": "Clientes do segmento varejo",
"approved": "1"
}
},
{
"Profile": {
"id": "2",
"name": "Atacado",
"description": "Clientes com volume de compra elevado",
"approved": "1"
}
}
]
}
Casos de Uso
- B2B/B2C — crie perfis "Pessoa Física" e "Pessoa Jurídica" para aplicar regras diferentes
- Listas de Preço — associe perfis a listas de preço diferenciadas (consulte o skill
tray-listas-preco-b2b)
- Descontos por grupo — configure descontos automáticos baseados no perfil do cliente
- Aprovação manual — use o campo
approved para controlar a ativação de perfis que requerem aprovação
Boas Práticas
- Nomes descritivos — use nomes claros para facilitar a gestão (ex: "Atacado - Gold", "Revendedor Autorizado")
- Perfil antes do cliente — crie o perfil antes de associar clientes a ele
- Um cliente, múltiplos perfis — um cliente pode pertencer a vários perfis simultaneamente
- Não exclua perfis em uso — verifique se há clientes associados antes de excluir um perfil
- Integração com preços — combine perfis com listas de preço B2B para oferecer preços diferenciados
- Recursos relacionados — consulte os skills
tray-clientes e tray-listas-preco-b2b para operações complementares
Como Usar no Claude Code
Exemplos de Prompt
- "cria os perfis Atacado e Varejo e associa o cliente 50 ao perfil Atacado"
- "lista todos os perfis de cliente disponíveis na loja"
- "implementa segmentação B2B/B2C com perfis e preços diferenciados"
- "remove o cliente 50 do perfil Varejo e migra para Atacado"
O que o Claude faz
- Gera o código de criação de perfil com wrapper
Profile
- Gera o código de associação e desassociação (sem body, apenas IDs na URL)
- Explica a combinação com
tray-listas-preco-b2b para preços diferenciados
- Demonstra o fluxo completo de segmentação B2B
O que você recebe
- Código de criação de perfil com nome e descrição
- Código de associação:
POST /customers/:id/profiles/:profile_id
- Código de desassociação:
DELETE /customers/:id/profiles/:profile_id
- Orientação sobre combinação com listas de preço B2B
Pré-requisitos
access_token configurado- Clientes já cadastrados com
customer_id disponível via tray-clientes
