tray-clientes

MANDATORY: Tool Call(s) Required Before Answering

• OBRIGATÓRIO: node skills/tray-dev/scripts/search_docs.mjs "<termo>" — confirme o comportamento da API antes de gerar código.
• OBRIGATÓRIO: node skills/clientes/scripts/validate.mjs '<payload_json>' — valide a estrutura do payload antes de retornar código ao usuário.

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	Obrigatório (create)	Descrição
name	string	Sim	Nome completo
email	string	Sim	E-mail (único na plataforma)
birth_date	date	Sim	Data de nascimento (YYYY-MM-DD)
cpf	string	Não¹	CPF (pessoa física)
cnpj	string	Não¹	CNPJ (pessoa jurídica)
rg	string	Não	RG
phone	string	Não	Telefone fixo
cellphone	string	Não	Celular
gender	string	Não	Gênero
company_name	string	Não	Razão social (PJ)
newsletter	number	Não	0=não inscrito, 1=inscrito na newsletter
created_at	datetime	—	Data de cadastro (retornado pela API)

⚠️ birth_date é obrigatório na criação (POST /customers). Omitir resulta em HTTP 400 — é a causa #1 de falha ao cadastrar cliente.

¹ cpf (PF) ou cnpj (PJ) conforme o tipo de cliente; informe o que corresponder à pessoa.

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": "[email protected]",
    "birth_date": "1990-05-20",
    "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 [email protected]"
• "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