Boas práticas

Busque um programa de fidelidade por vez. Esta é a recomendação com maior impacto na experiência do seu usuário — ver por quê logo abaixo.
Sempre envie o header Accept com application/vnd.economilha.v1+json para garantir compatibilidade futura. Omitir o header aponta sempre para a versão mais recente — o que faz sua integração mudar de comportamento sozinha quando publicarmos uma nova versão.
Prefira responseFormat: "PARSED" em integrações novas. O formato é estável e idêntico para todos os programas, enquanto o payload bruto muda sempre que uma companhia altera a própria API. Ver Formato da resposta.
Trate falhas parciais. Nem todas as companhias estarão disponíveis em toda busca. Verifique o campo success de cada item em results — a requisição retorna 200 OK mesmo quando parte dos programas falha.
Não dependa da ordem dos resultados no array results, nem dos voos dentro de flights.
Monitore sua quota com GET /quota antes de disparar lotes grandes de busca. Ver Quota e limites.
Valide datas antes de enviar — a data de ida deve ser futura e a de volta posterior à ida. Isso evita gastar quota com requisições que voltarão em 422.

O campo id dos voos em PARSED só é válido dentro da resposta em que veio. Ele não é estável entre chamadas e não serve para reserva — use-o apenas para deduplicar ou como chave de lista no seu frontend.

Uma requisição por programa

O campo airlineLoyalty aceita uma lista, e as buscas rodam em paralelo do nosso lado. Mas a resposta é agregada: ela só é devolvida quando todos os programas terminam.

Na prática, o tempo de uma busca com três programas é o tempo do programa mais lento — não a média. Um programa que demora 25 segundos segura os outros dois que responderam em 4.


Uma chamada com 3 programas:
  SMILES  ████                       (4s)
  LATAM   ██████                     (6s)
  AZUL    ███████████████████████    (25s)
  resposta ao cliente ─────────────► 25s (nada antes disso)

Três chamadas, uma por programa:
  SMILES  ████ ──► 4s
  LATAM   ██████ ──► 6s
  AZUL    ███████████████████████ ──► 25s

Disparando uma requisição por programa em paralelo, cada resposta chega assim que aquele programa termina. Seu usuário vê os primeiros voos em 4 segundos em vez de esperar 25 olhando para um spinner.

Alguns pontos que costumam gerar dúvida:

A quota é a mesma. 1 unidade por programa, agrupado ou não. Três chamadas de um programa custam exatamente o mesmo que uma chamada com três programas.
A carga no nosso lado é a mesma. Não há penalidade nem rate limit adicional por dividir as chamadas.
O tratamento de falhas fica mais simples. Cada resposta traz um único results[0], então uma falha isolada não exige varrer o array procurando qual programa quebrou.

Agrupar programas continua sendo válido quando a latência não importa — jobs em background, cargas noturnas, exportações. A recomendação vale para fluxos em que alguém está esperando a resposta na tela.