Filtros

Filtros permitem pedir só uma parte dos dados. Eles são passados na URL, como parâmetros de consulta (o que vem depois do ?), e todos são opcionais.

Os filtros disponíveis dependem do recurso. Hoje, somente a lista de viagens aceita filtros:

Endpoint	Filtros
Listar viagens	search e filtros por data de início e de fim
Listar depoimentos	nenhum (só paginação)
Viagem, empresa e SEO	nenhum (retornam um único objeto)

Esta página explica os conceitos. Os detalhes de cada parâmetro estão na referência da API.

Buscar por texto: search

search procura o texto no título, no endereço (slug) e na descrição curta da viagem.

curl "https://minhaagencia.avoei.com.br/api/v1/travels?search=paraty" \
  -H "Authorization: Bearer SEU_TOKEN"

• A busca não diferencia maiúsculas de minúsculas nem acentos: praia encontra Praia e paraíso encontra Paraiso.
• Ela procura o texto em qualquer parte do campo: rota encontra "Rota do Ouro".
• Caracteres como % e _ são tratados como texto comum, não como curingas.
• O texto pode ter até 100 caracteres. Um search vazio é ignorado.

Filtrar por período

Uma viagem tem uma data de início e uma data de fim. Há filtros para as duas, sempre com o formato AAAA-MM-DD e com limites inclusivos:

Parâmetro	Traz as viagens que…
start_date_from	começam nesta data ou depois
start_date_until	começam até esta data (inclusive)
end_date_from	terminam nesta data ou depois
end_date_until	terminam até esta data (inclusive)

Você pode enviar só um limite de cada campo, ou os dois. Por exemplo, as viagens que começam em dezembro de 2026:

curl "https://minhaagencia.avoei.com.br/api/v1/travels?start_date_from=2026-12-01&start_date_until=2026-12-31" \
  -H "Authorization: Bearer SEU_TOKEN"

As datas são datas de calendário, sem horário nem fuso: 2026-12-31 inclui as viagens que começam em qualquer momento do dia 31. Veja Datas e horários.

O padrão: só viagens futuras

Se você não enviar start_date_from, a lista traz apenas viagens que ainda não começaram (que começam hoje ou depois; "hoje" é o dia no horário de Brasília). Para incluir viagens passadas, envie uma data de início anterior:

curl "https://minhaagencia.avoei.com.br/api/v1/travels?start_date_from=2020-01-01" \
  -H "Authorization: Bearer SEU_TOKEN"

Nomes antigos: start_date e end_date

Antes dos parâmetros acima existirem, a lista já aceitava start_date e end_date. Eles continuam funcionando:

• start_date é o mesmo que start_date_from;
• end_date é o mesmo que end_date_until.

Em integrações novas, use os nomes com _from e _until, que deixam claro se o limite é inicial ou final. Se você enviar os dois nomes, vale o novo.

Combinar filtros

Todos os filtros se combinam: a viagem precisa atender a todos ao mesmo tempo. Você também pode usar filtros junto com ordenação e paginação:

curl "https://minhaagencia.avoei.com.br/api/v1/travels?search=paraty&start_date_from=2026-11-01&sort=-price&per_page=20" \
  -H "Authorization: Bearer SEU_TOKEN"

Essa consulta traz as viagens que citam "paraty" e começam a partir de 1º de novembro de 2026, das mais caras para as mais baratas, em páginas de 20.

Quando um filtro é inválido

A API não ignora um filtro inválido: ela responde 422 e não devolve viagem alguma. Isso evita que um erro de digitação faça o seu sistema mostrar dados errados sem perceber.

Os casos mais comuns:

• uma data fora do formato AAAA-MM-DD (como 13/11/2026) ou que não existe (como 2026-02-31);
• um limite final anterior ao inicial (por exemplo, start_date_until antes de start_date_from);
• um search com mais de 100 caracteres.

Exemplo de resposta:

{
  "success": false,
  "message": "The given data was invalid.",
  "data": [],
  "errors": {
    "start_date_from": ["O campo start date from não corresponde ao formato Y-m-d."]
  },
  "status": 422
}

Veja mais em Erros.