Clientes

Dados básicos de clientes, com inclusão opcional de contato/documento. Nunca retorna clientes de outra empresa que não a da credencial.

GET/clientes

Escopo: clientes:ler

Filtros

Parâmetro	Regra
nome	Busca em nome/razão e fantasia. Mínimo 2 caracteres.
cidade	Igualdade, sem diferenciar maiúsculas/minúsculas.
ativo	`0` ou `1`. Padrão `1`.
documento	CPF/CNPJ exato. Exige `clientes:contato:ler`.
incluir	Único valor: `contato`. Exige `clientes:contato:ler`.

Ordenação (ordenar_por): id, nome, data_cadastro. Padrão id asc.

Campos

Campo	Tipo	Origem
id	integer
nome	string	Física: nome + sobrenome. Jurídica: razão social.
tipo_pessoa	string	`fisica` ou `juridica`.
ativo	boolean
data_cadastro	string/null	RFC 3339 UTC.

Com incluir=contato, soma documento, emails[], telefones[] ({tipo, numero}) e endereco. As listas podem vir vazias; documento e endereco podem ser null.

Campo incluído	Tipo	Regra
documento	string/null	CPF ou CNPJ cadastrado.
emails[]	string[]	Endereços de e-mail não vazios.
telefones[]	object[]	Itens no formato `{tipo, numero}`.
endereco	object/null	Logradouro, número, complemento, bairro, cidade, UF e CEP.

curl -H "Authorization: Bearer SEU_TOKEN" \
  "https://web.synerasis.com.br/api/external/v1/clientes?nome=Silva&por_pagina=20"

$ch = curl_init('https://web.synerasis.com.br/api/external/v1/clientes?nome=Silva&por_pagina=20');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token],
]);
$clientes = json_decode(curl_exec($ch), true);

const resp = await fetch('https://web.synerasis.com.br/api/external/v1/clientes?nome=Silva&por_pagina=20', {
  headers: { 'Authorization': `Bearer ${token}` },
});
const { data, meta } = await resp.json();

Resposta 200

{
  "data": [
    {
      "id": 123,
      "nome": "João da Silva",
      "tipo_pessoa": "fisica",
      "ativo": true,
      "data_cadastro": "2023-05-10T17:32:00Z"
    }
  ],
  "meta": { "pagina": 1, "por_pagina": 20, "total": 1, "total_paginas": 1 }
}

GET/clientes/{id}

Escopo: clientes:ler

{id} precisa ser inteiro positivo. Aceita incluir=contato com as mesmas regras da listagem. ID inexistente, excluído ou de outra empresa retorna 404.

Requisição

curl -H "Authorization: Bearer SEU_TOKEN" \
  "https://web.synerasis.com.br/api/external/v1/clientes/123?incluir=contato"

Resposta 200

{
  "data": {
    "id": 123,
    "nome": "João da Silva",
    "tipo_pessoa": "fisica",
    "ativo": true,
    "data_cadastro": "2023-05-10T17:32:00Z",
    "documento": "123.456.789-00",
    "emails": ["[email protected]"],
    "telefones": [
      { "tipo": "celular", "numero": "(11) 98888-7777" }
    ],
    "endereco": {
      "logradouro": "Rua Exemplo",
      "numero": "100",
      "complemento": null,
      "bairro": "Centro",
      "cidade": "São Paulo",
      "uf": "SP",
      "cep": "01000-000"
    }
  }
}