1. Revisões
| Data | Versão | Descrição |
|---|---|---|
2025-11-28 |
DRAFT |
Revisão inicial da especificação. |
2025-12-10 |
DRAFT |
Alteração do âmbito da API; Adição de dados devolvidos sobre o cidadão; Adição de endpoints para gestão de representações; Remoção do endpoint de listagem de serviços. |
2026-01-27 |
1.0 |
Revisão final da primeira versão da especificação. |
2026-05-07 |
2.0 |
Atualização dos endereços do serviço; Adição de novos atributos de pesquisa do cidadão. |
2026-09-08 |
3.0 |
Adição do capítulo "Contas": endpoints genéricos de obtenção e pesquisa de contas (cidadão ou organização) e de gestão de representações e pedidos de representação por conta. |
2. Introdução
2.1. Âmbito
Devido à necessidade de integrar os diversos sistemas cliente com a plataforma AzorID, e considerando que algumas funcionalidades exigidas não são contempladas pelos padrões OpenID e OAuth2, foi desenvolvida uma API para o efeito. Esta API permite disponibilizar funcionalidades específicas, tais como:
-
verificar a existência de contas na plataforma AzorID;
-
obter dados associados a contas;
-
gerir representações.
Esta API não se sobrepõe aos serviços disponibilizados para integração OpenID, sendo que todos os fluxos de autenticação integrados com o AzorID regem-se por esse standard e estão descritos em outra documentação, nomeadamente, o "Protocolo e Especificação Técnica" e "Guia prático de integração OpenID".
2.2. Objetivo
Este documento tem como objetivo descrever a API AzorID, detalhando os seus endpoints, métodos suportados, parâmetros e exemplos de pedidos e respostas.
2.3. Terminologia
| Termo | Definição |
|---|---|
Access Token |
Chave utilizada para autenticação nos endpoints da API, podendo ser transmitida por diversas vias |
API |
Application Programming Interface: conjunto de definições e protocolos para a construção e integração de software |
Bearer Token |
Chave de acesso transmitida no cabeçalho |
Client Credentials Flow |
Fluxo OAuth2 para autenticação de aplicações |
Endpoint |
Um ponto de acesso específico na API para realizar uma operação de consulta ou escrita |
GUID |
Identificador Global Único utilizado para identificar recursos |
HTTP |
HyperText Transfer Protocol: protocolo de comunicação utilizado para a transferência de dados na web |
HTTP Header |
Cabeçalho HTTP: parte de um pedido ou resposta HTTP que contém informações adicionais sobre a mensagem |
IDP |
Identity Provider: sistema provedor de identidades, responsável pelo processo de autenticação e autorização |
OAuth2 |
Um padrão de autorização que permite a um sistema (cliente) aceder a dados de um utilizador noutro serviço (servidor de recursos), sem que o utilizador tenha de partilhar as suas credenciais |
OpenID |
Uma extensão ao padrão OAuth 2.0, adicionando funcionalidades padronizadas para autenticação de utilizadores e fornecimento de informações associadas |
Representação |
Relação que permite a um cidadão atuar em nome de outro |
Representado |
Cidadão que é representado por outro cidadão no contexto de uma ação específica |
Representante |
Cidadão que representa outro cidadão no contexto de uma ação específica |
Scope |
Grupo de permissões associado ao pedido de autenticação ou a uma chave de acesso |
3. Autenticação
Todos os pedidos efetuados à API devem ser autenticados através de um token de acesso (bearer token).
A obtenção do token de acesso é realizada através do IDP do sistema AzorID, utilizando o fluxo de client credentials.
3.1. Obtenção do token de acesso
Para obter um access token, o cliente deve enviar um pedido HTTP POST para o token endpoint do IDP com as respetivas credenciais de cliente.
O processo de obtenção do token segue o standard OAuth2 "client credentials flow" [RFC6749], sendo que as respostas esperadas, quer em caso de sucesso ou erro, são as descritas na respetiva especificação.
3.1.1. Pedido de exemplo
POST /openid/token HTTP/1.1
Host: azorid.azores.gov.pt
Content-Type: application/x-www-form-urlencoded
grant_type=client_credentials
&client_id=YOUR_CLIENT_ID
&client_secret=YOUR_CLIENT_SECRET
3.1.2. Corpo da resposta de exemplo
{
"access_token": "YOUR_ACCESS_TOKEN",
"token_type": "Bearer",
"expires_in": 300,
"scope": ""
}
3.2. Pedidos autenticados à API
Todos os pedidos à API devem incluir o access token no header HTTP Authorization no formato “Bearer {token}”.
GET /example-endpoint HTTP/1.1
Host: azorid-api.azores.gov.pt
Authorization: Bearer YOUR_ACCESS_TOKEN
3.3. Diagrama
4. Contas
São disponibilizados endpoints genéricos para a consulta e gestão de contas, aplicáveis tanto a cidadãos como a organizações. Uma conta é sempre identificada pelo seu identificador único (id) no sistema AzorID. O acesso a cada grupo de endpoints depende das permissões atribuídas ao cliente.
4.1. Obter dados da conta
GET /accounts/{id}
Obtém os dados da conta associada ao identificador único fornecido. Uma conta pode corresponder a um cidadão ou a uma organização; a estrutura da resposta difere entre os dois casos, sendo o tipo indicado no campo accountType (ver Tipos de conta).
4.1.1. Parâmetros do pedido
| Parâmetro | Tipo | Descrição |
|---|---|---|
|
|
Identificador único da conta no sistema AzorID. |
4.1.2. Estados de resposta
| Código | Descrição |
|---|---|
|
A conta foi encontrada e os seus dados são retornados no corpo da resposta. |
|
Não existe nenhuma conta com o identificador fornecido. |
|
NOTA
|
Alem dos estados descritos nesta secção, aplicam-se também os estados de erro gerais da API descritos na secção Erros. |
4.1.3. Estrutura da resposta (200)
Campos comuns a todos os tipos de conta:
| Campo | Tipo | Descrição |
|---|---|---|
|
|
Tipo de conta, de acordo com Tipos de conta. |
|
|
Identificador único da conta no sistema AzorID. |
|
|
Nome de apresentação da conta. |
|
|
Data de registo da conta em formato ISO 8601. |
|
|
Indica se a identidade associada à conta está certificada. |
Conta de cidadão (accountType = Citizen)
Além dos campos comuns:
| Campo | Tipo | Descrição |
|---|---|---|
|
|
Nome completo do cidadão, caso disponível e certificado. |
|
|
Número de conta AzorID. |
|
|
Número do Cartão de Cidadão, caso disponível e certificado. |
|
|
Data de expiração do Cartão de Cidadão em formato ISO 8601, caso disponível e certificado. |
|
|
Número de Identificação Fiscal (NIF), caso disponível e certificado. |
|
|
Número Nacional de Utente, caso disponível e certificado. |
|
|
Número do Passaporte, caso disponível e certificado. |
|
|
Número de Identificação da Segurança Social (NISS), caso disponível e certificado. |
|
|
Data de expiração do Passaporte em formato ISO 8601, caso disponível e certificado. |
|
|
Estado civil, de acordo com Tipos de estado civil, caso disponível e certificado. |
|
|
Lista de endereços associados ao cidadão, caso disponíveis e certificados. |
|
|
Lista de contactos ativos associados ao cidadão, caso disponíveis e certificados. |
|
|
Data de nascimento em formato ISO 8601, caso disponível e certificada. |
|
|
Nacionalidade do cidadão, caso disponível e certificada. |
Conta de organização (accountType = Organization)
Além dos campos comuns:
| Campo | Tipo | Descrição |
|---|---|---|
|
|
Designação social da organização. |
|
|
Número de conta AzorID. |
|
|
Número de Identificação de Pessoa Coletiva (NIPC). |
Address
| Campo | Tipo | Descrição |
|---|---|---|
|
|
Código do distrito. |
|
|
Nome do distrito. |
|
|
Código do concelho. |
|
|
Nome do concelho. |
|
|
Código da localidade no domínio CTT, ou vazio se não disponível. |
|
|
Nome da localidade. |
|
|
Código postal. |
|
|
Extensão do código postal. |
|
|
Designação postal. |
|
|
Código da rua/via/estrada no domínio CTT, se disponível. |
|
|
Nome da rua/via/estrada. |
|
|
Representação textual da via. |
|
|
Designação adicional do endereço, como número da porta, andar, etc. |
|
|
Conjunto de linhas que representam a morada em formato de texto, de acordo com as normas CTT. |
|
|
Tipo do endereço de acordo com Tipos de endereço. |
Contact
| Campo | Tipo | Descrição |
|---|---|---|
|
|
Tipo de contacto (e.g. |
|
|
Valor do contacto. |
|
|
Código de chamada internacional, aplicável a contactos telefónicos (e.g. |
|
|
Indica se este é o contacto principal. |
Nationality
| Campo | Tipo | Descrição |
|---|---|---|
|
|
Código da nacionalidade - ISO 3166-1 alpha-2. |
|
|
Nome do país. |
4.1.4. Exemplo de pedido
GET /accounts/00000000-0000-0000-0000-000000000001 HTTP/1.1
Host: azorid-api.azores.gov.pt
Authorization: Bearer YOUR_ACCESS_TOKEN
4.1.5. Exemplo de resposta (cidadão)
{
"accountType": "Citizen",
"id": "00000000-0000-0000-0000-000000000001",
"displayName": "João Silva",
"registration": "2025-10-01T12:00:00Z",
"isAccountCertified": true,
"name": "João Silva",
"accountNumber": "123456",
"citizenCardNumber": "1234567890",
"citizenCardExpirationDate": "2030-12-31",
"fiscalNumber": "123456789",
"patientNumber": "987654321",
"passportNumber": "AA1234567",
"socialSecurityNumber": "11234567890",
"passportExpirationDate": "2028-05-15",
"maritalStatus": "Single",
"addresses": [
{
"districtCode": "43",
"districtName": "Ilha Terceira",
"countyCode": "4301",
"countyName": "Angra do Heroísmo",
"localityCode": "",
"localityName": "Angra do Heroísmo",
"postalCode": "9700",
"postalCodeExtension": "191",
"postalCodeDesignation": "ANGRA DO HEROÍSMO",
"streetCode": "1810143",
"streetName": "Rua da Sé",
"address": "Rua da Sé",
"unitNumber": "10",
"displayLines": [
"Rua da Sé, 10",
"Angra do Heroísmo",
"9700-191 ANGRA DO HEROÍSMO"
],
"nature": "Default"
}
],
"contacts": [
{
"nature": "PhoneNumber",
"value": "912345678",
"countryCallingCode": "+351",
"isPrimary": true
},
{
"nature": "Email",
"value": "[email protected]",
"isPrimary": true
}
],
"birthDate": "1990-01-15",
"nationality": {
"code": "PT",
"name": "Portugal"
}
}
4.1.6. Exemplo de resposta (organização)
{
"accountType": "Organization",
"id": "00000000-0000-0000-0000-000000000010",
"displayName": "Empresa Exemplo, Lda.",
"registration": "2024-03-12T09:30:00Z",
"isAccountCertified": true,
"socialDesignation": "Empresa Exemplo, Lda.",
"accountNumber": "345678",
"fiscalNumber": "500123456"
}
4.2. Pesquisar contas
GET /accounts/search
Pesquisa contas com base num ou mais atributos identificadores. Devolve uma lista com as contas correspondentes (no máximo 24). Caso nenhum parâmetro de pesquisa válido seja fornecido, é devolvida uma lista vazia.
|
NOTA
|
Quando um dos atributos fornecidos corresponde de forma inequívoca a uma única conta (correspondência exata sobre um atributo atualmente certificado), é devolvida apenas essa conta. |
4.2.1. Parâmetros opcionais do pedido (query string)
| Parâmetro | Tipo | Descrição |
|---|---|---|
|
|
Número de Identificação Fiscal (NIF) ou de Pessoa Coletiva (NIPC) — 9 dígitos. |
|
|
Número de Identificação Civil — 8 dígitos. |
|
|
Endereço de correio eletrónico de um contacto ativo do cidadão. |
|
|
Número de conta AzorID, de um cidadão ou de uma organização — 6 a 9 dígitos. |
|
NOTA
|
Parâmetros com formato inválido são ignorados. Se, após esta validação, não restar nenhum parâmetro de pesquisa, é devolvida uma lista vazia. |
4.2.2. Estados de resposta
| Código | Descrição |
|---|---|
|
A pesquisa foi executada; o corpo da resposta contém a lista de contas correspondentes (eventualmente vazia). |
|
NOTA
|
Alem dos estados descritos nesta secção, aplicam-se também os estados de erro gerais da API descritos na secção Erros. |
4.2.3. Estrutura da resposta (200)
Lista (array) de objetos com a mesma estrutura descrita em Obter dados da conta.
4.2.4. Exemplo de pedido
GET /accounts/search?fiscalNumber=123456789 HTTP/1.1
Host: azorid-api.azores.gov.pt
Authorization: Bearer YOUR_ACCESS_TOKEN
4.2.5. Exemplo de resposta
[
{
"accountType": "Citizen",
"id": "00000000-0000-0000-0000-000000000001",
"displayName": "João Silva",
"registration": "2025-10-01T12:00:00Z",
"isAccountCertified": true,
"name": "João Silva",
"accountNumber": "123456",
"fiscalNumber": "123456789",
"addresses": [],
"contacts": []
}
]
4.3. Listar representações da conta
GET /accounts/{id}/representations
Retorna a lista de representações em que a conta indicada participa, seja como representante seja como representada. Ao contrário de um pedido de representação, cada representação abrange sempre um único serviço.
4.3.1. Parâmetros do pedido
| Parâmetro | Tipo | Descrição |
|---|---|---|
|
|
Identificador único da conta no sistema AzorID. |
4.3.2. Parâmetros opcionais do pedido (query string)
| Parâmetro | Tipo | Descrição |
|---|---|---|
|
|
Filtra as representações pelo papel da conta, de acordo com Papéis de representação. Se omitido, são retornadas as representações em ambos os papéis. |
|
|
Se |
4.3.3. Estados de resposta
| Código | Descrição |
|---|---|
|
As representações são retornadas no corpo da resposta. |
|
NOTA
|
Alem dos estados descritos nesta secção, aplicam-se também os estados de erro gerais da API descritos na secção Erros. |
4.3.4. Estrutura da resposta (200)
| Campo | Tipo | Descrição |
|---|---|---|
|
|
Lista de representações. |
Representation
| Campo | Tipo | Descrição |
|---|---|---|
|
|
ID da representação no sistema AzorID. |
|
|
Papel da conta indicada nesta representação, de acordo com Papéis de representação. |
|
|
ID da contraparte — a outra conta envolvida na representação. |
|
|
Nome de apresentação da contraparte. |
|
|
Número de conta AzorID da contraparte (cidadão ou organização). |
|
|
Data de início da representação em formato ISO 8601. |
|
|
Data de fim da representação em formato ISO 8601, caso definida. |
|
|
Data de criação da representação em formato ISO 8601. |
|
|
Data da última atualização da representação em formato ISO 8601, caso tenha sido alterada. |
|
|
Data de revogação da representação em formato ISO 8601, caso tenha sido revogada. |
|
|
Indica se a representação está atualmente em vigor. |
|
|
O serviço abrangido pela representação. |
RepresentationService
| Campo | Tipo | Descrição |
|---|---|---|
|
|
ID do serviço no sistema AzorID. |
|
|
Código do serviço. |
|
|
Nome do serviço. |
4.3.5. Exemplo de pedido
GET /accounts/00000000-0000-0000-0000-000000000001/representations?role=AsRepresentative HTTP/1.1
Host: azorid-api.azores.gov.pt
Authorization: Bearer YOUR_ACCESS_TOKEN
4.3.6. Exemplo de resposta
{
"representations": [
{
"id": "00000000-0000-0000-0000-000000000001",
"role": "AsRepresentative",
"counterpartId": "00000000-0000-0000-0000-000000000002",
"counterpartDisplayName": "Maria Silva",
"counterpartAccountNumber": "234567",
"start": "2025-10-01T12:00:00Z",
"end": "2026-10-01T12:00:00Z",
"creation": "2025-10-01T12:00:00Z",
"lastUpdate": "2025-10-15T12:00:00Z",
"isActive": true,
"service": {
"id": "00000000-0000-0000-0000-000000000003",
"code": "SERVICE-CODE-001",
"name": "Service Name 1"
}
}
]
}
4.4. Obter representação
GET /accounts/{id}/representations/{representationId}
Retorna uma representação específica, desde que a conta indicada seja parte da mesma.
4.4.1. Parâmetros do pedido
| Parâmetro | Tipo | Descrição |
|---|---|---|
|
|
Identificador único da conta no sistema AzorID. |
|
|
ID da representação no sistema AzorID. |
4.4.2. Estados de resposta
| Código | Descrição |
|---|---|
|
A representação foi encontrada e é retornada no corpo da resposta. |
|
A representação não existe ou a conta indicada não é parte da mesma. |
|
NOTA
|
Alem dos estados descritos nesta secção, aplicam-se também os estados de erro gerais da API descritos na secção Erros. |
4.4.3. Estrutura da resposta (200)
Objeto Representation, com a estrutura descrita em Listar representações da conta.
4.4.4. Exemplo de pedido
GET /accounts/00000000-0000-0000-0000-000000000001/representations/00000000-0000-0000-0000-000000000001 HTTP/1.1
Host: azorid-api.azores.gov.pt
Authorization: Bearer YOUR_ACCESS_TOKEN
4.4.5. Exemplo de resposta
{
"id": "00000000-0000-0000-0000-000000000001",
"role": "AsRepresentative",
"counterpartId": "00000000-0000-0000-0000-000000000002",
"counterpartDisplayName": "Maria Silva",
"counterpartAccountNumber": "234567",
"start": "2025-10-01T12:00:00Z",
"end": "2026-10-01T12:00:00Z",
"creation": "2025-10-01T12:00:00Z",
"lastUpdate": "2025-10-15T12:00:00Z",
"isActive": true,
"service": {
"id": "00000000-0000-0000-0000-000000000003",
"code": "SERVICE-CODE-001",
"name": "Service Name 1"
}
}
4.5. Criar representação
POST /accounts/{id}/representations
Cria diretamente uma ou mais representações em que a conta indicada é a representada, sem passar pelo fluxo de pedido e consentimento descrito em Criar pedido de representação. É criada uma representação por cada serviço indicado.
|
NOTA
|
Os serviços já cobertos por uma representação ativa para o mesmo par (representado/representante) são ignorados. Se, após esta filtragem, não restar nenhum serviço, a operação falha com 409 Conflict.
|
4.5.1. Parâmetros do pedido
| Parâmetro | Tipo | Descrição |
|---|---|---|
|
|
Identificador único da conta representada no sistema AzorID. |
4.5.2. Estrutura do corpo do pedido
| Campo | Tipo | Descrição |
|---|---|---|
|
|
ID da conta do cidadão representante. Obrigatório se |
|
|
Código de representação do cidadão representante. Obrigatório se |
|
|
Data de início da representação em formato ISO 8601. |
|
|
Data de fim da representação em formato ISO 8601. Se definida, não pode ser anterior ao início nem exceder o início em mais de 6 meses. |
|
|
Lista de códigos dos serviços a representar. Cada serviço tem de permitir representação. |
4.5.3. Estados de resposta
| Código | Descrição |
|---|---|
|
As representações foram criadas com sucesso e os respetivos IDs são retornados no corpo da resposta. |
|
NOTA
|
Alem dos estados descritos nesta secção, aplicam-se também os estados de erro gerais da API descritos na secção Erros. Em particular, é retornado 409 Conflict quando o representante não está certificado, quando o representante coincide com a conta representada, quando algum código de serviço é inválido ou não permite representação, quando a duração excede 6 meses, ou quando todos os serviços já se encontram representados para o par.
|
4.5.4. Estrutura da resposta (200)
| Campo | Tipo | Descrição |
|---|---|---|
|
|
Mapa das representações criadas, em que cada chave é o código do serviço e o respetivo valor é o ID ( |
4.5.5. Exemplo de pedido
POST /accounts/00000000-0000-0000-0000-000000000001/representations HTTP/1.1
Host: azorid-api.azores.gov.pt
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json
{
"representativeCode": "234567",
"start": "2025-12-01T00:00:00Z",
"end": "2026-06-01T00:00:00Z",
"serviceCodes": [
"SERVICE-CODE-001",
"SERVICE-CODE-002"
]
}
4.5.6. Exemplo de resposta
{
"representationIdsByServiceCode": {
"SERVICE-CODE-001": "00000000-0000-0000-0000-000000000003",
"SERVICE-CODE-002": "00000000-0000-0000-0000-000000000004"
}
}
4.6. Revogar representação
POST /accounts/{id}/representations/{representationId}/revoke
Revoga uma representação em que a conta indicada é parte. A revogação tem efeito imediato.
4.6.1. Parâmetros do pedido
| Parâmetro | Tipo | Descrição |
|---|---|---|
|
|
Identificador único da conta no sistema AzorID. |
|
|
ID da representação a revogar. |
4.6.2. Estados de resposta
| Código | Descrição |
|---|---|
|
A representação foi revogada com sucesso. |
|
A representação não existe ou a conta indicada não é parte da mesma. |
|
A representação já se encontra revogada. |
|
NOTA
|
Alem dos estados descritos nesta secção, aplicam-se também os estados de erro gerais da API descritos na secção Erros. |
4.6.3. Estrutura da resposta (200)
Não é retornado nenhum conteúdo no corpo da resposta.
4.6.4. Exemplo de pedido
POST /accounts/00000000-0000-0000-0000-000000000001/representations/00000000-0000-0000-0000-000000000003/revoke HTTP/1.1
Host: azorid-api.azores.gov.pt
Authorization: Bearer YOUR_ACCESS_TOKEN
4.7. Criar pedido de representação
POST /accounts/{id}/representations/requests
Cria um pedido de representação em que a conta indicada é a representada — ou seja, a conta que solicita ser representada. O pedido é criado no estado Pending e permanece nesse estado até ser respondido pelo representante (ver Responder a um pedido de representação).
Ao criar o pedido, o cidadão indicado como representante é notificado.
|
NOTA
|
Os serviços já cobertos por uma representação ativa, ou por um pedido pendente, para o mesmo par (representado/representante) são ignorados. Se, após esta filtragem, não restar nenhum serviço, a operação falha com 409 Conflict.
|
4.7.1. Parâmetros do pedido
| Parâmetro | Tipo | Descrição |
|---|---|---|
|
|
Identificador único da conta representada no sistema AzorID. |
4.7.2. Estrutura do corpo do pedido
| Campo | Tipo | Descrição |
|---|---|---|
|
|
ID da conta do cidadão representante. Obrigatório se |
|
|
Código de representação do cidadão representante. Obrigatório se |
|
|
Data de início da representação pretendida em formato ISO 8601. |
|
|
Data de fim da representação pretendida em formato ISO 8601. Não pode ser anterior ao início nem exceder o início em mais de 6 meses. |
|
|
Lista de códigos dos serviços a associar ao pedido. Cada serviço tem de permitir representação. |
4.7.3. Estados de resposta
| Código | Descrição |
|---|---|
|
O pedido de representação foi criado com sucesso e o respetivo ID é retornado no corpo da resposta. |
|
NOTA
|
Alem dos estados descritos nesta secção, aplicam-se também os estados de erro gerais da API descritos na secção Erros. Em particular, é retornado 409 Conflict quando o representante não está certificado, quando o representante coincide com a conta representada, quando algum código de serviço é inválido ou não permite representação, quando a duração excede 6 meses, ou quando não resta nenhum serviço por representar após a filtragem descrita acima.
|
4.7.4. Estrutura da resposta (200)
| Campo | Tipo | Descrição |
|---|---|---|
|
|
Mapa do pedido de representação criado, em que cada chave é o código de um serviço efetivamente incluído no pedido e o respetivo valor é o ID ( |
4.7.5. Exemplo de pedido
POST /accounts/00000000-0000-0000-0000-000000000001/representations/requests HTTP/1.1
Host: azorid-api.azores.gov.pt
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json
{
"representativeCode": "234567",
"start": "2025-12-01T00:00:00Z",
"end": "2026-06-01T00:00:00Z",
"serviceCodes": [
"SERVICE-CODE-001",
"SERVICE-CODE-002"
]
}
4.7.6. Exemplo de resposta
{
"requestIdsByServiceCode": {
"SERVICE-CODE-001": "00000000-0000-0000-0000-000000000005",
"SERVICE-CODE-002": "00000000-0000-0000-0000-000000000005"
}
}
4.8. Listar pedidos de representação
GET /accounts/{id}/representations/requests
Retorna a lista de pedidos de representação em que a conta indicada participa, seja como representante (pedidos recebidos) seja como representada (pedidos efetuados).
4.8.1. Parâmetros do pedido
| Parâmetro | Tipo | Descrição |
|---|---|---|
|
|
Identificador único da conta no sistema AzorID. |
4.8.2. Parâmetros opcionais do pedido (query string)
| Parâmetro | Tipo | Descrição |
|---|---|---|
|
|
Filtra pela direção do pedido relativamente à conta, de acordo com Direção do pedido de representação. Se omitido, são retornados os pedidos em ambas as direções. |
|
|
Filtra pelo estado do pedido, de acordo com Tipos de estado de pedido de representação. |
4.8.3. Estados de resposta
| Código | Descrição |
|---|---|
|
Os pedidos de representação são retornados no corpo da resposta. |
|
NOTA
|
Alem dos estados descritos nesta secção, aplicam-se também os estados de erro gerais da API descritos na secção Erros. |
4.8.4. Estrutura da resposta (200)
| Campo | Tipo | Descrição |
|---|---|---|
|
|
Lista de pedidos de representação, ordenada do mais recente para o mais antigo. |
RepresentationRequest
| Campo | Tipo | Descrição |
|---|---|---|
|
|
ID do pedido de representação no sistema AzorID. |
|
|
Direção do pedido relativamente à conta indicada, de acordo com Direção do pedido de representação. |
|
|
Estado do pedido, de acordo com Tipos de estado de pedido de representação. |
|
|
ID da conta representada — a conta que efetuou o pedido. |
|
|
Nome de apresentação da conta representada. |
|
|
ID da conta representante — a conta que recebeu o pedido. |
|
|
Nome de apresentação da conta representante. |
|
|
Data de início da representação pretendida em formato ISO 8601. |
|
|
Data de fim da representação pretendida em formato ISO 8601. |
|
|
Data de criação do pedido em formato ISO 8601. |
|
|
Data da última atualização do pedido em formato ISO 8601, caso tenha sido alterado. |
|
|
Lista de serviços associados ao pedido. |
RepresentationService
| Campo | Tipo | Descrição |
|---|---|---|
|
|
ID do serviço no sistema AzorID. |
|
|
Código do serviço. |
|
|
Nome do serviço. |
4.8.5. Exemplo de pedido
GET /accounts/00000000-0000-0000-0000-000000000001/representations/requests?direction=Outbound&status=Pending HTTP/1.1
Host: azorid-api.azores.gov.pt
Authorization: Bearer YOUR_ACCESS_TOKEN
4.8.6. Exemplo de resposta
{
"requests": [
{
"id": "00000000-0000-0000-0000-000000000005",
"direction": "Outbound",
"status": "Pending",
"requesterId": "00000000-0000-0000-0000-000000000001",
"requesterDisplayName": "João Silva",
"representativeId": "00000000-0000-0000-0000-000000000002",
"representativeDisplayName": "Maria Silva",
"start": "2025-12-01T00:00:00Z",
"end": "2026-06-01T00:00:00Z",
"creation": "2025-11-20T10:00:00Z",
"services": [
{
"id": "00000000-0000-0000-0000-000000000003",
"code": "SERVICE-CODE-001",
"name": "Service Name 1"
}
]
}
]
}
4.9. Obter pedido de representação
GET /accounts/{id}/representations/requests/{requestId}
Retorna um pedido de representação específico, desde que a conta indicada participe no mesmo.
4.9.1. Parâmetros do pedido
| Parâmetro | Tipo | Descrição |
|---|---|---|
|
|
Identificador único da conta no sistema AzorID. |
|
|
ID do pedido de representação no sistema AzorID. |
4.9.2. Estados de resposta
| Código | Descrição |
|---|---|
|
O pedido foi encontrado e é retornado no corpo da resposta. |
|
O pedido não existe ou a conta indicada não participa no mesmo. |
|
NOTA
|
Alem dos estados descritos nesta secção, aplicam-se também os estados de erro gerais da API descritos na secção Erros. |
4.9.3. Estrutura da resposta (200)
Objeto RepresentationRequest, com a estrutura descrita em Listar pedidos de representação.
4.9.4. Exemplo de pedido
GET /accounts/00000000-0000-0000-0000-000000000001/representations/requests/00000000-0000-0000-0000-000000000005 HTTP/1.1
Host: azorid-api.azores.gov.pt
Authorization: Bearer YOUR_ACCESS_TOKEN
4.10. Responder a um pedido de representação
Um pedido de representação no estado Pending pode transitar para um estado final através de um dos endpoints descritos nesta secção.
Todos estes endpoints exigem que o pedido esteja no estado Pending; caso contrário é retornado 409 Conflict. Nenhum deles retorna conteúdo no corpo da resposta.
4.10.1. Aprovar pedido de representação
POST /accounts/{id}/representations/requests/{requestId}/approve
Aprova um pedido de representação. Apenas a conta representante — a que recebeu o pedido — pode aprovar.
Ao aprovar, são criadas as representações correspondentes (uma por cada serviço associado ao pedido) e a conta representada é notificada.
Parâmetros do pedido
| Parâmetro | Tipo | Descrição |
|---|---|---|
|
|
Identificador único da conta representante no sistema AzorID. |
|
|
ID do pedido de representação a aprovar. |
Estados de resposta
| Código | Descrição |
|---|---|
|
O pedido foi aprovado e as representações foram criadas. |
|
O pedido não existe ou a conta indicada não participa no mesmo. |
|
O pedido não está no estado |
|
NOTA
|
Alem dos estados descritos nesta secção, aplicam-se também os estados de erro gerais da API descritos na secção Erros. |
Estrutura da resposta (200)
Não é retornado nenhum conteúdo no corpo da resposta.
Exemplo de pedido
POST /accounts/00000000-0000-0000-0000-000000000002/representations/requests/00000000-0000-0000-0000-000000000005/approve HTTP/1.1
Host: azorid-api.azores.gov.pt
Authorization: Bearer YOUR_ACCESS_TOKEN
4.10.2. Rejeitar pedido de representação
POST /accounts/{id}/representations/requests/{requestId}/reject
Rejeita um pedido de representação. Apenas a conta representante pode rejeitar. Não são criadas representações. A conta representada é notificada.
Parâmetros do pedido
| Parâmetro | Tipo | Descrição |
|---|---|---|
|
|
Identificador único da conta representante no sistema AzorID. |
|
|
ID do pedido de representação a rejeitar. |
Estados de resposta
| Código | Descrição |
|---|---|
|
O pedido foi rejeitado. |
|
O pedido não existe ou a conta indicada não participa no mesmo. |
|
O pedido não está no estado |
|
NOTA
|
Alem dos estados descritos nesta secção, aplicam-se também os estados de erro gerais da API descritos na secção Erros. |
Estrutura da resposta (200)
Não é retornado nenhum conteúdo no corpo da resposta.
Exemplo de pedido
POST /accounts/00000000-0000-0000-0000-000000000002/representations/requests/00000000-0000-0000-0000-000000000005/reject HTTP/1.1
Host: azorid-api.azores.gov.pt
Authorization: Bearer YOUR_ACCESS_TOKEN
4.10.3. Cancelar pedido de representação
POST /accounts/{id}/representations/requests/{requestId}/cancel
Cancela um pedido de representação. Apenas a conta representada — a que efetuou o pedido — pode cancelar.
Parâmetros do pedido
| Parâmetro | Tipo | Descrição |
|---|---|---|
|
|
Identificador único da conta representada no sistema AzorID. |
|
|
ID do pedido de representação a cancelar. |
Estados de resposta
| Código | Descrição |
|---|---|
|
O pedido foi cancelado. |
|
O pedido não existe ou a conta indicada não participa no mesmo. |
|
O pedido não está no estado |
|
NOTA
|
Alem dos estados descritos nesta secção, aplicam-se também os estados de erro gerais da API descritos na secção Erros. |
Estrutura da resposta (200)
Não é retornado nenhum conteúdo no corpo da resposta.
Exemplo de pedido
POST /accounts/00000000-0000-0000-0000-000000000001/representations/requests/00000000-0000-0000-0000-000000000005/cancel HTTP/1.1
Host: azorid-api.azores.gov.pt
Authorization: Bearer YOUR_ACCESS_TOKEN
5. Cidadãos
|
NOTA
|
Encontra-se disponível um endpoint genérico de contas (ver Contas) que permite obter e pesquisar dados tanto de cidadãos como de organizações através de uma interface comum. Para novas integrações, deve ser dada preferência a esse endpoint. |
Estes endpoints mantém-se documentados por questões de retrocompatibilidade.
5.1. Obter dados do cidadão
Os dados do cidadão podem ser obtidos através de um identificador pesquisável, como o NIF ou o código de representação, ou através do identificador único do cidadão no sistema AzorID.
O sistema cliente, não conhecendo o identificador único do cidadão, deve utilizar o endpoint de obtenção via identificador pesquisável. No entanto, deve guardar o identificador único do cidadão caso necessário para futuros pedidos a outros endpoints.
5.1.1. Obter via identificador pesquisável
GET /citizens/{identifierType}/{identifier}
Obtem os dados do cidadão associado ao identificador fornecido, caso o mesmo se encontre registado no sistema AzorID.
Parâmetros do pedido
| Parâmetro | Tipo | Descrição |
|---|---|---|
|
|
Tipo de identificador do cidadão (e.g., |
|
|
Valor do identificador do cidadão. |
5.1.2. Obter via identificador único
GET /citizens/{id}
Pesquisa e retorna os dados do cidadão associado ao ID fornecido.
Parâmetros do pedido
| Parâmetro | Tipo | Descrição |
|---|---|---|
|
|
ID do cidadão no sistema AzorID. |
5.1.3. Estados de resposta
A resposta a ambos os endpoints é idêntica, seguindo a estrutura descrita abaixo.
| Código | Descrição |
|---|---|
|
O cidadão foi encontrado e os seus dados são retornados no corpo da resposta. |
|
O cidadão com o identificador fornecido não foi encontrado no sistema. |
|
NOTA
|
Alem dos estados descritos nesta secção, aplicam-se também os estados de erro gerais da API descritos na secção Erros. |
5.1.4. Estrutura da resposta (200)
| Campo | Tipo | Descrição |
|---|---|---|
|
|
Identificador único do cidadão no sistema AzorID. |
|
|
Data de registo do cidadão em formato ISO 8601. |
|
|
Lista de identificadores pesquisáveis associados ao cidadão. |
|
|
Indica se a conta do cidadão está certificada. |
|
|
Nome completo do cidadão. |
|
|
Número de conta AzorID. |
|
|
Número do Cartão de Cidadão do cidadão, caso o mesmo esteja disponível e certificado. |
|
|
Data de expiração do Cartão de Cidadão do cidadão em formato ISO 8601, caso o mesmo esteja disponível e certificado. |
|
|
Número de Identificação Fiscal (NIF) do cidadão, caso o mesmo esteja disponível e certificado. |
|
|
Número Nacional de Utente do cidadão, caso o mesmo esteja disponível e certificado. |
|
|
Número do Passaporte do cidadão, caso o mesmo esteja disponível e certificado. |
|
|
Data de expiração do Passaporte do cidadão em formato ISO 8601, caso o mesmo esteja disponível e certificado. |
|
|
Estado civil do cidadão, caso o mesmo esteja disponível e certificado, de acordo com a tabela Tipos de estado civil. |
|
|
Lista de endereços associados ao cidadão, caso os mesmos estejam disponíveis e certificados. |
|
|
Lista de contactos associados ao cidadão, caso os mesmos estejam disponíveis e certificados. |
|
|
Data de nascimento do cidadão em formato ISO 8601, caso a mesma esteja disponível e certificado. |
|
|
Nacionalidade do cidadão, caso a mesma esteja disponível e certificada. |
|
|
Informações relativas á mãe do cidadão, caso as mesmas estejam disponíveis e certificadas. |
|
|
Informações relativas ao pai do cidadão, caso as mesmas estejam disponíveis e certificadas. |
Identifier
| Campo | Tipo | Descrição |
|---|---|---|
|
|
Tipo de identificador de acordo com a tabela Tipos de identificadores pesquisáveis. |
|
|
Valor do identificador. |
Address
| Campo | Tipo | Descrição |
|---|---|---|
|
|
Código do distrito. |
|
|
Nome do distrito. |
|
|
Código do concelho. |
|
|
Nome do concelho. |
|
|
Código da freguesia. |
|
|
Nome da freguesia. |
|
|
Código postal. |
|
|
Extensão do código postal. |
|
|
Designação postal. |
|
|
Código da rua/via/estrada no domínio CTT, se disponível. |
|
|
Nome da rua/via/estrada. |
|
|
Designação adicional do endereço, como número da porta, andar, etc. |
|
|
Conjunto de linhas que representam a morada em formato de texto, de acordo com as normas CTT. |
|
|
Tipo do endereço de acordo com a tabela Tipos de endereço. |
Contact
| Campo | Tipo | Descrição |
|---|---|---|
|
|
Tipo de contacto (e.g. |
|
|
Valor do contacto. |
|
|
Código de chamada internacional, aplicável para contactos telefónicos (e.g. |
|
|
Indica se este é o contacto principal. |
Nationality
| Campo | Tipo | Descrição |
|---|---|---|
|
|
Código da nacionalidade - ISO 3166-1 alpha-2. |
|
|
Nome do país. |
CitizenRelative
| Campo | Tipo | Descrição |
|---|---|---|
|
|
Nome completo do familiar. |
|
|
Número de Identificação Fiscal (NIF) do familiar, caso o mesmo esteja disponível. |
|
|
Número do Cartão de Cidadão do familiar, caso o mesmo esteja disponível. |
|
|
Data de expiração do Cartão de Cidadão do familiar em formato ISO 8601, caso o mesmo esteja disponível. |
5.1.5. Exemplo de pedido
GET /citizens/FiscalNumber/123456789 HTTP/1.1
Host: azorid-api.azores.gov.pt
Authorization: Bearer YOUR_ACCESS_TOKEN
5.1.6. Exemplo de resposta
{
"id": "00000000-0000-0000-0000-000000000001",
"registration": "2025-10-01T12:00:00Z",
"identifiers": [
{
"nature": "FiscalNumber",
"value": "123456789"
},
{
"nature": "RepresentationCode",
"value": "123456"
}
],
"isAccountCertified": true,
"name": "João Silva",
"accountNumber": "123456",
"citizenCardNumber": "1234567890",
"citizenCardExpirationDate": "2030-12-31",
"fiscalNumber": "123456789",
"patientNumber": "987654321",
"passportNumber": "AA1234567",
"passportExpirationDate": "2028-05-15",
"maritalStatus": "Single",
"addresses": [
{
"districtCode": "43",
"districtName": "Ilha Terceira",
"countyCode": "4301",
"countyName": "Angra do Heroísmo",
"parishCode": "4860",
"parishName": "Sé",
"postalCode": "9700",
"postalExtensionCode": "191",
"postalDesignation": "ANGRA DO HEROÍSMO",
"thoroughfareCode": "1810143",
"thoroughfare": "Rua da Sé",
"unit": "10",
"displayLines": [
"Rua da Sé, 10",
"Sé",
"9700-191 ANGRA DO HEROÍSMO"
],
"nature": "Default"
}
],
"contacts": [
{
"nature": "Phone",
"value": "912345678",
"countryCallingCode": "+351",
"isPrimary": true
},
{
"nature": "Email",
"value": "[email protected]",
"isPrimary": true
}
],
"birthDate": "1990-01-15",
"nationality": {
"code": "PT",
"name": "Portugal"
}
}
6. Estruturas comuns
6.1. Erros
Alem dos casos de erro já descritos para cada endpoint, o serviço pode retornar os seguintes erros a considerar:
| Código | Descrição |
|---|---|
|
O pedido é inválido, malformado ou falhou a validação de inputs. |
|
O token de acesso está ausente, inválido ou expirado. |
|
O cliente não tem permissão para aceder ao recurso solicitado. |
|
Ocorreu um erro a nível de regras de negócio que impede o processamento do pedido. Aplicável apenas a endpoints de escrita ( |
|
Ocorreu um erro inesperado no servidor. [1] |
6.2. Dados de referência
6.2.1. Tipos de identificadores pesquisáveis
| Tipo | Descrição |
|---|---|
|
Número de conta AzorID. |
|
Número de Identificação Civil. |
|
Número de Identificação Fiscal. |
|
Código de representação atribuído pelo sistema AzorID. |
6.2.2. Tipos de conta
| Tipo | Descrição |
|---|---|
|
Conta de cidadão (pessoa singular). |
|
Conta de organização (pessoa coletiva). |
6.2.3. Tipos de estado civil
| Tipo | Descrição |
|---|---|
|
Solteiro(a). |
|
Casado(a). |
|
Viúvo(a). |
|
Divorciado(a). |
|
Separado(a) judicialmente. |
6.2.4. Tipos de endereço
| Tipo | Descrição |
|---|---|
|
Endereço preferêncial. |
|
Endereço alternativo. |
6.2.5. Papéis de representação
| Tipo | Descrição |
|---|---|
|
A conta atua como representante de outra conta. |
|
A conta é representada por outra conta. |
6.2.6. Direção do pedido de representação
| Tipo | Descrição |
|---|---|
|
A conta indicada é o representante que recebeu o pedido. |
|
A conta indicada é o representado que efetuou o pedido. |
6.2.7. Tipos de estado de pedido de representação
| Tipo | Descrição |
|---|---|
|
Pedido pendente de resposta pelo representante. |
|
Pedido aprovado pelo representante. |
|
Pedido rejeitado pelo representante. |
|
Pedido cancelado pelo representado que o efetuou. |