Eventos

A API de eventos 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 eventos. 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/events	Listar	Lista todos os eventos
GET	/api/v1/events/`{id}`	Visualizar	Exibe um determinado evento pelo ID
POST	/api/v1/events	Criar	Cria um novo evento
PUT	/api/v1/events/`{id}`	Editar	Atualiza um evento pelo ID
DELETE	/api/v1/events/`{id}`	Cancelar	Cancela um evento pelo ID

Campos

Abaixo estão os campos disponíveis na API:

💡 Nota importante: Quando um evento possui um local cadastrado vinculado (idlocalevento > 0), os campos de endereço (endereco, numero, complemento, cep, bairro, cidade, estado) são preenchidos automaticamente com as informações do local cadastrado em "Meus Locais".

Campo	Tipo	Descrição
tipoEvento	string	Tipo do evento (ex: Casamento, Almoço)
datadecadastro	date	Data de cadastro do evento
idorcamento	integer	ID do orçamento relacionado
idcliente	integer	ID do cliente
nomeCliente	string	Nome do cliente
dataevento	date	Data do evento
horaevento	time	Hora do evento
localevento	string	Nome do local do evento
nomeevento	string	Nome/Título do evento
idlocalevento	integer	ID do local do evento (0 = sem local cadastrado)
endereco	string	Endereço do evento (preenchido automaticamente quando idlocalevento > 0)
numero	string	Número do endereço (preenchido automaticamente quando idlocalevento > 0)
complemento	string	Complemento do endereço (preenchido automaticamente quando idlocalevento > 0)
cep	string	CEP do local (preenchido automaticamente quando idlocalevento > 0)
bairro	string	Bairro do local (preenchido automaticamente quando idlocalevento > 0)
cidade	string	Cidade do evento (preenchida automaticamente quando idlocalevento > 0)
estado	string	Estado do evento (preenchido automaticamente quando idlocalevento > 0)
informacoes	text	Informações adicionais
observacao	text	Observações gerais
codigointerno	string	Código interno do evento
convidados	integer	Número de convidados
datasAdicionais	array	Datas adicionais do evento
status	string	Status do evento

Listar

Endpoint: /api/v1/events

Método: GET

Retorna uma lista de todos os eventos. 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: asc para ascendente, desc para 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 eventos pelo nome em ordem ascendente: /api/v1/events?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 eventos por período: /api/v1/events?start=2024-07-01&end=2024-07-30

Busca por código interno

Permite localizar eventos pelo código interno cadastrado no sistema. A comparação é exata: 0001 não retorna eventos com código 00010.

Parâmetro:

codigointerno: Código interno do evento. Deve ser uma string não vazia.

Exemplo de Uso: Para buscar o evento com código interno PED-2024-001: /api/v1/events?codigointerno=PED-2024-001

O filtro pode ser combinado com os demais parâmetros de busca, período, ordenação e paginação.

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. Deve ser um número inteiro maior que zero.

Os valores de pagination (total_data e total_page) consideram somente os eventos que atendem aos filtros aplicados.

Exemplo de Uso: Para acessar a segunda página de registros: /api/v1/events?page=2&limit=10

Buscar

Nossa API oferece buscas detalhadas no cadastro de eventos, 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 evento, Nome Cliente

Exemplo de Uso: Para buscar eventos pelos campos acima: /api/v1/events?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 eventos por um nome específico, ordenados pelo ID, e exibir apenas os primeiros 10 resultados, você pode usar a seguinte URL:

/api/v1/events?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/events?search=Jonathan&start=2024-07-01&end=2024-07-30&field_sort=id&sort=desc&page=1&limit=10

Response:

json

