Clientes
A API de clientes oferece métodos para a manipulação eficiente das informações dos clientes, incluindo operações CRUD (cadastrar, visualizar, editar e deletar). Com funcionalidades adicionais para filtragem e pesquisa detalhada, a API facilita a gestão de dados e a tomada de decisões informadas.
Introdução
Nesta documentação, detalhamos os campos que você pode esperar manipular ao interagir com a API. Cada campo é descrito para esclarecer sua função e o tipo de dado esperado, como nome, contato, e informações demográficas, garantindo que você possa fornecer ou obter informações precisas.
As URLs da API são especificadas para cada operação possível, desde a listagem de todos os clientes até a atualização de um registro específico. Ao seguir as URLs e métodos HTTP detalhados, você será capaz de realizar operações de CRUD de forma intuitiva e eficaz.
Veja abaixo:
URLs
| Método | URL | Ação | Descrição |
|---|---|---|---|
| GET | /api/v1/clients | Listar | Lista todos os clientes |
| GET | /api/v1/clients/{id} | Visualizar | Exibe um determinado cliente pelo ID |
| PUT | /api/v1/clients/{id} | Editar | Atualiza um determinado cliente |
| DELETE | /api/v1/clients/{id} | Deletar | Remove um cliente na base de dados |
| POST | /api/v1/clients | Cadastrar | Cria um ou mais clientes na base de dados |
Campos
Os dados dos clientes devem ser enviados no formato JSON. Abaixo estão os campos que podem ser incluídos no corpo da solicitação:
| Campo | Tipo | Descrição | Obrigatório | Val. Def. |
|---|---|---|---|---|
| tipocadastro | boolean | 0 = Pessoa Física / 1 = Pessoa Jurídica | Não | 0 = Pessoa Física |
| nome | string | Nome cliente | Sim | N/A |
| string | Email do cliente | Não | N/A | |
| email2 | string | Email secundário | Não | N/A |
| cep | string | CEP pode ser formatado ou não | Não | N/A |
| endereco | string | Endereço do cliente | Não | N/A |
| numero | string | Número do local | Não | N/A |
| complemento | string | Complemento ex. Apt xxx Bloco 1 | Não | N/A |
| bairro | string | Bairro | Não | N/A |
| cidade | string | Cidade | Não | N/A |
| estado | string | Estado ex. MG | Não | N/A |
| pontoreferencia | string | Ponto de ref. | Não | N/A |
| responsavel | string | Nome do responsável | Não | N/A |
| anotacoes | longtext | Observações Gerais | Não | N/A |
| datadenascimento | date | Data de Nascimento | Não | N/A |
| cpf | string | CPF pode ser formatado ou não | Não | N/A |
| rg | string | RG | Não | N/A |
| orgaoexpeditor | string | Orgão Expeditor | Não | N/A |
| datadeexpedicao | date | Data de Expedição | Não | N/A |
| pais | string | Ex. +55 | Não | N/A |
| dditelefone | string | DDI Telefone ex. (31) | Não | N/A |
| telefone | string | Telefone para contato | Não | N/A |
| dditelefone2 | string | DDI Telefone ex. (31) | Não | N/A |
| telefone2 | string | Telefone secundário | Não | N/A |
| ddicelular | string | DDI Celular ex. (31) | Não | N/A |
| celular | string | Celular | Não | N/A |
| redesocial | string | Texto com a URL da rede social | Não | N/A |
| profissao | string | Profissão | Não | N/A |
| estadocivil | string | Casado(a), Solteiro(a) | Não | N/A |
| nacionalidade | string | Nacionalidade | Não | N/A |
| razaosocial | string | Razão social para PJ | Não | N/A |
| nomefantasia | string | Nome Fantasia para PJ | Não | N/A |
| cnpjpj | string | CNPJ para PJ | Não | N/A |
| municipal | string | Inscrição Municipal para PJ | Não | N/A |
| estadual | string | Inscrição Estadual para PJ | Não | N/A |
| ceppj | string | CEP para PJ | Não | N/A |
| enderecopj | string | Endereço para PJ | Não | N/A |
| numeropj | string | Número para PJ | Não | N/A |
| complementopj | string | Complemento para PJ ex. Sala xx | Não | N/A |
| bairropj | string | Bairro para PJ | Não | N/A |
| cidadepj | string | Cidade para PJ | Não | N/A |
| estadopj | string | Estado para PJ ex. MG | Não | N/A |
| paispj | string | País para PJ ex. Brasil | Não | N/A |
| pontoreferenciapj | string | Ponto de ref. para PJ | Não | N/A |
Listar
Endpoint: /api/v1/clients
Método: GET
Retorna uma lista de todos os clientes. Suporta busca e paginação para gerenciar grandes volumes de dados.
Ordenação
Para melhorar a experiência de visualização dos dados, oferecemos suporte à ordenação de registros. Você pode especificar a ordenação dos dados através de dois parâmetros:
Parâmetros:
sort: Define a direção da ordenação. Valores permitidos:ascpara ascendente,descpara descendente.field_sort: Especifica o campo pelo qual os registros devem ser ordenados, você pode consultar os campos disponiveis clicando aqui.
Exemplo de Uso: Para ordenar os clientes pelo nome em ordem ascendente: /api/v1/clients?field_sort=nome&sort=asc
Paginação
A paginação é essencial para o gerenciamento eficiente dos dados, especialmente quando lidamos com grandes volumes. Cada página pode conter um número definido de registros, reduzindo o tempo de carregamento e melhorando a usabilidade.
Parâmetro:
page: Número da página desejada.limit(opcional): Número de registros por página, o limite e de até 200 registros.
Exemplo de Uso: Para acessar a segunda página de registros: /api/v1/clients?page=2&limit=10
Buscar
Nossa API permite a realização de buscas detalhadas no cadastro de clientes, facilitando a localização de registros específicos. Você pode especificar o campo de busca e, opcionalmente, o tipo de dado.
Parâmetros:
search: Valor a ser pesquisado.type(opcional): Define o campo específico a ser buscado. Se não especificado, a busca padrão inclui Nome, Razão Social e Nome Fantasia.
Tipos de Busca:
| Código | Descrição |
|---|---|
| 0 | Nome, Razão Social, Nome Fantasia |
| 1 | |
| 2 | Telefone ou Celular |
| 3 | CPF ou CNPJ |
Exemplo de Uso: Para buscar clientes pelo e-mail: /api/v1/clients?search=example@example.com&type=1
Resumo
Utilizar as funcionalidades de Ordenação, Paginação e Buscar em conjunto permite uma manipulação eficiente e precisa dos dados na nossa API. Por exemplo, para listar clientes por um e-mail específico, ordenados pelo ID, e exibir apenas os primeiros 10 resultados, você pode usar a seguinte URL:
/api/v1/clients?search=jonathan@meeventos.com.br&type=1&field_sort=id&sort=desc&page=1&limit=10
Esta combinação otimiza suas consultas, permitindo que você obtenha dados específicos de forma rápida e organizada.
Response:
{
"data": [
{
"id": "1186",
"nome": "API 1",
"email": "jonathan@meeventos.com.br",
"cpf": "01234567890",
"cep": "30720610",
"endereco": "",
"numero": "",
"bairro": "",
"cidade": "",
"estado": "",
"telefone": "31 999999999",
"email2": "",
"telefone2": "31 999999999",
"razaosocial": "",
"celular": "31 999999999",
"responsavel": "",
"datadenascimento": null,
"anotacoes": "",
"datadecadastro": "0000-00-00",
"rg": "",
"dditelefone": null,
"dditelefone2": null,
"ddicelular": null,
"pais": "",
"tipocadastro": "0",
"redesocial": "",
"profissao": "",
"estadocivil": "",
"nacionalidade": "",
"orgaoexpeditor": "",
"datadeexpedicao": null,
"nomefantasia": "",
"cnpjpj": "369852",
"municipal": "",
"estadual": "",
"ceppj": "",
"enderecopj": "",
"numeropj": "",
"bairropj": "",
"cidadepj": "",
"estadopj": "",
"paispj": "",
"pontoreferencia": "",
"pontoreferenciapj": "",
"complemento": "",
"complementopj": ""
}
],
"pagination": {
"page": 1, // Página atual
"page_size": 200, // Quantidade de resgistros exibida por pagina
"total_page": 1, // Quantidade de paginas no total
"total_data": 1 // Quantidade total de registros encontrados
}
}Cadastrar
Endpoint: /api/v1/clients
Método: POST
Permite a criação de um ou mais clientes. Os dados do cliente devem ser fornecidos no corpo da solicitação.
Exemplo de corpo da solicitação para criar um cliente:
Request:
// Observe que o json abaixo e um array, onde pode ser enviado 1 ou varios registros
[
{
"nome": "Jonathan Moreira Brambati",
"email": "jonathan@meeventos.com.br",
"cep": "30720610",
// Outros campos que queiram cadastrar
},
// Outros clientes que queiram inserir
]Response:
{
"status": "success",
"message": "1 Cliente(s) Inserido(s)",
"data": [
{
"id": "1215",
"cliente": "Jonathan Moreira Brambati"
}
]
}Visualizar
Endpoint: /api/v1/clients/{id}
Método: GET
Para visualizar as informações de um cliente, você pode fazer uma solicitação GET para endpoint acima. Não é necessário fornecer informações no corpo da solicitação, já que você estará apenas recuperando dados. O ID do cliente a ser consultado deve ser especificado no endpoint.
Response:
{
"id": "1186",
"nome": "API 1",
"email": "jonathan@meeventos.com.br",
"cpf": "01234567890",
"cep": "30720610",
"endereco": "",
"numero": "",
"bairro": "",
"cidade": "",
"estado": "",
"telefone": "31 999999999",
"email2": "",
"telefone2": "31 999999999",
"razaosocial": "",
"celular": "31 999999999",
"responsavel": "",
"datadenascimento": null,
"anotacoes": "",
"datadecadastro": "0000-00-00",
"rg": "",
"dditelefone": null,
"dditelefone2": null,
"ddicelular": null,
"pais": "",
"tipocadastro": "0",
"redesocial": "",
"profissao": "",
"estadocivil": "",
"nacionalidade": "",
"orgaoexpeditor": "",
"datadeexpedicao": null,
"nomefantasia": "",
"cnpjpj": "369852",
"municipal": "",
"estadual": "",
"ceppj": "",
"enderecopj": "",
"numeropj": "",
"bairropj": "",
"cidadepj": "",
"estadopj": "",
"paispj": "",
"pontoreferencia": "",
"pontoreferenciapj": "",
"complemento": "",
"complementopj": ""
}Editar
Endpoint: /api/v1/clients/{id}
Método: PUT
Permite a atualização de dados de um cliente específico. Os dados para atualização devem ser fornecidos no corpo da solicitação. O ID do cliente a ser editado deve ser especificado no endpoint.
Exemplo de corpo da solicitação para atualizar um cliente:
Request:
{
"nome": "Jonathan Moreira Brambati",
"email": "jonathan@meeventos.com.br",
"cnpjpj": "29206803000189",
// Outros campos que queiram editar
}Response:
{
"status": "success", // success, error
"message": "Registro atualizado com sucesso.",
"data": [
{
"id": "1187",
"nome": "Jonathan Moreira Brambati m",
"email": "jonathan@meeventos.com.br",
"cpf": "",
"cep": "",
"endereco": "",
"numero": "",
"bairro": "",
"cidade": "Belo Horizonte",
"estado": "",
"telefone": "",
"email2": "",
"telefone2": "",
"razaosocial": "",
"celular": "",
"responsavel": "",
"datadenascimento": null,
"anotacoes": "",
"datadecadastro": "0000-00-00",
"rg": "",
"dditelefone": null,
"dditelefone2": null,
"ddicelular": null,
"pais": "",
"tipocadastro": "0",
"redesocial": "",
"profissao": "",
"estadocivil": "",
"nacionalidade": "",
"orgaoexpeditor": "",
"datadeexpedicao": null,
"nomefantasia": "",
"cnpjpj": "",
"municipal": "",
"estadual": "",
"ceppj": "",
"enderecopj": "",
"numeropj": "",
"bairropj": "",
"cidadepj": "",
"estadopj": "",
"paispj": "",
"pontoreferencia": "",
"pontoreferenciapj": "",
"complemento": "",
"complementopj": ""
}
]
}Deletar
Endpoint: /api/v1/clients/{id}
Método: DELETE
Remove um cliente específico da base de dados. O ID do cliente a ser removido deve ser especificado no endpoint.
Response:
{
"status": "success", // success, error
"message": "Cliente excluído com sucesso."
}