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 Authorization dos pedidos HTTP para autenticação

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

Diagram

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

id

string (guid)

Identificador único da conta no sistema AzorID.

4.1.2. Estados de resposta

Código Descrição

200 OK

A conta foi encontrada e os seus dados são retornados no corpo da resposta.

404 Not Found

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

accountType

string

Tipo de conta, de acordo com Tipos de conta.

id

string (guid)

Identificador único da conta no sistema AzorID.

displayName

string

Nome de apresentação da conta.

registration

string (date)

Data de registo da conta em formato ISO 8601.

isAccountCertified

boolean

Indica se a identidade associada à conta está certificada.

Conta de cidadão (accountType = Citizen)

Além dos campos comuns:

Campo Tipo Descrição

name

string?

Nome completo do cidadão, caso disponível e certificado.

accountNumber

string?

Número de conta AzorID.

citizenCardNumber

string?

Número do Cartão de Cidadão, caso disponível e certificado.

citizenCardExpirationDate

string? (date)

Data de expiração do Cartão de Cidadão em formato ISO 8601, caso disponível e certificado.

fiscalNumber

string?

Número de Identificação Fiscal (NIF), caso disponível e certificado.

patientNumber

string?

Número Nacional de Utente, caso disponível e certificado.

passportNumber

string?

Número do Passaporte, caso disponível e certificado.

socialSecurityNumber

string?

Número de Identificação da Segurança Social (NISS), caso disponível e certificado.

passportExpirationDate

string? (date)

Data de expiração do Passaporte em formato ISO 8601, caso disponível e certificado.

maritalStatus

string?

Estado civil, de acordo com Tipos de estado civil, caso disponível e certificado.

addresses

array (Address[])

Lista de endereços associados ao cidadão, caso disponíveis e certificados.

contacts

array (Contact[])

Lista de contactos ativos associados ao cidadão, caso disponíveis e certificados.

birthDate

string? (date)

Data de nascimento em formato ISO 8601, caso disponível e certificada.

nationality

Nationality?

Nacionalidade do cidadão, caso disponível e certificada.

Conta de organização (accountType = Organization)

Além dos campos comuns:

Campo Tipo Descrição

socialDesignation

string?

Designação social da organização.

accountNumber

string?

Número de conta AzorID.

fiscalNumber

string?

Número de Identificação de Pessoa Coletiva (NIPC).

Address
Campo Tipo Descrição

districtCode

string

Código do distrito.

districtName

string

Nome do distrito.

countyCode

string

Código do concelho.

countyName

string

Nome do concelho.

localityCode

string

Código da localidade no domínio CTT, ou vazio se não disponível.

localityName

string

Nome da localidade.

postalCode

string

Código postal.

postalCodeExtension

string

Extensão do código postal.

postalCodeDesignation

string

Designação postal.

streetCode

string?

Código da rua/via/estrada no domínio CTT, se disponível.

streetName

string?

Nome da rua/via/estrada.

address

string?

Representação textual da via.

unitNumber

string

Designação adicional do endereço, como número da porta, andar, etc.

displayLines

array (string)

Conjunto de linhas que representam a morada em formato de texto, de acordo com as normas CTT.

nature

string

Tipo do endereço de acordo com Tipos de endereço.

Contact
Campo Tipo Descrição

nature

string

Tipo de contacto (e.g. Email, PhoneNumber).

value

string

Valor do contacto.

countryCallingCode

string?

Código de chamada internacional, aplicável a contactos telefónicos (e.g. +351).

isPrimary

boolean

Indica se este é o contacto principal.

Nationality
Campo Tipo Descrição

code

string

Código da nacionalidade - ISO 3166-1 alpha-2.

name

string

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

fiscalNumber

string

Número de Identificação Fiscal (NIF) ou de Pessoa Coletiva (NIPC) — 9 dígitos.

citizenCard

string

Número de Identificação Civil — 8 dígitos.

emailAddress

string

Endereço de correio eletrónico de um contacto ativo do cidadão.

accountNumber

string

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

200 OK

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

id

string (guid)

Identificador único da conta no sistema AzorID.

4.3.2. Parâmetros opcionais do pedido (query string)

Parâmetro Tipo Descrição

role

string

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.

active

boolean

