Clientes

Gerencie o cadastro de clientes da sua agência. Suporta Pessoa Física (PF) e Pessoa Jurídica (PJ).

GET /v1/clients

Lista todos os clientes do time.

Query Parameters

Parâmetro	Tipo	Padrão	Descrição
`page`	number	1	Página atual
`limit`	number	20	Itens por página (máx: 100)
`type`	string	—	Filtrar por tipo: `PF`, `PJ`
`status`	string	—	Filtrar: `active`, `inactive`
`search`	string	—	Buscar por nome, email, CPF ou CNPJ
`sort`	string	`-created_at`	Ordenação. Campos: `full_name`, `email`, `created_at`, `updated_at`, `is_active`

Request

curl -X GET "https://app.sonar.marketing/api/v1/clients?type=PJ&status=active" \
  -H "Authorization: Bearer snr_live_sua_chave_aqui"

Response

{
  "success": true,
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "type": "PJ",
      "name": "TechStore Brasil Ltda",
      "display_name": "TechStore",
      "email": "marketing@techstore.com.br",
      "phone": "+55 11 99999-8888",
      "mobile_phone": null,
      "whatsapp": "+55 11 99999-8888",
      "cpf": null,
      "cnpj": "12.345.678/0001-90",
      "legal_name": "TechStore Brasil Comércio Digital Ltda",
      "trade_name": "TechStore",
      "source": "indicacao",
      "status": "active",
      "notes": null,
      "tags": ["ecommerce"],
      "address": {
        "street": "Av. Paulista",
        "number": "1000",
        "complement": "Sala 101",
        "neighborhood": "Bela Vista",
        "city": "São Paulo",
        "state": "SP",
        "zip_code": "01310-100",
        "country": "Brasil"
      },
      "created_at": "2026-01-15T10:30:00Z",
      "updated_at": "2026-02-04T14:20:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 150,
    "pages": 8
  }
}

POST /v1/clients

Cria um novo cliente.

Request Body

Campo	Tipo	Obrigatório	Descrição
`name`	string	Sim	Nome completo ou razão social
`type`	string	Sim	`PF` ou `PJ`
`display_name`	string	Não	Nome de exibição
`email`	string	Não	Email
`phone`	string	Não	Telefone
`mobile_phone`	string	Não	Celular
`whatsapp`	string	Não	WhatsApp
`cpf`	string	Não	CPF (apenas PF)
`rg`	string	Não	RG (apenas PF)
`birth_date`	string	Não	Data nascimento YYYY-MM-DD (apenas PF)
`gender`	string	Não	Gênero (apenas PF)
`cnpj`	string	Não	CNPJ (apenas PJ)
`legal_name`	string	Não	Razão social (apenas PJ)
`trade_name`	string	Não	Nome fantasia (apenas PJ)
`state_registration`	string	Não	Inscrição estadual (apenas PJ)
`address`	object	Não	Endereço (street, number, complement, neighborhood, city, state, zip_code, country)
`source`	string	Não	Origem do cliente
`notes`	string	Não	Observações
`tags`	array	Não	Tags

Request

curl -X POST https://app.sonar.marketing/api/v1/clients \
  -H "Authorization: Bearer snr_live_sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "PJ",
    "name": "TechStore Brasil Ltda",
    "email": "marketing@techstore.com.br",
    "cnpj": "12.345.678/0001-90",
    "phone": "+55 11 99999-8888",
    "tags": ["ecommerce"]
  }'

Response (201)

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "type": "PJ",
    "name": "TechStore Brasil Ltda",
    "email": "marketing@techstore.com.br",
    "cnpj": "12.345.678/0001-90",
    "status": "active",
    "tags": ["ecommerce"],
    "created_at": "2026-02-04T10:30:00Z",
    "updated_at": "2026-02-04T10:30:00Z"
  }
}

GET /v1/clients/:id

Busca um cliente específico por ID (UUID).

curl -X GET https://app.sonar.marketing/api/v1/clients/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer snr_live_sua_chave_aqui"

PUT /v1/clients/:id

Atualiza campos de um cliente. Envie apenas os campos que deseja alterar.

curl -X PUT https://app.sonar.marketing/api/v1/clients/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer snr_live_sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+55 11 88888-7777",
    "notes": "Cliente VIP"
  }'

DELETE /v1/clients/:id

Desativa o cliente (soft delete — seta is_active = false).

curl -X DELETE https://app.sonar.marketing/api/v1/clients/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer snr_live_sua_chave_aqui"

Response

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "inactive",
    "deactivated_at": "2026-02-04T15:30:00Z"
  }
}

Erros Comuns

Código	Erro	Solução
`400`	`Campo 'name' é obrigatório`	Inclua o campo `name`
`400`	`Campo 'type' é obrigatório`	Use `PF` ou `PJ`
`404`	`Cliente não encontrado`	Verifique o UUID
`422`	`CPF já cadastrado`	CPF duplicado no team
`422`	`CNPJ já cadastrado`	CNPJ duplicado no team

Clientes

On this page