Boas práticas

1. Uma requisição, um programa. É o que garante o menor tempo de resposta para o seu usuário — ver Comparando vários programas.

2. 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.

3. 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.

4. Trate falhas por programa. Nem toda companhia estará disponível em toda busca. Verifique o campo success do item em results — a requisição retorna 200 OK mesmo quando a busca no programa falha.

5. Não dependa da ordem dos voos dentro de flights.

6. Monitore sua quota com GET /quota antes de disparar lotes grandes de busca. Ver Quota e limites.

7. 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.

Comparando vários programas

Cada busca vai até a API da companhia em tempo real, e os programas respondem em tempos diferentes: alguns em 7 segundos, outros passam dos 20. Isso é da natureza dos provedores.

Para comparar programas, dispare uma requisição por programa, em paralelo, e renderize cada resposta assim que ela chegar:

SMILES  ████                       ──► 4s   já aparece na tela
LATAM   ██████                     ──► 6s   já aparece na tela
AZUL    ███████████████████████    ──► 25s  entra depois

O erro comum é esperar todas as promises terminarem (Promise.all) para só então montar a tela: nesse caso o usuário fica 25 segundos olhando para um spinner por causa de um único programa lento, mesmo com os outros dois já respondidos. Prefira resolver cada requisição individualmente (Promise.allSettled, ou um handler por chamada) e ir preenchendo a lista de forma incremental.

Alguns pontos que costumam gerar dúvida:

• A quota é por programa consultado. Consultar três programas custa três buscas — nada muda em função de como você organiza as chamadas. Ver Quota e limites.
• Não há penalidade nem rate limit adicional por disparar as chamadas em paralelo.
• O tratamento de falhas fica isolado. Cada resposta traz um único results[0], então um programa fora do ar afeta só o card daquele programa na sua tela.