Se true (predefinição), retorna apenas representações ativas; se false, retorna todas as representações.

4.3.3. Estados de resposta

Código Descrição

200 OK

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

representations

array (Representation[])

Lista de representações.

Representation
Campo Tipo Descrição

id

string (guid)

ID da representação no sistema AzorID.

role

string

Papel da conta indicada nesta representação, de acordo com Papéis de representação.

counterpartId

string (guid)

ID da contraparte — a outra conta envolvida na representação.

counterpartDisplayName

string

Nome de apresentação da contraparte.

counterpartAccountNumber

string?

Número de conta AzorID da contraparte (cidadão ou organização).

start

string (date)

Data de início da representação em formato ISO 8601.

end

string? (date)

Data de fim da representação em formato ISO 8601, caso definida.

creation

string (date)

Data de criação da representação em formato ISO 8601.

lastUpdate

string? (date)

Data da última atualização da representação em formato ISO 8601, caso tenha sido alterada.

revocation

string? (date)

Data de revogação da representação em formato ISO 8601, caso tenha sido revogada.

isActive

boolean

Indica se a representação está atualmente em vigor.

service

RepresentationService

O serviço abrangido pela representação.

RepresentationService
Campo Tipo Descrição

id

string (guid)

ID do serviço no sistema AzorID.

code

string

Código do serviço.

name

string

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

id

string (guid)

Identificador único da conta no sistema AzorID.

representationId

string (guid)

ID da representação no sistema AzorID.

4.4.2. Estados de resposta

Código Descrição

200 OK

A representação foi encontrada e é retornada no corpo da resposta.

404 Not Found

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

id

string (guid)

Identificador único da conta representada no sistema AzorID.

4.5.2. Estrutura do corpo do pedido

Campo Tipo Descrição

representativeAccountId

string? (guid)

ID da conta do cidadão representante. Obrigatório se representativeCode não for definido.

representativeCode

string?

Código de representação do cidadão representante. Obrigatório se representativeAccountId não for definido.

start

string (date)

Data de início da representação em formato ISO 8601.

end

string? (date)

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.

serviceCodes

array (string)

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

200 OK

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

representationIdsByServiceCode

object

Mapa das representações criadas, em que cada chave é o código do serviço e o respetivo valor é o ID (string (guid)) da representação criada para esse serviço.

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

id

string (guid)

Identificador único da conta no sistema AzorID.

representationId

string (guid)

ID da representação a revogar.

4.6.2. Estados de resposta

Código Descrição

200 OK

A representação foi revogada com sucesso.

404 Not Found

A representação não existe ou a conta indicada não é parte da mesma.

409 Conflict

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

id

string (guid)

Identificador único da conta representada no sistema AzorID.

4.7.2. Estrutura do corpo do pedido

Campo Tipo Descrição

representativeAccountId

string? (guid)

ID da conta do cidadão representante. Obrigatório se representativeCode não for definido.

representativeCode

string?

Código de representação do cidadão representante. Obrigatório se representativeAccountId não for definido.

start

string (date)

Data de início da representação pretendida em formato ISO 8601.

end

string (date)

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.

serviceCodes

array (string)

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

200 OK

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

requestIdsByServiceCode

object

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 (string (guid)) desse pedido. Como os serviços já cobertos por uma representação ativa ou por um pedido pendente são ignorados (ver nota acima), as chaves podem ser um subconjunto de serviceCodes; o valor é o mesmo em todas as entradas, por se tratar de um único pedido.

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

id

string (guid)

Identificador único da conta no sistema AzorID.

4.8.2. Parâmetros opcionais do pedido (query string)

Parâmetro Tipo Descrição

direction

string

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.

status

string

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

200 OK

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

requests

array (RepresentationRequest[])

Lista de pedidos de representação, ordenada do mais recente para o mais antigo.

RepresentationRequest
Campo Tipo Descrição

id

string (guid)

ID do pedido de representação no sistema AzorID.

direction

string

Direção do pedido relativamente à conta indicada, de acordo com Direção do pedido de representação.

status

string

Estado do pedido, de acordo com Tipos de estado de pedido de representação.

requesterId

string (guid)

ID da conta representada — a conta que efetuou o pedido.

requesterDisplayName

string

Nome de apresentação da conta representada.

representativeId

string (guid)

