API para programadores

Esta página descreve os endpoints públicos que pode usar para integrar com o Imbecis. Não é necessária autenticação para o endpoint documentado abaixo.

URL base da API neste ambiente: https://api.imbecis.app

GET /reports/confirmed

Devolve uma lista paginada de denúncias públicas confirmadas, ordenadas pela ocorrência mais recente primeiro.

Pedido

GET /reports/confirmed

Parâmetros de query

Parâmetro	Tipo	Obrig.	Predefinição	Restrições	Descrição
page	integer	Não	1	≥ 1	Número da página.
pageSize	integer	Não	10	5 – 50	Resultados por página.
from_time	string	Não	—	ISO 8601	Limite inferior no tempo da ocorrência (`occurredAt`, com recurso a `createdAt` em relatórios antigos).
to_time	string	Não	—	ISO 8601, ≥ from_time	Limite superior (mesma lógica de fallback que `from_time`).
municipality	string	Não	—	Município português válido	Filtra pelo campo `municipality` do relatório (geocodificação).

Exemplos de URL completas

Primeira página (predefinições):

GET https://api.imbecis.app/reports/confirmed

Página 2, 25 resultados, Braga:

GET https://api.imbecis.app/reports/confirmed?page=2&pageSize=25&municipality=Braga

Janela temporal:

GET https://api.imbecis.app/reports/confirmed?from_time=2026-04-01T00:00:00.000Z&to_time=2026-04-30T23:59:59.999Z

Resposta: 200 OK

{
  "success": true,
  "message": "Confirmed reports",
  "meta": {
    "page": 1,
    "pageSize": 10,
    "total": 84,
    "totalPages": 9
  },
  "payload": [
    {
      "id": "69f3a084f3a164e5562c4d20",
      "occurredAt": "2026-04-30T14:22:00.000Z",
      "createdAt": "2026-04-30T14:23:11.000Z",
      "picture": "https://cdn.imbecis.app/reports/69f3a084f3a164e5562c4d20.jpg",
      "plateNumber": "AA-00-BB",
      "plateCountry": "pt",
      "location": {
        "latitude": 41.54321,
        "longitude": -8.42109,
        "municipality": "Braga",
        "freguesia": "Maximinos",
        "street": "Rua de Santa Margarida",
        "doorNumber": 12,
        "postal_code": "4710-306"
      }
    }
  ]
}

Campos do corpo (nível superior)

Campo	Tipo	Descrição
success	boolean	Sempre `true` em sucesso.
message	string	Mensagem legível.
meta	object	Metadados de paginação.
payload	array	Lista de denúncias confirmadas.

Campo	Tipo	Descrição
page	integer	Página atual.
pageSize	integer	Itens por página nesta resposta.
total	integer	Total de registos que correspondem ao filtro.
totalPages	integer	Total de páginas; `0` se `total` for `0`.

Itens em payload[]

Campo	Tipo	Descrição
id	string	ObjectId MongoDB em hexadecimal.
occurredAt	string	ISO 8601 — quando a infração foi observada; em relatórios antigos pode coincidir com `createdAt`.
createdAt	string	ISO 8601 — quando a denúncia foi submetida.
picture	string \| null	URL pública da imagem (matrícula desfocada); `null` se não houver.
plateNumber	string \| null	Matrícula; `null` se não confirmada.
plateCountry	string \| null	Código ISO do país da matrícula (ex.: `pt`).
location	object	Localização (ver tabela seguinte).

location

Campo	Tipo	Descrição
latitude	number	Arredondada a 5 casas decimais.
longitude	number	Arredondada a 5 casas decimais.
municipality	string \| undefined	Município (geocodificação).
freguesia	string \| undefined	Freguesia.
street	string \| undefined	Nome da rua.
doorNumber	integer \| undefined	Número de porta.
postal_code	string \| undefined	Código postal (ex.: `4710-306`).

Erros: 400 Bad Request

Devolvido quando os parâmetros de query falham a validação.

{
  "success": false,
  "errors": [
    "pageSize must not be less than 5",
    "municipality is not a valid municipality"
  ]
}

Condição	Mensagem (exemplo)
`page` < 1	page must not be less than 1
`pageSize` fora de 5 – 50	pageSize must not be less than 5 / must not be greater than 50
`from_time` inválido	from_time must be a valid ISO date string
`to_time` inválido	to_time must be a valid ISO date string
`from_time` > `to_time`	from_time must be earlier than or equal to to_time
`municipality` inválido	municipality is not a valid municipality

Notas

Ordenação: por occurredAt decrescente; registos sem esse campo usam createdAt para ordenação e tendem a aparecer depois dos mais recentes com occurredAt explícito.
Filtro municipality: corresponde ao campo de topo do relatório preenchido por geocodificação, não pesquisa dentro de geoInfo.
Campos geográficos opcionais: municipality, freguesia, street, doorNumber e postal_code em location podem ser omitidos se ainda não houver enriquecimento ou o geocoder não devolver valor.
Autenticação: endpoint público, sem credenciais.