Convidados

A API de convidados disponibiliza métodos eficientes para gerenciar participantes de eventos, incorporando recursos avançados de filtragem e pesquisa detalhada. Essas funcionalidades aprimoram a gestão dos dados, apoiando decisões mais informadas sobre a presença e organização dos convidados.

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 informações pessoais, status de presença, e detalhes de contato, 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 convidados até a criação de novos registros. Ao seguir as URLs e métodos HTTP detalhados, você será capaz de realizar operações de forma intuitiva e eficaz.

Veja abaixo:

URLs

Método	URL	Ação	Descrição
GET	/api/v1/guests	Listar	Lista todos os convidados
GET	/api/v1/guests/{id}	Visualizar	Exibe um determinado convidado pelo ID
POST	/api/v1/guests	Criar	Cria um novo convidado

Campos

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

Campo	Tipo	Descrição	Obrigatório
idevento	integer	ID do evento	Sim
iduser	integer	ID do usuário	Sim
nome	string	Nome do convidado	Sim
sobrenome	string	Sobrenome do convidado	Sim
email	string	Email do convidado	Sim
telefone	string	Telefone do convidado	Sim
mesa	string	Mesa designada para o convidado	Não
idgrupo	integer	ID do grupo (tipo de grupo)	Não
texto	text	Observações adicionais	Não
genero	string	Gênero do convidado	Sim
idade	string	Idade do convidado	Sim
presenca	string	Status de presença (PENDENTE, CANCELADO, CONFIRMADO)	Não
token	string	Token único para identificação	Não
envioemail	string	Status de envio de email	Não

Listar

Endpoint: /api/v1/guests

Método: GET

Retorna uma lista de todos os convidados. Suporta busca e paginação para gerenciar grandes volumes de dados.

Filtros Específicos

Além das funcionalidades básicas, oferecemos filtros específicos para convidados:

Parâmetros:

• idevento: Filtra convidados por evento específico
• presenca: Filtra por status de presença (PENDENTE, CANCELADO, CONFIRMADO)

Exemplo de Uso: Para filtrar convidados de um evento específico: /api/v1/guests?idevento=123&presenca=CONFIRMADO

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 convidados pelo nome em ordem ascendente: /api/v1/guests?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 é de até 200 registros.

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

Buscar

Nossa API oferece buscas detalhadas no cadastro de convidados, 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: Nome, Sobrenome, Email

Exemplo de Uso: Para buscar convidados pelos campos acima: /api/v1/guests?search=João

Resumo

Utilizar as funcionalidades de Filtros, Ordenação, Paginação e Buscar em conjunto permite uma manipulação eficiente e precisa dos dados na nossa API. Por exemplo, para listar convidados confirmados de um evento específico, ordenados pelo nome, e exibir apenas os primeiros 10 resultados, você pode usar a seguinte URL:

/api/v1/guests?idevento=123&presenca=CONFIRMADO&search=João&field_sort=nome&sort=asc&page=1&limit=10

Response:

{
  "data": [
    {
      "id": "1",
      "idevento": "123",
      "iduser": "1",
      "nome": "João",
      "sobrenome": "Silva",
      "email": "joao.silva@email.com",
      "telefone": "(11) 99999-9999",
      "mesa": "Mesa 1",
      "idgrupo": "2",
      "texto": "Convidado especial",
      "genero": "Masculino",
      "idade": "30",
      "presenca": "CONFIRMADO",
      "token": "abc123def456789",
      "envioemail": "sim"
    }
  ],
  "pagination": {
    "page": 1,
    "page_size": 200,
    "total_page": 1,
    "total_data": 1
  }
}

Visualizar

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

Método: GET

Para visualizar as informações de um convidado, 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 convidado a ser consultado deve ser especificado no endpoint.

Response:

{
  "id": "1",
  "idevento": "123",
  "iduser": "1",
  "nome": "João",
  "sobrenome": "Silva",
  "email": "joao.silva@email.com",
  "telefone": "(11) 99999-9999",
  "mesa": "Mesa 1",
  "idgrupo": "2",
  "texto": "Convidado especial",
  "genero": "Masculino",
  "idade": "30",
  "presenca": "CONFIRMADO",
  "token": "abc123def456789",
  "envioemail": "sim"
}

Criar

Endpoint: /api/v1/guests

Método: POST

Para criar um novo convidado, 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:

• idevento: ID do evento
• iduser: ID do usuário
• nome: Nome do convidado
• sobrenome: Sobrenome do convidado
• email: Email válido
• telefone: Telefone de contato
• genero: Gênero do convidado
• idade: Idade do convidado

Campos Opcionais:

• mesa: Mesa designada
• tipogrupo: ID do grupo (será salvo como idgrupo)
• texto: Observações adicionais
• presenca: Status de presença (padrão: PENDENTE) CANCELADO, CONFIRMADO

Exemplo de Requisição:

{
  "idevento": 123,
  "iduser": 1,
  "nome": "Maria",
  "sobrenome": "Santos",
  "email": "maria.santos@email.com",
  "telefone": "(11) 88888-8888",
  "mesa": "Mesa 5",
  "tipogrupo": 2,
  "texto": "Vegetariana",
  "genero": "Feminino",
  "idade": "25",
  "presenca": "PENDENTE"
}

Response de Sucesso:

{
  "status": "success",
  "message": "Convidado criado com sucesso.",
  "data": {
    "id": 15,
    "nome": "Maria",
    "sobrenome": "Santos",
    "email": "maria.santos@email.com",
    "telefone": "(11) 88888-8888",
    "mesa": "Mesa 5",
    "idgrupo": 0,
    "texto": "Vegetariana",
    "genero": "Feminino",
    "idade": "25",
    "presenca": "PENDENTE"
  }
}

Observações:

• A API verifica se o evento, usuário e grupo (se informado) existem antes de criar o convidado
• Status de presença aceitos: PENDENTE, CANCELADO, CONFIRMADO