ID da conta representante — a conta que recebeu o pedido.

representativeDisplayName

string

Nome de apresentação da conta representante.

start

string (date)

Data de início da representação pretendida em formato ISO 8601.

end

string? (date)

Data de fim da representação pretendida em formato ISO 8601.

creation

string (date)

Data de criação do pedido em formato ISO 8601.

lastUpdate

string? (date)

Data da última atualização do pedido em formato ISO 8601, caso tenha sido alterado.

services

array (RepresentationService[])

Lista de serviços associados ao pedido.

RepresentationService
Campo Tipo Descrição

id

string (guid)

ID do serviço no sistema AzorID.

code

string

Código do serviço.

name

string

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

id

string (guid)

Identificador único da conta no sistema AzorID.

requestId

string (guid)

ID do pedido de representação no sistema AzorID.

4.9.2. Estados de resposta

Código Descrição

200 OK

O pedido foi encontrado e é retornado no corpo da resposta.

404 Not Found

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

id

string (guid)

Identificador único da conta representante no sistema AzorID.

requestId

string (guid)

ID do pedido de representação a aprovar.

Estados de resposta
Código Descrição

200 OK

O pedido foi aprovado e as representações foram criadas.

404 Not Found

O pedido não existe ou a conta indicada não participa no mesmo.

409 Conflict

O pedido não está no estado Pending, ou a conta indicada não é o representante do pedido.

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

id

string (guid)

Identificador único da conta representante no sistema AzorID.

requestId

string (guid)

ID do pedido de representação a rejeitar.

Estados de resposta
Código Descrição

200 OK

O pedido foi rejeitado.

404 Not Found

O pedido não existe ou a conta indicada não participa no mesmo.

409 Conflict

O pedido não está no estado Pending, ou a conta indicada não é o representante do pedido.

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

id

string (guid)

Identificador único da conta representada no sistema AzorID.

requestId

string (guid)

ID do pedido de representação a cancelar.

Estados de resposta
Código Descrição

200 OK

O pedido foi cancelado.

404 Not Found

O pedido não existe ou a conta indicada não participa no mesmo.

409 Conflict

O pedido não está no estado Pending, ou a conta indicada não é o representado que efetuou o pedido.

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

identifierType

string

Tipo de identificador do cidadão (e.g., FiscalNumber ou RepresentationCode) designado em Tipos de identificadores pesquisáveis.

identifier

string

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

string (guid)

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

200 OK

O cidadão foi encontrado e os seus dados são retornados no corpo da resposta.

404 Not Found

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

id

string (guid)

Identificador único do cidadão no sistema AzorID.

registration

string (date)

Data de registo do cidadão em formato ISO 8601.

identifiers

array (Identifier[])

Lista de identificadores pesquisáveis associados ao cidadão.

isAccountCertified

boolean

Indica se a conta do cidadão está certificada.

name

string

Nome completo do cidadão.

accountNumber

string

Número de conta AzorID.

citizenCardNumber

string?

Número do Cartão de Cidadão do cidadão, caso o mesmo esteja disponível e certificado.

citizenCardExpirationDate

string? (date)

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.

fiscalNumber

string?

Número de Identificação Fiscal (NIF) do cidadão, caso o mesmo esteja disponível e certificado.

patientNumber

string?

Número Nacional de Utente do cidadão, caso o mesmo esteja disponível e certificado.

passportNumber

string?

Número do Passaporte do cidadão, caso o mesmo esteja disponível e certificado.

passportExpirationDate

string? (date)

Data de expiração do Passaporte do cidadão em formato ISO 8601, caso o mesmo esteja disponível e certificado.

maritalStatus

string?

Estado civil do cidadão, caso o mesmo esteja disponível e certificado, de acordo com a tabela Tipos de estado civil.

addresses

array (Address[])

Lista de endereços associados ao cidadão, caso os mesmos estejam disponíveis e certificados.

contacts

array (Contact[])

Lista de contactos associados ao cidadão, caso os mesmos estejam disponíveis e certificados.

birthDate

string? (date)

Data de nascimento do cidadão em formato ISO 8601, caso a mesma esteja disponível e certificado.

nationality

Nationality?

Nacionalidade do cidadão, caso a mesma esteja disponível e certificada.

mother

