DOCUMENTAÇÃO

Introdução

A PTAPI disponibiliza serviços REST para consultar dados portugueses através de métodos simples e respostas JSON.

Base URL

https://api.ptapi.net

Autenticação

Todos os métodos das APIs exigem uma chave ativa enviada como Bearer token.

Authorization: Bearer CHAVE_API

A chave deve pertencer a uma subscrição ativa. Os domínios configurados são comparados com os headers Origin ou Referer. Uma origem ausente ou não reconhecida fica assinalada nos logs como ONR, mas não bloqueia o pedido.

Respostas de erro

Os erros são devolvidos em JSON com uma descrição legível e um código estável para tratamento pela aplicação. Cada página de API documenta adicionalmente os erros próprios dos seus métodos.

{
  "error": "Descrição do erro.",
  "code": "error_code"
}
401invalid_api_key — chave ausente, inválida, revogada ou sem acesso.
404service_not_found — serviço inexistente ou inativo.
404service_method_not_found — método inexistente no serviço.
405method_not_allowed — foi utilizado um verbo diferente de GET.
429quota_exhausted — o plafond disponível foi esgotado.

Limites

Quando existe um limite, a resposta indica o total e o valor restante nos headers:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 998

Estado do serviço

Os endpoints de saúde não exigem chave. /health verifica a API e a ligação à base de dados; /health/services lista os serviços ativos e indica se cada um tem um handler disponível.

GET /health
GET /health/services