Guia de integração
Seis regras que evitam a maior parte do que corre mal numa integração: limites atingidos, dados repetidos, e leitores induzidos em erro sobre a actualidade do que estão a ver. Os valores desta página são os que o serviço aplica.
As seis regras
Incêndio · Sintra
Fonte: ANEPC · via api.emcurso.pt · 14:32
Diga de onde vem
Quem lê a sua aplicação tem de conseguir saber de onde vem o dado e quão recente é. Não é uma cortesia: uma ocorrência apresentada sem fonte nem hora lê-se como sendo sua e como sendo de agora.
Não peça mais depressa
Cada família de endpoints tem um intervalo abaixo do qual a resposta não muda. Pedir mais depressa do que isso gasta quota para receber exactamente o mesmo corpo.
A resposta diz-lhe quanto resta
Cada resposta diz quanto resta em cada janela. Uma integração que os lê trava antes de bater no limite; uma que não os lê descobre o limite ao receber 429.
Espere mais de cada vez
Perante 429 ou 5xx, espere e volte a tentar com intervalos crescentes e uma variação aleatória. Sem essa variação, todos os clientes que falharam ao mesmo tempo voltam no mesmo segundo.
Diga quem é
Um User-Agent que nomeie a integração e permita o contacto. É por aí que distinguimos um pico legítimo de um abuso — e por aí que o avisamos antes de limitar a chave.
Nem todo o erro é igual
Um 404 não é um 429 e nenhum dos dois é um 500. Tratar tudo como «falhou» faz a aplicação repetir o que nunca vai resultar e desistir do que resultaria à segunda.
Apresente a fonte e a hora da última actualização junto do dado, não num rodapé nem numa página «sobre». Esta é a forma mínima:
<p class="attribution">
Fonte: ANEPC · via api.emcurso.pt · {{ultimaActualizacao}}
</p>Abaixo destes intervalos a resposta é a mesma. São os valores que o serviço aplica, não uma recomendação.
| Natureza | Intervalo | Endpoints |
|---|---|---|
| Ocorrências ao vivo | 30 s | /prociv/ |
| Constrangimentos de trânsito | 1 min | /traffic/ |
| Ficha de ocorrência do ICNF | 5 min | /icnf/ocorrencia |
| Deteção e contexto | 5 min | /fires/ · /context |
| Avisos meteorológicos | 10 min | /ipma/warnings |
| Previsão e risco | 30 min | /ipma/forecast · /ipma/fire-risk |
| Séries históricas e rotas | 1 h | /icnf/ · /geo/route |
| Dados de referência | 24 h | /prociv/distritos · /geo/municipality-boundary |
Em cada resposta. Quando `Remaining` chega a zero, os pedidos seguintes recebem 429 até ao instante indicado em `Reset`.
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 47
X-RateLimit-Reset: 1735689600
Retry-After: 23O essencial: respeitar `Retry-After` quando existe, crescer o intervalo, e somar uma variação aleatória.
async function call(url, tentativa = 0) {
const res = await fetch(url, { headers });
if (res.ok) return res.json();
if (res.status === 429 || res.status >= 500) {
if (tentativa >= 5) throw new Error(`desisti: ${res.status}`);
// Respeitar o Retry-After quando o servidor o envia.
const after = Number(res.headers.get("Retry-After"));
const espera = Number.isFinite(after)
? after * 1000
: 2 ** tentativa * 1000;
// Variação aleatória: sem ela, todos os clientes que
// falharam ao mesmo tempo voltam no mesmo segundo.
await sleep(espera + Math.random() * 1000);
return call(url, tentativa + 1);
}
throw new Error(`pedido falhou: ${res.status}`);
}Nome da integração, versão, e uma forma de contacto. Mantenha-o estável entre versões.
User-Agent: CamaraDeSintra-Despacho/1.4 (+https://cm-sintra.pt)| Código | Significa | Faça |
|---|---|---|
| 200 | O pedido resultou | Nada. Verifique os cabeçalhos de quota. |
| 400 | Parâmetro inválido | Corrija o pedido. Repetir não resolve. |
| 401 | Chave em falta ou inválida | Verifique o header Authorization. Não repita em ciclo. |
| 403 | Endpoint fora do âmbito da chave | Peça o alargamento na consola. |
| 404 | O recurso não existe | Trate como ausência, não como erro. |
| 429 | Limite da janela atingido | Recue. Respeite Retry-After. |
| 503 | Fonte a montante indisponível | Repita com backoff. Não é da sua chave. |