Ordenação - Even3

Visão geral

Ordenação de resultados da API Even3

Use o parâmetro order_by para definir por qual campo e em qual direção os registros são retornados nas listagens.

Como funciona a ordenação da API

Os endpoints de listagem da API v2 aceitam o parâmetro order_by para definir a ordem dos registros retornados. A ordenação é aplicada antes da paginação, ou seja, ela determina quais registros aparecem em cada página.

Importante: a ordenação é sempre feita por um único campo, e apenas campos permitidos para o endpoint são aceitos. Quando order_by não é informado, cada recurso aplica a sua ordenação padrão.

O parâmetro pode ser combinado livremente com filter, fields, page e page_size na mesma requisição.

O que você pode fazer com a ordenação

Com um único parâmetro você controla a apresentação dos dados e garante consistência entre as páginas da sua integração.

Escolher o campo: informe um campo permitido pelo endpoint, como name ou registration_date.
Definir a direção: use asc para ordem crescente ou desc para decrescente.
Combinar com filtros: aplique order_by junto com filter para refinar e organizar a consulta.
Paginar com segurança: mantenha a mesma ordenação em todas as páginas da varredura.

O parâmetro order_by

O valor é composto pelo nome do campo e pela direção, separados por ponto: campo.direcao.

Formato

order_by=campo.asc  |  order_by=campo.desc

Componentes

Campo	Descrição
campo	Deve ser um dos campos permitidos para o endpoint consultado. Campos não reconhecidos retornam 400.
direção	Aceita asc (crescente) ou desc (decrescente). É obrigatório informar a direção.
Limite	Apenas um campo por requisição. Não é possível encadear múltiplos campos de ordenação.

VÁLIDOUm campo e uma direção — aceito em todos os endpoints de listagem

order_by=name.asc
order_by=registration_date.desc
order_by=id.asc

INVÁLIDOFormatos não aceitos — retornam erro 400

order_by=name
order_by=-name
order_by=name.asc,email.desc

Exemplo: GET /api/v2/attendees?order_by=name.asc&page=1&page_size=50

Cabeçalho de resposta: X-Api-OrderBy-Syntax

As listagens retornam este cabeçalho informando a sintaxe suportada pela rota, útil para validar a integração durante o desenvolvimento.

X-Api-OrderBy-Syntax: field.asc|field.desc (single field)

Ordenação junto com filtros e paginação

O order_by funciona com os dois padrões de filtro suportados pela API, RQL e LHS Brackets, sem alterar a estrutura da resposta.

RQL — filtrar e ordenar

Inscritos confirmados a partir de uma data, do mais recente para o mais antigo.

GET https://api.even3.com/api/v2/attendees?filter=registration_date&gt;=2026-01-01&amp;order_by=registration_date.desc

LHS Brackets — mesmo resultado

A ordenação é declarada da mesma forma, independentemente do padrão de filtro.

GET https://api.even3.com/api/v2/attendees?filter[registration_date][gte]=2026-01-01&order_by=registration_date.desc

Retorno ordenado

A estrutura da resposta permanece a mesma. O order_by altera apenas a sequência dos itens em data e, consequentemente, a distribuição entre as páginas.

200 OKResposta de sucesso

{
"data": [
{
"id": 999999,
"event_id": 999999,
"name": "Teste Even3",
"email": "teste@even3.com",
"is_confirmed": true,
"registration_category": "Entrada teste",
"registration_date": "22/07/2026",
"registration_hour": "13:10"
},
{
"id": 999998,
"event_id": 999999,
"name": "Teste Even3 2",
"email": "teste2@even3.com",
"is_confirmed": true,
"registration_category": "Entrada teste",
"registration_date": "15/03/2026",
"registration_hour": "09:42"
}
],
"count": 2,
"pagination": {
"current_page": 1,
"total_page": 1,
"page_size": 30,
"quantity": 2,
"has_previous": false,
"has_next": false
}
}

Campos aceitos por endpoint

Cada recurso possui a sua própria lista de campos ordenáveis e a sua ordenação padrão, aplicada quando order_by não é informado.

Recurso	Endpoint	Ordenação padrão	Campos ordenáveis
Inscritos	/api/v2/attendees	id.asc	id, event_id, check_in_code, name, badge_name, email, gender, photo, document_number, is_confirmed, registration_category, registration_date, registration_hour
Eventos	/api/v2/events	id.asc	id, title, url, start_date, start_time, end_date, end_time, registration_start_date, registration_end_date, created_date, updated_date, summary, description, image, image_url, banner, credit_hours, country, state, city, venue, latitude, longitude, online, published
Pagamentos	/api/v2/payments	id.asc	id, event_id, payment_reference, attendee_name, attendee_email, attendee_document_number, attendee_phone, description, item, amount
Submissões	/api/v2/submission/list /api/v2/submission/proceedings	id.asc	id, event_id, title, status
Atividades	/api/v2/schedule/session	id.asc	id, event_id, title, schedule_title, venue, description, tags
Palestrantes	/api/v2/schedule/speaker	id.asc	id, event_id, name, photo_url, job_title, bio, email
Certificados	/api/v2/certificates	attendee_id.asc	id, attendee_id, event_id, name, email, document_number, certificate_url
Website	/api/v2/website	display_order.asc	id, event_id, section_id, title, subtitle, description, template, display_order, is_visible, additional_information, is_default_layout, is_standalone_layout

Eventos: campos relacionados a ingressos, como tickets.title, tickets.prices.price e demais campos de lote, podem ser utilizados em filter, mas não são aceitos em order_by.

Observação: o valor de order_by não diferencia maiúsculas de minúsculas, então order_by=Name.DESC e order_by=name.desc produzem o mesmo resultado.

Respostas de erro na ordenação

Qualquer inconsistência no order_by interrompe a requisição e retorna 400 Bad Request com o código InvalidParameter.

Situação	Exemplo	Detalhe retornado
Formato incorreto	order_by=name	Error in order_by parameter. Expected format: field.asc or field.desc
Mais de um campo	order_by=name.asc,email.desc	Error in order_by parameter. Only one sort field is allowed.
Campo não permitido	order_by=nome.asc	Invalid field: nome
Campo de ingresso em eventos	order_by=tickets.prices.price.asc	Error in order_by parameter. Ticket fields are not supported for ordering.
Parâmetro desconhecido	orderby=name.asc	Invalid parameter: orderby

Estrutura do erro

O campo detail indica exatamente o que precisa ser corrigido na requisição.

400 Bad RequestResposta de erro

{
"success": false,
"message": "Invalid request",
"detail": "Error in order_by parameter. Expected format: field.asc or field.desc",
"help": "Review query parameters (filter, order_by, page, page_size) and request values.",
"code": "InvalidParameter"
}

Boas práticas ao ordenar

Ao percorrer todas as páginas de uma listagem, prefira ordenar por um campo de valor único, como id. Campos que podem se repetir, como name ou status, não garantem uma sequência estável entre páginas e podem fazer com que um mesmo registro apareça duas vezes ou seja omitido durante a varredura.

Mantenha exatamente os mesmos valores de order_by e filter em todas as requisições de uma mesma paginação. Alterar a ordenação no meio da varredura reorganiza o conjunto de resultados e invalida o controle de páginas já lidas.

Sempre que a ordenação padrão do recurso já atender à necessidade, omita o parâmetro. Isso simplifica a integração e evita erros de campo inválido.