Orçamentos
A API de orçamentos disponibiliza métodos eficientes para acessar informações, incorporando recursos avançados de filtragem e pesquisa detalhada. Essas funcionalidades aprimoram a gestão dos dados, apoiando decisões mais 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 orçamentos. Ao seguir as URLs e métodos HTTP detalhados, você será capaz de realizar a visualização de forma intuitiva e eficaz.
Veja abaixo:
URLs
| Método | URL | Ação | Descrição |
|---|---|---|---|
| GET | /api/v1/budgets | Listar | Lista todos os orçamentos |
| GET | /api/v1/budgets/{id} | Visualizar | Exibe um determinado orçamento pelo ID |
| POST | /api/v1/budgets/ | Cadastrar | Cria um orçamento na base de dados |
| PUT | /api/v1/budgets/{id}/followups | Cadastrar | Cria um follow-up para um orçamento específico |
Campos
Os dados dos orçamentos 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. |
|---|---|---|---|---|
| nome | string | Nome cliente | Sim | N/A |
| string | Email do cliente | Não | N/A | |
| comoconheceu | int | Id do registro no sistema | Não | N/A |
| tipoevento | int | Id do registro no sistema | Não | N/A |
| dataevento | date | Data do evento | Não | N/A |
| mensagem | string | Campo livre de texto | Não | N/A |
| idvendedor | int | Id do usuário do sistema | Não | N/A |
| observacao | string | Campo livre de texto | Não | N/A |
| codigointerno | string | Campo livre de texto | Não | N/A |
| numeroconvidados | int | Número de convidados do evento | Não | N/A |
| valorinicial | decimal | Valore negociável | Não | N/A |
| string | Cliente possui whatsapp sim/nao | Não | nao | |
| dditelefone | string | DDDI informar o + | Não | N/A |
| telefone | string | Telefone com ou sem mascara | Não | N/A |
| ddicelular | string | DDDI informar o + | Não | N/A |
| celular | string | Celular com ou sem mascara | Não | N/A |
| idlocalevento | int | Id do registro no sistema | Não | N/A |
| nomeresponsavel | string | Campo livre de texto | Não | N/A |
| obs2 | string | Campo livre de texto | Não | N/A |
| obs3 | string | Campo livre de texto | Não | N/A |
| obs4 | string | Campo livre de texto | Não | N/A |
| nomedoevento | string | Campo livre de texto | Não | N/A |
Nota: Para obter os IDs necessários para os campos comoconheceu, tipoevento, idvendedor, e idlocalevento, consulte a página de Rotas Adicionais.
Listar
Endpoint: /api/v1/budgets
Método: GET
Retorna uma lista de todos os orçamentos. 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 disponíveis clicando aqui.
Exemplo de Uso: Para ordenar os orçamentos pelo nome em ordem ascendente: /api/v1/budgets?field_sort=nomeevento&sort=asc
Busca por período
A busca por período entre datas é fundamental para a gestão eficiente de dados, especialmente quando trabalhamos com grandes volumes. Ao definir um intervalo de datas, podemos limitar o número de registros retornados, reduzindo o tempo de processamento e aprimorando a usabilidade do sistema.
Parâmetros:
start: Especifica o campo que define a data de início para o filtro, deve ser enviada no formato Y-m-d.end: Especifica o campo que define a data de fim para o filtro, deve ser enviada no formato Y-m-d
Exemplo de Uso: Para filtrar os orçamentos por período: /api/v1/budgets?start=2024-07-01&end=2024-07-30
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/budgets?page=2&limit=10
Buscar
Nossa API oferece buscas detalhadas no cadastro de orçamentos, permitindo a fácil localização de registros específicos. A busca é realizada nos campos listados na tabela abaixo, otimizando o processo de consulta sem necessidade de especificar os campos manualmente.
Parâmetro:
search: Valor a ser pesquisado.
Tipos de Busca:
Campos Pesquisados: Informações, Observação, Nome do orçamento, Nome Cliente
Exemplo de Uso: Para buscar orçamentos pelos campos acima: /api/v1/budgets?search=Nome Cliente
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 orçamentos por um nome específico, ordenados pelo ID, e exibir apenas os primeiros 10 resultados, você pode usar a seguinte URL:
/api/v1/budgets?search=Jonathan&field_sort=id&sort=desc&page=1&limit=10
Para realizar uma busca por período, adicione os parâmetros start e date.
/api/v1/budgets?search=Jonathan&start=2024-07-01&end=2024-07-30&field_sort=id&sort=desc&page=1&limit=10
Response:
{
"data": [
{
"id": "1619",
"email": "jonathan@meeventos.com.br",
"emailcopia": "",
"nome": "jonathan",
"dditelefone": "+55",
"telefone": "31 99999-9999",
"ddicelular": "+55",
"celular": "31 99999-9999",
"comoconheceu": "Já era Cliente",
"idtipoevento": "45",
"tipoevento": "Coffee Break",
"dataevento": "2024-09-03",
"assunto": "Orçamento do Coffee break",
"mensagem": "Descrição Jonathan Brambati",
"vendedor": "Jonathan Brambati",
"dataretorno": "2024-08-22",
"status": "Em aberto",
"numeroconvidados": "30",
"idlocal": "159",
"localevento": "Me Space",
"funil": "Visita realizada",
"idevento": "",
"nomedoevento": "Cafe do Thalles",
"nomeresponsavel": "Thalles",
"datasAdicionais": [
{
"fim": "2025-03-22 00:00:00",
"tag": null,
"inicio": "2025-03-22 00:00:00",
"idLocal": 158,
"nomeLocal": "teste jon 11111"
}
],
"observacoes": [
{
"obs1": "Observação",
"valor": "Observação"
},
{
"obs2": "Observações 2",
"valor": "Observações"
},
{
"obs3": "Observações 3",
"valor": "Observações"
},
{
"obs4": "Observações 4",
"valor": "Observações"
}
],
"empresa": [{
"rg": "",
"cep": "30720610",
"cpf": "",
"ceppj": "",
"bairro": "Padre Eustáquio",
"cidade": "Belo Horizonte",
"cnpjpj": "",
"estado": "MG",
"numero": "123",
"bairropj": "",
"cidadepj": "",
"endereco": "Nome da Rua",
"estadopj": "",
"numeropj": "",
"enderecopj": "",
"complemento": "teste",
"complementopj": ""
}],
},
{
"id": "1620",
"email": "thalles@meeventos.com.br",
"emailcopia": "",
"nome": "Thalles",
"dditelefone": "",
"telefone": "",
"ddicelular": "",
"celular": "",
"comoconheceu": "Não Informado",
"idtipoevento": "35",
"tipoevento": "Almoço",
"dataevento": "2024-08-21",
"assunto": "Orçamento do Coffee break",
"mensagem": "Teste Jonathan Brambati",
"vendedor": "Jonathan Brambati",
"dataretorno": "2024-08-20",
"status": "Finalizados",
"numeroconvidados": "0",
"idlocal": "159",
"localevento": "Me Space",
"funil": null,
"idevento": "",
"nomedoevento": "",
"nomeresponsavel": "",
"datasAdicionais": null,
"observacoes": null,
"empresa": [{
"rg": null,
"cep": null,
"cpf": null,
"ceppj": null,
"bairro": null,
"cidade": null,
"cnpjpj": null,
"estado": null,
"numero": null,
"bairropj": null,
"cidadepj": null,
"endereco": null,
"estadopj": null,
"numeropj": null,
"enderecopj": null,
"complemento": null,
"complementopj": null
}]
}
],
"pagination": {
"page": 1, // Página atual
"page_size": 200, // Quantidade de registros exibida por pagina
"total_page": 1, // Quantidade de paginas no total
"total_data": 1 // Quantidade total de registros encontrados
}
}Cadastrar
Endpoint: /api/v1/budgets
Método: POST
Permite a criação de um orçamento. Os dados do orçamento devem ser fornecidos no corpo da solicitação.
Exemplo de corpo da solicitação para criar um orçamento:
Request:
{
"nome": "Jonathan Moreira",
"email": "",
"comoconheceu": "",
"tipoevento": "",
"dataevento": "",
"mensagem": "",
"idvendedor": "",
"observacao": "",
"codigointerno": "",
"numeroconvidados": "",
"valorinicial": "",
"whatsapp": "",
"dditelefone": "",
"telefone": "",
"ddicelular": "",
"celular": "",
"idlocalevento": "",
"nomeresponsavel": "",
"obs2": "",
"obs3": "",
"obs4": "",
"nomedoevento": "",
}Response:
{
"status": "success",
"message": "Orçamento Inserido",
"id": "2201",
"email": "",
"nome": "Jonathan Moreira",
"comoconheceu": 6,
"tipoevento": "1",
"dataevento": "0000-00-00",
"mensagem": "",
"idvendedor": "119",
"observacao": "",
"codigointerno": "",
"numeroconvidados": "",
"valorinicial": "",
"whatsapp": "",
"dditelefone": "",
"telefone": "",
"ddicelular": "",
"celular": "",
"idlocalevento": "",
"nomeresponsavel": "",
"obs2": "",
"obs3": "",
"obs4": "",
"nomedoevento": ""
}Visualizar
Endpoint: /api/v1/budgets/{id}
Método: GET
Para visualizar as informações de um evento, 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": "1620",
"email": "jonathan@meeventos.com.br",
"emailcopia": "",
"nome": "Jonathan",
"dditelefone": "",
"telefone": "",
"ddicelular": "",
"celular": "",
"comoconheceu": "Não Informado",
"idtipoevento": "35",
"tipoevento": "Almoço",
"dataevento": "2024-08-21",
"assunto": "Orçamento do Coffee break",
"mensagem": "Teste Jonathan Brambati",
"vendedor": "Jonathan Brambati",
"dataretorno": "2024-08-20",
"status": "Finalizados",
"numeroconvidados": "0",
"idlocal": "159",
"localevento": "Me Space",
"funil": null,
"idevento": "",
"nomedoevento": "",
"nomeresponsavel": "",
"datasAdicionais": [
{
"fim": "2025-03-22 00:00:00",
"tag": null,
"inicio": "2025-03-22 00:00:00",
"idLocal": 158,
"nomeLocal": "teste jon 11111"
}
],
"observacoes": [
{
"obs1": "Observação",
"valor": "Observação"
},
{
"obs2": "Observações 2",
"valor": "Observações"
},
{
"obs3": "Observações 3",
"valor": "Observações"
},
{
"obs4": "Observações 4",
"valor": "Observações"
}
],
"empresa": [{
"rg": "",
"cep": "30720610",
"cpf": "",
"ceppj": "",
"bairro": "Padre Eustáquio",
"cidade": "Belo Horizonte",
"cnpjpj": "",
"estado": "MG",
"numero": "123",
"bairropj": "",
"cidadepj": "",
"endereco": "Nome da Rua",
"estadopj": "",
"numeropj": "",
"enderecopj": "",
"complemento": "teste",
"complementopj": ""
}],
}Cadastrar Follow-up
Endpoint: /api/v1/budgets/{id}/followups
Método: PUT
Permite o cadastro de um follow-up para um orçamento específico. Os dados do follow-up devem ser fornecidos no corpo da solicitação.
Campos
| Campo | Tipo | Descrição | Obrigatório | Val. ex. |
|---|---|---|---|---|
| dataRetorno | date | Data do próximo retorno | Sim | 2024-10-16 |
| horaRetorno | time | Hora do próximo retorno | Não | 14:30 |
| atencaoLead | int | Nível de atenção do lead (1-5) | Não | 3 |
| idvendedor | int | Id do usuário do sistema | Não | 27 |
| anotacoes | longtext | Anotações do atendimento | Não | N/A |
Explicação dos Níveis de Atenção do Lead (atencaoLead)
O campo atencaoLead representa o nível de prioridade ou urgência associado ao lead. Aqui está o significado de cada nível:
- Muito Baixo: Lead com pouco potencial ou interesse mínimo.
- Baixo: Lead com algum potencial, mas não prioritário.
- Médio: Lead com potencial moderado, merece atenção regular.
- Alto: Lead promissor, requer atenção prioritária.
- Muito Alto: Lead de alta prioridade, necessita de ação imediata.
Essa classificação ajuda a equipe de vendas a priorizar seus esforços e recursos, focando nos leads mais promissores ou que necessitam de atenção urgente.
Nota: Para obter os IDs necessários para o campo idvendedor, consulte a página de Rotas Adicionais.
Exemplo de corpo da solicitação para cadastrar um follow-up:
Request:
{
"dataRetorno": "2024-10-16",
"horaRetorno": "14:30",
"idvendedor": 27,
"atencaoLead": 3,
"anotacoes": "Cliente interessado em pacotes para eventos corporativos. Solicitar mais informações sobre o número de participantes e preferências de cardápio. Agendar uma visita ao local do evento na próxima semana."
}Response:
{
"status": "success",
"message": "Follow-up cadastrado com sucesso",
"id": "123",
}Note que o id no endpoint se refere ao ID do orçamento ao qual o follow-up está sendo adicionado.