EmCursoAPI
Chave

Referência técnica

Catálogo de endpoints

Todas as rotas abertas a chamadas externas, com os parâmetros aceites, um pedido pronto a executar e a estrutura exacta da resposta. Todas respondem a GET, salvo indicação em contrário.

37
endpoints
6
famílias
Base
https://api.emcurso.pt
Conta e chave

GET /key

Dados da chave usada no pedido — nome, entidade, endpoints autorizados, User-Agent exigido — e o estado atual das três janelas de limite (minuto, hora, dia), incluindo quando cada uma repõe.

Disponível com qualquer chave, seja qual for o valor de allowedEndpoints: este pedido não é validado contra os endpoints autorizados nem consome quota, precisamente para poder ser usado para verificar quanto resta. Numa janela já reposta, used vem a 0 e resetAt vem null.

Parâmetros

Este endpoint não aceita parâmetros.

GET/keySimulação
curl -H "Authorization: Bearer $EMCURSO_KEY" "https://api.emcurso.pt/key"

Dados da própria chave, devolvidos pelo EmCurso

Autenticação

Autenticação e chaves de acesso

Todos os pedidos externos são autenticados por chave no header Authorization, em formato Bearer. As chaves são nominais, revogáveis a qualquer momento e podem ser restringidas a um subconjunto de endpoints e a um User-Agent declarado.

200 · autenticado

$ curl -sD - -H "Authorization: Bearer $EMCURSO_KEY" \
    "https://api.emcurso.pt/prociv/incendios/ativos"

HTTP/2 200
content-type: application/json; charset=utf-8
cache-control: public, s-maxage=30, stale-while-revalidate=60
x-cache: HIT
x-auth-method: bearer
x-ratelimit-limit: 60
x-ratelimit-remaining: 57
x-ratelimit-reset: 2026-08-01T11:43:00.000Z
x-ratelimit-reset-after: 38
x-ratelimit-window: minute

401 · sem chave

$ curl -sD - "https://api.emcurso.pt/prociv/incendios/ativos"

HTTP/2 401
www-authenticate: Bearer realm="EmCurso API"
content-type: application/json
x-request-id: 8f1c2e40-9b3a-4d61

{
  "success": false,
  "error": "Unauthorized",
  "message": "Missing or invalid API key",
  "requestId": "8f1c2e40-9b3a-4d61",
  "hint": "Para acesso externo, use Authorization: Bearer <API_KEY>"
}

O que cada estado significa

200
Pedido servido
X-Cache diz se veio de cache (HIT), da origem (MISS) ou de uma cópia expirada servida enquanto revalida (STALE).
401
Chave ausente, inválida ou revogada
O campo message diz qual dos três. Confirme o header antes de suspeitar da chave — um caminho inexistente responde 404, nunca 401.
403
User-Agent recusado
A chave exige um User-Agent declarado e o enviado não corresponde. Os identificadores observados estão listados na consola.
429
Limite excedido
Retry-After indica os segundos a aguardar e nunca é zero. O corpo repete o valor em retryAfterSeconds, com resetAt e a janela que disparou.
404
Caminho inexistente
Devolvido a qualquer chamador, com ou sem chave. Quem envia uma chave emitida recebe também os caminhos próximos e a lista completa.

Cada resposta transporta X-Request-ID, repetido no corpo das recusas. É esse o identificador a indicar ao reportar um problema.

Quotas

Limites de utilização

Cada chave tem os seus próprios limites, fixados na apreciação do pedido em função da finalidade e do volume declarado. Os valores abaixo são os que uma integração corrente recebe; uma que precise de mais pede-o na consola, com justificação.

pedidosX-RateLimit-Window
60por minutominuteprotege a origem de rajadas
1 000por horahouracomoda sondagem regular
10 000por diadaytecto diário da chave

As três janelas são verificadas em simultâneo. A que se esgotar primeiro é a que responde 429, e é o seu nome que vem em X-RateLimit-Window.

Em cada resposta
x-ratelimit-limit: 60
x-ratelimit-remaining: 57
x-ratelimit-reset: 2026-08-01T11:43:00.000Z
x-ratelimit-reset-after: 38
x-ratelimit-window: minute
429 · limite excedido
HTTP/2 429
retry-after: 38
x-ratelimit-limit: 60
x-ratelimit-remaining: 0
x-ratelimit-window: minute

{
  "success": false,
  "error": "Too Many Requests",
  "retryAfterSeconds": 38,
  "resetAt": "2026-08-01T11:43:00.000Z",
  "limit": 60,
  "window": "minute",
  "hint": "Limite excedido. Repetir dentro de 38s."
}

Retry-After nunca é zero, pelo que pode ser ligado directamente a um backoff sem inventar um valor de reserva. X-RateLimit-Reset-After diz o mesmo em segundos, e X-RateLimit-Reset o instante em ISO-8601.

O serviço assenta em infraestrutura comunitária gratuita. A disponibilidade é best-effort e não há garantia de latência; utilização intensiva ou sustentada carece de acordo prévio.