Ambientes, limites e controlo de versões

Sandbox e produção, um único URL base

URL base: https://api.dubaitrip.com/v1. O sandbox e a produção partilham-no; a chave com que assina seleciona o ambiente. Uma chave dt_sbx_ funciona com os ambientes de teste dos nossos fornecedores — pesquisas, tarifação, verificações de tarifa, encomendas, reservas, emissão e cancelamentos funcionam todos de ponta a ponta com inventário de teste, sem bilhete ou voucher reais e sem qualquer cobrança. Uma chave dt_live_, emitida após a análise para produção, acede ao inventário real e é liquidada contra o seu depósito.

As reservas de sandbox e de produção são mantidas separadas no seu portal do programador (cada reserva está assinalada), e os âmbitos, limites e regras de IP são geridos por ambiente.

Limites de pedidos e quotas

Cada chave é limitada por um balde de tokens (pedidos sustentados por segundo mais um pico) e por uma quota diária. Predefinições do sandbox: 2 pedidos/segundo, pico de 5, 2000 pedidos/dia. Os limites de produção são acordados por conta. Exceder o balde devolve 429 api_rate_limited com um cabeçalho Retry-After; esgotar a quota devolve 429 api_quota_exceeded até à meia-noite UTC.

As pesquisas pesadas são assíncronas por conceção: passe wait=false para obter de imediato um searchId e consultar periodicamente o endpoint de pesquisa, ou wait=true para receber o resultado completo numa única chamada. As consultas periódicas contam para os seus limites como qualquer outro pedido.

Controlo look-to-book

As pesquisas também são racionadas em função das reservas que faz. Cada dia de uma janela móvel (7 dias por predefinição) concede uma quota gratuita de pesquisas, e cada reserva feita nessa janela acrescenta mais cap pesquisas — cap é o número de pesquisas por reserva acordado para a sua conta e mostrado no portal do programador. As consultas periódicas, a tarifação, as regras tarifárias e as leituras de conteúdo nunca contam; só contam as chamadas de pesquisa de voos e de hotéis.

Quando a quota se esgota, as pesquisas respondem 429 look_to_book_exceeded com um cabeçalho Retry-After que aponta para a meia-noite UTC seguinte, quando o dia mais antigo sai da janela. Uma reserva reabre a quota de imediato. O cartão Look-to-book do portal do programador mostra os contadores em tempo real, o limite e o que resta; se a sua integração pesquisa legitimamente muito mais do que reserva, peça-nos para aumentar o limite em vez de repetir os pedidos apesar da recusa.

Idempotência

Os endpoints que comprometem dinheiro ou inventário — criar uma encomenda ou reserva, emitir, cancelar — exigem um cabeçalho Idempotency-Key (qualquer cadeia única até 128 caracteres; um UUID é ideal). Repetir com a mesma chave devolve a resposta original em vez de criar um duplicado; um corpo diferente com uma chave reutilizada devolve 409.

Controlo de versões

A versão está no caminho (/v1). As alterações aditivas — novos campos opcionais, novos valores de enum, novos endpoints — são publicadas sem mudança de versão, por isso faça o parsing de forma defensiva e ignore campos desconhecidos. As alterações incompatíveis recebem uma nova versão principal com um período de migração; o guia Registo de alterações lista todas as alterações.