{
  "data": [
      {
      "id": "1084",
      "caracteristica": null,
      "tipoEvento": "Almoço ",
      "datadecadastro": "2024-03-04",
      "idorcamento": "0",
      "idcliente": "1216",
      "nomeCliente": "Teste cliente nome",
      "dataevento": "2030-08-08",
      "horaevento": "00:00:00",
      "localevento": "Salão de Festas Paradise",
      "nomeevento": "Teste Jonathan",
      "idlocalevento": "159",
      "endereco": "Rua das Palmeiras, 1234",
      "numero": "1234",
      "complemento": "Salão Principal",
      "cep": "30112-000",
      "bairro": "Centro",
      "cidade": "Belo Horizonte",
      "estado": "MG",
      "informacoes": "teste 2323",
      "observacao": "",
      "codigointerno": "",
      "convidados": "100",
      "datasAdicionais": [
        {
          "fim": "2030-08-10 15:00:00",
          "inicio": "2030-08-10 08:00:00"
        },
        {
          "fim": "2030-08-09 15:00:00",
          "inicio": "2030-08-09 08:00:00"
        },
        {
          "fim": "2024-07-07 00:00:00",
          "inicio": "2024-07-07 00:00:00"
        },
        {
          "fim": "2024-07-06 00:00:00",
          "inicio": "2024-07-06 00:00:00"
        },
        {
          "fim": "2024-07-05 00:00:00",
          "inicio": "2024-07-05 00:00:00"
        },
        {
          "fim": "2024-07-04 00:00:00",
          "inicio": "2024-07-04 00:00:00"
        },
        {
          "fim": "2024-07-03 00:00:00",
          "inicio": "2024-07-03 00:00:00"
        },
        {
          "fim": "2024-07-02 00:00:00",
          "inicio": "2024-07-02 00:00:00"
        }
      ],
      "status": "Eventos Anteriores" // Define categoria que o evento se encontra, (controle interno do sistema), tipos possíveis "Próximos Eventos", "Eventos Anteriores", "Cancelado"
    }
  ],
  "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 com os filtros aplicados
  }
}

Visualizar

