aibot88 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_tokennão aparece como literal string no código gerado. - Confirme que esta é a skill correta para o recurso (leia
when_not_to_useno frontmatter). - 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": "joao@exemplo.com",
"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
- E-mail único — o e-mail é identificador único do cliente na plataforma
- Valide CPF/CNPJ — antes de enviar, valide localmente para evitar erros 400
- Newsletter opt-in — respeite a LGPD, envie
newsletter: 1apenas com consentimento - Webhook — configure o webhook
customerpara 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 joao@exemplo.com"
- "lista todos os clientes inscritos na newsletter"
- "implementa a sincronização de clientes do meu ERP para a Tray"
O que o Claude faz
- Gera o código de criação com wrapper
Customere validação de CPF/CNPJ - Usa filtros de listagem (
email,cpf,newsletter) para buscas específicas - Inclui tratamento de erro para e-mail duplicado (cliente já existente)
- 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_tokenconfigurado- E-mail único por cliente