CitizenRelative?

Informações relativas á mãe do cidadão, caso as mesmas estejam disponíveis e certificadas.

father

CitizenRelative?

Informações relativas ao pai do cidadão, caso as mesmas estejam disponíveis e certificadas.

Identifier
Campo Tipo Descrição

nature

string

Tipo de identificador de acordo com a tabela Tipos de identificadores pesquisáveis.

value

string

Valor do identificador.

Address
Campo Tipo Descrição

districtCode

string

Código do distrito.

districtName

string

Nome do distrito.

countyCode

string

Código do concelho.

countyName

string

Nome do concelho.

parishCode

string

Código da freguesia.

parishName

string

Nome da freguesia.

postalCode

string

Código postal.

postalExtensionCode

string

Extensão do código postal.

postalDesignation

string

Designação postal.

thoroughfareCode

string?

Código da rua/via/estrada no domínio CTT, se disponível.

thoroughfare

string

Nome da rua/via/estrada.

unit

string

Designação adicional do endereço, como número da porta, andar, etc.

displayLines

array (string)

Conjunto de linhas que representam a morada em formato de texto, de acordo com as normas CTT.

nature

string

Tipo do endereço de acordo com a tabela Tipos de endereço.

Contact
Campo Tipo Descrição

nature

string

Tipo de contacto (e.g. Phone, Email).

value

string

Valor do contacto.

countryCallingCode

string?

Código de chamada internacional, aplicável para contactos telefónicos (e.g. +351).

isPrimary

boolean

Indica se este é o contacto principal.

Nationality
Campo Tipo Descrição

code

string

Código da nacionalidade - ISO 3166-1 alpha-2.

name

string

Nome do país.

CitizenRelative
Campo Tipo Descrição

name

string

Nome completo do familiar.

fiscalNumber

string?

Número de Identificação Fiscal (NIF) do familiar, caso o mesmo esteja disponível.

citizenCardNumber

string?

Número do Cartão de Cidadão do familiar, caso o mesmo esteja disponível.

citizenCardExpirationDate

string?

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

400 Bad Request

O pedido é inválido, malformado ou falhou a validação de inputs.

401 Unauthorized

O token de acesso está ausente, inválido ou expirado.

403 Forbidden

O cliente não tem permissão para aceder ao recurso solicitado.

409 Conflict

Ocorreu um erro a nível de regras de negócio que impede o processamento do pedido. Aplicável apenas a endpoints de escrita (POST)

500 Internal Server Error

Ocorreu um erro inesperado no servidor. [1]

6.2. Dados de referência

6.2.1. Tipos de identificadores pesquisáveis

Tipo Descrição

AccountNumber

Número de conta AzorID.

CitizenCardNumber

Número de Identificação Civil.

FiscalNumber

Número de Identificação Fiscal.

RepresentationCode

Código de representação atribuído pelo sistema AzorID.

6.2.2. Tipos de conta

Tipo Descrição

Citizen

Conta de cidadão (pessoa singular).

Organization

Conta de organização (pessoa coletiva).

6.2.3. Tipos de estado civil

Tipo Descrição

Single

Solteiro(a).

Married

Casado(a).

Widowed

Viúvo(a).

Divorced

Divorciado(a).

LegallySeparated

Separado(a) judicialmente.

6.2.4. Tipos de endereço

Tipo Descrição

Default

Endereço preferêncial.

Alternative

Endereço alternativo.

6.2.5. Papéis de representação

Tipo Descrição

AsRepresentative

A conta atua como representante de outra conta.

AsRepresented

A conta é representada por outra conta.

6.2.6. Direção do pedido de representação

Tipo Descrição

Inbound

A conta indicada é o representante que recebeu o pedido.

Outbound

A conta indicada é o representado que efetuou o pedido.

6.2.7. Tipos de estado de pedido de representação

Tipo Descrição

Pending

Pedido pendente de resposta pelo representante.

Approved

Pedido aprovado pelo representante.

Rejected

Pedido rejeitado pelo representante.

Cancelled

Pedido cancelado pelo representado que o efetuou.

7. Referências


1. Em caso de erro interno do servidor (5xx), recomenda-se que o cliente tente novamente o pedido após algum tempo, e se o problema persistir, que seja notificada a equipa técnica responsável.