Endpoint: /api/v1/events/{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:

json

{
  "id": "1",
  "caracteristica": null,
  "tipoEvento": "Casamento",
  "datadecadastro": "2018-11-29",
  "idorcamento": "0",
  "idcliente": "1186",
  "nomeCliente": "Jonathan Moreira Brambati",
  "dataevento": "2019-04-20",
  "horaevento": "11:26:00",
  "localevento": "Mineirão ",
  "nomeevento": "Casamento Giselle e Tiago",
  "idlocalevento": "158",
  "endereco": "Avenida Antônio Abrahão Caram",
  "numero": "1001",
  "complemento": "",
  "cep": "31275-000",
  "bairro": "São José",
  "cidade": "BH",
  "estado": "MG",
  "informacoes": "Teste",
  "observacao": "",
  "codigointerno": "",
  "convidados": "100",
  "datasAdicionais": null,
  "status": "Cancelado"
}

Criar

Endpoint: /api/v1/events

Método: POST

Para criar um novo evento, você deve fazer uma solicitação POST para o endpoint acima. Os dados devem ser enviados no corpo da requisição em formato JSON.

Campos Obrigatórios:

idcliente: ID do cliente
tipoevento: ID do tipo de evento
nomeevento: Nome/título do evento
dataevento: Data do evento (formato: Y-m-d)
idvendedor: ID do vendedor responsável

Campos Opcionais:

horaevento: Hora de início (formato: HH:MM:SS)
horaeventofim: Hora de fim (formato: HH:MM:SS)
localevento: Nome do local
idlocalevento: ID do local cadastrado
idorcamento: ID de um orçamento para ser vinculado ao evento
endereco: Endereço do evento
numero: Número do endereço
complemento: Complemento
bairro: Bairro
cidade: Cidade
estado: Estado
cep: CEP
pais: País
observacao: Observações gerais
obs2, obs3, obs4: Observações adicionais
nconvidados: Número de convidados
comoconheceu: Como conheceu a empresa
codigointerno: Código interno
datasAdicionais: Array de datas adicionais

Exemplo de Requisição:

json

{
  "idcliente": 1216,
  "tipoevento": 2,
  "nomeevento": "Casamento Maria e João",
  "dataevento": "2024-12-25",
  "idvendedor": 1,
  "horaevento": "18:00:00",
  "horaeventofim": "23:00:00",
  "idorcamento": 1,
  "localevento": "Salão de Festas Central",
  "endereco": "Rua das Flores, 123",
  "numero": "123",
  "bairro": "Centro",
  "cidade": "São Paulo",
  "estado": "SP",
  "cep": "01234-567",
  "nconvidados": 150,
  "observacao": "Cerimônia ao ar livre",
  "datasAdicionais": [
    {
      "inicio": "2024-12-24 14:00:00",
      "fim": "2024-12-24 18:00:00",
      "idLocal": 1,
      "idTag": 10,
      "informacoes": "Ensaio da cerimônia"
    },
    {
      "inicio": "2024-12-26 08:00:00",
      "fim": "2024-12-26 12:00:00",
      "informacoes": "Desmontagem"
    }
  ]
}

Response de Sucesso:

json

{
  "status": "success",
  "message": "Evento cadastrado com sucesso.",
  "data": {
    "id": "1085",
    "caracteristica": null,
    "tipoEvento": "Casamento",
    "datadecadastro": "2024-01-15",
    "idorcamento": "0",
    "idcliente": "1216",
    "nomeCliente": "Maria Silva",
    "dataevento": "2024-12-25",
    "horaevento": "18:00:00",
    "localevento": "Salão de Festas Central",
    "nomeevento": "Casamento Maria e João",
    "idlocalevento": "0",
    "endereco": "Rua das Flores, 123",
    "numero": "123",
    "complemento": "",
    "cep": "01234-567",
    "bairro": "Centro",
    "cidade": "São Paulo",
    "estado": "SP",
    "informacoes": "",
    "observacao": "Cerimônia ao ar livre",
    "codigointerno": "",
    "convidados": "150",
    "status": "Próximos Eventos"
  }
}

Observações:

A API verifica se cliente, tipo de evento e vendedor existem antes de criar
Preenchimento automático de endereço: Quando informado idlocalevento (local cadastrado), os campos de endereço (endereco, numero, complemento, bairro, cidade, estado, cep) são preenchidos automaticamente com os dados do local cadastrado. Se informados manualmente junto com idlocalevento, os valores manuais têm prioridade
Local sem cadastro: Para eventos em locais não cadastrados, deixe idlocalevento vazio ou 0 e preencha os campos de endereço manualmente

Editar

Endpoint: /api/v1/events/{id}

Método: PUT

Atualiza parcialmente um evento existente. O parâmetro {id} deve ser o ID numérico do evento e o corpo da solicitação deve conter pelo menos um campo válido. Os campos que não forem enviados permanecem inalterados.

Campos aceitos

Todos os campos são opcionais, mas pelo menos um deve ser informado.

Campo	Tipo	Descrição
nomeevento	string	Nome/título do evento. Não pode ser vazio
idcliente	integer	ID de um cliente existente
tipoevento	integer	ID de um tipo de evento existente
idvendedor	integer	ID de um vendedor existente
dataevento	date	Data do evento (formato: Y-m-d)
horaevento	time	Hora de início (formato: HH:MM:SS)
horaeventofim	time	Hora de fim (formato: HH:MM:SS)
idlocalevento	integer	ID de um local cadastrado. Use `0` para remover o vínculo
localevento	string	Nome do local
endereco	string	Endereço do evento
numero	string	Número do endereço
complemento	string	Complemento
bairro	string	Bairro
cidade	string	Cidade
estado	string	Estado
cep	string	CEP
pais	string	País
observacao	string	Observações gerais
obs2, obs3, obs4	string	Observações adicionais
informacoes	string	Informações adicionais
nconvidados	integer	Número de convidados. Aceita `0`
comoconheceu	integer	ID de um registro de "como conheceu" existente
codigointerno	string	Código interno

As datas adicionais não são alteradas por este endpoint.

Bloqueio de data e local

Quando a empresa usa o bloqueio de agenda por local, alterar dataevento ou idlocalevento passa pela mesma verificação do sistema: se o local já tiver uma pré-reserva ou já tiver atingido o limite de eventos na data, a resposta é 409. Eventos cancelados não contam para esse limite.

Eventos sincronizados com integrações

Quando o evento está sincronizado com o Google Agenda ou com o MeCheckin, a API não altera os dados de agenda: nomeevento, dataevento, horaevento, horaeventofim, idlocalevento, localevento e os campos de endereço. Nesse caso a resposta é 409, porque a sincronização com essas integrações é feita pela tela do sistema. Os demais campos continuam editáveis.

Registro no histórico

Toda edição que altera algum campo é registrada no histórico do evento, com a lista dos campos alterados. Reenviar valores iguais aos já gravados não gera registro.

Exemplo de Requisição:

json

{
  "nomeevento": "Casamento Maria e João",
  "dataevento": "2024-12-28",
  "horaevento": "19:00:00",
  "nconvidados": 180
}

Response de Sucesso:

json

{
  "status": "success",
  "message": "Evento atualizado com sucesso.",
  "data": {
    "id": "1085",
    "caracteristica": null,
    "tipoEvento": "Casamento",
    "datadecadastro": "2024-01-15",
    "idorcamento": "0",
    "idcliente": "1216",
    "nomeCliente": "Maria Silva",
    "dataevento": "2024-12-28",
    "horaevento": "19:00:00",
    "localevento": "Salão de Festas Central",
    "nomeevento": "Casamento Maria e João",
    "idlocalevento": "0",
    "endereco": "Rua das Flores, 123",
    "numero": "123",
    "complemento": "",
    "cep": "01234-567",
    "bairro": "Centro",
    "cidade": "São Paulo",
    "estado": "SP",
    "pais": null,
    "pontoreferencia": null,
    "informacoes": "",
    "observacao": "Cerimônia ao ar livre",
    "codigointerno": "",
    "convidados": "180",
    "datasAdicionais": null,
    "STATUS": "Próximos Eventos"
  }
}

Possíveis erros

Status HTTP	Situação
`400`	ID inválido, corpo sem campos válidos ou algum campo fora do formato aceito
`404`	Evento, cliente, tipo de evento, vendedor, local ou "como conheceu" não encontrado
`409`	Evento cancelado, conflito de data/local com o bloqueio de agenda ou alteração de dados de agenda em evento sincronizado com integrações
`500`	Erro interno ao executar a atualização

Cancelar

Endpoint: /api/v1/events/{id}

Método: DELETE

Cancela um evento, da mesma forma que o cancelamento pela tela do sistema. O evento não é apagado: ele passa a ter o status Cancelado e continua disponível nos GET, com seus pedidos, financeiro e datas adicionais preservados. Assim, o evento pode ser reativado depois pelo sistema.

O corpo da solicitação é opcional e aceita o motivo do cancelamento, que fica registrado no histórico do evento:

Campo	Tipo	Descrição
motivo	string	Motivo do cancelamento. Padrão: `Cancelado pela API`

Cancelar um evento já cancelado retorna sucesso, sem gerar um novo registro no histórico.

Exemplo de Requisição:

json

{
  "motivo": "Cliente desistiu da data"
}

Response de Sucesso:

json

{
  "status": "success",
  "message": "Evento cancelado com sucesso.",
  "data": {
    "id": 1085,
    "status": "Cancelado"
  }
}

Possíveis erros

Status HTTP	Situação
`400`	ID inválido ou `motivo` vazio
`404`	Evento não encontrado
`409`	Evento sincronizado com o Google Agenda ou com o MeCheckin. Nesse caso, cancele pela tela do sistema, para que o cancelamento chegue também às integrações
`500`	Erro interno ao executar o cancelamento

Eventos ​

Introdução ​

URLs ​

Campos ​

Listar ​

Ordenação ​

Busca por período ​

Busca por código interno ​

Paginação ​

Buscar ​

Resumo ​

Visualizar ​

Criar ​

Editar ​

Campos aceitos ​

Bloqueio de data e local ​

Eventos sincronizados com integrações ​

Registro no histórico ​

Possíveis erros ​

Cancelar ​

Possíveis erros ​

Eventos

Introdução

URLs

Campos

Listar

Ordenação

Busca por período

Busca por código interno

Paginação

Buscar

Resumo

Visualizar

Criar

Editar

Campos aceitos

Bloqueio de data e local

Eventos sincronizados com integrações

Registro no histórico

Possíveis erros

Cancelar

Possíveis erros