Clientes

Gerencie os clientes no gateway de pagamentos Asaas

Endpoints

GET /api/customers

Lista todos os clientes cadastrados.

Resposta
[
  {
    "id": "string",
    "name": "string",
    "cpfCnpj": "string",
    "email": "string",
    "phone": "string",
    "mobilePhone": "string",
    "address": "string",
    "addressNumber": "string",
    "complement": "string",
    "province": "string",
    "postalCode": "string",
    "externalReference": "string",
    "notificationDisabled": boolean,
    "additionalEmails": "string[]",
    "municipalInscription": "string",
    "stateInscription": "string",
    "observations": "string",
    "groupName": "string",
    "company": "string",
    "asaasId": "string",
    "createdAt": "string",
    "updatedAt": "string"
  }
]

POST /api/customers

Cria um novo cliente.

Request Body
{
  "name": "string",                    // Nome completo ou razão social
  "cpfCnpj": "string",                // CPF ou CNPJ (apenas números)
  "email": "string",                  // Email principal
  "phone": "string",                  // Telefone fixo (opcional)
  "mobilePhone": "string",            // Telefone celular (opcional)
  "address": "string",                // Endereço (opcional)
  "addressNumber": "string",          // Número do endereço (opcional)
  "complement": "string",             // Complemento (opcional)
  "province": "string",               // Bairro (opcional)
  "postalCode": "string",             // CEP (opcional)
  "externalReference": "string",      // Referência externa (opcional)
  "notificationDisabled": boolean,    // Desabilita notificações (opcional)
  "additionalEmails": "string[]",     // Emails adicionais (opcional)
  "municipalInscription": "string",   // Inscrição municipal (opcional)
  "stateInscription": "string",       // Inscrição estadual (opcional)
  "observations": "string",           // Observações (opcional)
  "groupName": "string",              // Nome do grupo (opcional)
  "company": "string"                 // Nome da empresa (opcional)
}
Exemplo
curl -X POST "http://seu-servidor/api/customers" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "João da Silva",
    "cpfCnpj": "12345678909",
    "email": "joao@email.com",
    "mobilePhone": "11999999999",
    "address": "Rua das Flores",
    "addressNumber": "123",
    "complement": "Apto 45",
    "province": "Centro",
    "postalCode": "12345678"
  }'

GET /api/customers/:id

Obtém detalhes de um cliente específico.

Exemplo
curl -X GET "http://seu-servidor/api/customers/123"

GET /api/customers/cpf-cnpj/:cpfCnpj

Busca um cliente pelo CPF/CNPJ.

Exemplo
curl -X GET "http://seu-servidor/api/customers/cpf-cnpj/12345678909"

PATCH /api/customers/:id

Atualiza um cliente existente.

Request Body
{
  "name": "string",                    // Opcional
  "email": "string",                  // Opcional
  "phone": "string",                  // Opcional
  "mobilePhone": "string",            // Opcional
  "address": "string",                // Opcional
  "addressNumber": "string",          // Opcional
  "complement": "string",             // Opcional
  "province": "string",               // Opcional
  "postalCode": "string",             // Opcional
  "externalReference": "string",      // Opcional
  "notificationDisabled": boolean,    // Opcional
  "additionalEmails": "string[]",     // Opcional
  "municipalInscription": "string",   // Opcional
  "stateInscription": "string",       // Opcional
  "observations": "string",           // Opcional
  "groupName": "string",              // Opcional
  "company": "string"                 // Opcional
}
Exemplo
curl -X PATCH "http://seu-servidor/api/customers/123" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "novo.email@exemplo.com",
    "mobilePhone": "11988888888",
    "address": "Nova Rua",
    "addressNumber": "456"
  }'

DELETE /api/customers/:id

Remove um cliente.

Exemplo
curl -X DELETE "http://seu-servidor/api/customers/123"
Sincronização com Asaas

Todos os clientes são sincronizados automaticamente com o Asaas. O campo asaasId é usado para manter a referência com o cliente no Asaas.

Boas Práticas
  • Mantenha os dados do cliente sempre atualizados
  • Use o CPF/CNPJ como identificador único do cliente
  • Forneça pelo menos um email e um telefone para contato
  • Preencha o endereço completo para emissão de boletos
  • Use o campo externalReference para referência do seu sistema