tray-clientes

name	tray-clientes
description	API de Clientes da Tray. Utilize quando o desenvolvedor precisar gerenciar dados de clientes da loja: listagem, consulta, cadastro, atualização e exclusão. Inclui campos de pessoa física (CPF) e jurídica (CNPJ), validações brasileiras e gestão de newsletter.
when_to_use	Use quando o desenvolvedor mencionar: cliente, cadastrar cliente, atualizar cliente, CPF, CNPJ, pessoa física, pessoa jurídica, GET /customers, POST /customers, PUT /customers, endereço de cliente, validação de CPF, validação de CNPJ ou opt-in newsletter.
when_not_to_use	Não use para endereços do cliente (use tray-enderecos-cliente), perfis/grupos de clientes (use tray-perfis-cliente) nem para inscrições em newsletter (use tray-newsletter).

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).
5. Execute node skills/clientes/scripts/validate.mjs '<payload_json>' para confirmar a estrutura do payload que vai gerar. O validador checa apenas estrutura (campos obrigatórios, tipos e campos desconhecidos), nunca valores reais — então monte um payload sintético com placeholders sempre que os valores vierem de variáveis de ambiente, da entrada do usuário ou de outras chamadas. Exemplo: node skills/clientes/scripts/validate.mjs '{"Customer":{"name":"<nome>","email":"<email>"}}'. Corrija todos os erros antes de retornar o código ao usuário. Até 3 tentativas — se persistir, explique o problema ao usuário.

API de Clientes — Tray

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

Endpoints

Método	Endpoint	Descrição
GET	/customers	Listagem de clientes com paginação e filtros
GET	/customers/:id	Consultar dados do cliente por ID
POST	/customers	Cadastrar novo cliente
PUT	/customers/:id	Atualizar dados do cliente
DELETE	/customers/:id	Excluir cliente

Autenticação: ?access_token={token}

Campos do Cliente

Campo	Tipo	Descrição
name	string	Nome completo
email	string	E-mail (obrigatório, único)
cpf	string	CPF (pessoa física)
cnpj	string	CNPJ (pessoa jurídica)
rg	string	RG
phone	string	Telefone fixo
cellphone	string	Celular
birth_date	date	Data de nascimento (YYYY-MM-DD)
gender	string	Gênero
company_name	string	Razão social (PJ)
newsletter	number	0=não inscrito, 1=inscrito na newsletter
created_at	datetime	Data de cadastro

Validações Brasileiras

• CPF: deve ser um CPF válido (11 dígitos, algoritmo de verificação)
• CNPJ: deve ser um CNPJ válido (14 dígitos, algoritmo de verificação)

Corpo da Requisição (POST/PUT)

{
  "Customer": {
    "name": "João Silva",
    "email": "[e-mail]",
    "cpf": "12345678901",
    "phone": "1133334444",
    "cellphone": "11999998888",
    "newsletter": 1
  }
}

Paginação

limit (máximo 50, padrão 30), page.

Recursos Relacionados

• Endereços: gerenciados via API separada — consulte o skill tray-enderecos-cliente
• Perfis: gerenciados via API separada — consulte o skill tray-perfis-cliente

Boas Práticas

1. E-mail único — o e-mail é identificador único do cliente na plataforma
2. Valide CPF/CNPJ — antes de enviar, valide localmente para evitar erros 400
3. Newsletter opt-in — respeite a LGPD, envie newsletter: 1 apenas com consentimento
4. Webhook — configure o webhook customer para receber notificações de alterações

Como Usar no Claude Code

Exemplos de Prompt

• "cadastra um novo cliente pessoa física com CPF e telefone"
• "busca o cliente pelo e-mail [e-mail]"
• "lista todos os clientes inscritos na newsletter"
• "implementa a sincronização de clientes do meu ERP para a Tray"

O que o Claude faz

1. Gera o código de criação com wrapper Customer e validação de CPF/CNPJ
2. Usa filtros de listagem (email, cpf, newsletter) para buscas específicas
3. Inclui tratamento de erro para e-mail duplicado (cliente já existente)
4. Sugere o fluxo completo: cliente → endereço → perfil quando necessário

O que você recebe

• Código de criação com wrapper {"Customer": {...}} e campos obrigatórios
• Validação local de CPF/CNPJ antes da chamada à API
• Código de busca por e-mail ou CPF via filtros de listagem
• Orientação sobre campos LGPD (newsletter)

Pré-requisitos

• access_token configurado
• E-mail único por cliente