> For the complete documentation index, see [llms.txt](https://docs.scepman.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.scepman.com/pt/gestao-de-certificados/management-rest-api.md).

# API REST de gestão

{% hint style="warning" %}
Apenas na SCEPman Enterprise Edition

Aplicável à versão 3.1 e posteriores
{% endhint %}

A API de Gestão fornece acesso administrativo aos certificados emitidos no SCEPman. Destina-se a fluxos de trabalho de gestão e operacionais, como localizar certificados e revogá-los quando necessário.

Estes pontos de acesso estão disponíveis em `/api/manage` e requerem um utilizador autenticado com a função **Manage.All** em SCEPman-api.

{% hint style="info" %}
Se atualizar a partir de uma versão anterior do SCEPman, poderá ainda não ter a função Manage.All. Execute `Complete-SCEPmanInstallation` novamente numa Cloud Shell para a adicionar automaticamente à sua aplicação SCEPman-api.
{% endhint %}

## Autenticação

A API utiliza a autenticação Entra. Muitas vezes, a forma mais simples de autenticar é através da Microsoft Authentication Library (MSAL).

Uma forma de obter um token bearer para a API de Gestão é através da CLI do Azure. O valor necessário para o parâmetro \`--resource\` é o URI do ID da aplicação do registo de aplicações SCEPman-api (normalmente, o ID da aplicação precedido de `api://`).

```bash
az account get-access-token --resource api://[APPLICATION-ID] --query accessToken --output tsv
```

Por exemplo:

```bash
TOKEN=$(az account get-access-token \
  --resource api://16b6a4d1-0a20-4b41-bf58-12783034cad3 \
  --query accessToken \
  --output tsv)
```

Pode então utilizar esse token nas chamadas à API:

```bash
curl -X GET "https://scepman.contoso.com/api/manage/search?searchText=ABC123&pageSize=10&certValidity=Any&certType=Any" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"
```

## API de Pesquisa

**`GET /api/manage/search`**

Pesquisa os certificados emitidos e devolve um conjunto de resultados paginado.

### Parâmetros de pesquisa

**`searchText`**

Termo de pesquisa em texto livre utilizado para encontrar certificados correspondentes. Normalmente, é utilizado para pesquisas por correspondência parcial, por exemplo, para encontrar o requerente ou outros metadados pesquisáveis do certificado.

**`pageSize`**

Número máximo de certificados devolvidos numa única página de resposta.

* Predefinição: 50

**`continuationToken`**

Token de paginação opcional utilizado para pedir a página seguinte de resultados.\
Devolva o `continuationToken` recebido numa resposta de pesquisa anterior para continuar a obter mais certificados.

**`certValidity`**

Filtra os certificados pelo estado de validade.

* Predefinição: `Any`

Os valores válidos são `Any`, `Active`, `Expired`, `Revoked`.

**`certType`**

Filtra os certificados pelo tipo de certificado.

* Predefinição: `Any`

Pode ser utilizado para restringir o conjunto de resultados a categorias específicas de certificados. Os valores válidos são `Static`, `DC`, `User`, `Device`, e `Any`.

**`Sources`**

Filtra os certificados pelo ponto final através do qual foram emitidos. Pode especificar este filtro várias vezes, uma vez por origem.

* Predefinição: sem restrições

Os valores válidos são apresentados na tabela abaixo. Tem de especificar a origem através do respetivo valor inteiro:

| Origem            | Valor                                                   |
| ----------------- | ------------------------------------------------------- |
| CertificateMaster | 0                                                       |
| Intune            | 1 ou 9 (utilize ambos para garantir que encontra todos) |
| Static            | 3                                                       |
| StaticAAD         | 4                                                       |
| Jamf              | 5                                                       |
| DomainController  | 6                                                       |
| API               | 7                                                       |
| RadiusAPI         | 8                                                       |
| Active Directory  | 10                                                      |

### **Exemplo**

```bash
curl -X GET "https://scepman.contoso.com/api/manage/search?searchText=507AEAC03CCEF83F106914418D9222E466A629C1&pageSize=10&certValidity=Any&certType=Any" \
  -H "Authorization: Bearer <token>" \
  -H "Accept: application/json"
```

#### **Resposta de exemplo**

```json
{
  "items": [
    {
    "serialNumber":  "507AEAC03CCEF83F106914418D9222E466A629C1",
    "subject":  "CN=device01.contoso.local",
    "sans":  null,
    "upn":  null,
    "issuanceDate":  "2026-05-28T10:57:22Z",
    "expirationDate":  "2028-05-28T10:57:22Z",
    "revocationDate":  null,
    "revocationReason":  null,
    "revokedBy":  null,
    "requester":  "pkiAdmin@contoso.com",
    "source":  "CertificateMaster",
    "certificateType":  "Static"
    }
  ],
  "continuationToken": "...",
  "fullTextSearch": false
}
```

### **Campos da resposta**

**`items`**

Os certificados da página atual.

**`continuationToken`**

Um token opaco para obter a página seguinte. É `null` quando se chega à última página.

{% hint style="info" %}
Trate o token de continuação como opaco e devolva-o sem alterações. Não o modifique, não o guarde durante longos períodos e não o reutilize com parâmetros de pesquisa diferentes — um token só é válido para a consulta exata que o gerou.
{% endhint %}

**`fullTextSearch`**

Indica que tipo de correspondência de texto produziu este resultado.

* `true` — `searchText` foi encontrado **em qualquer parte** dos campos pesquisados (pesquisa de texto integral).
* `false` — `searchText` foi encontrado apenas no **início** dos campos pesquisados (pesquisa por prefixo).

O campo também está presente quando não é fornecido nenhum `searchText` ; nesse caso, é `false` &#x20;

{% hint style="info" %}
`fullTextSearch` está disponível a partir do SCEPman 3.2. O SCEPman 3.1 não o inclui e realiza sempre uma pesquisa por prefixo.
{% endhint %}

### Comportamento da pesquisa

#### **Pesquisa de texto integral vs. pesquisa por prefixo**

O SCEPman escolhe automaticamente a estratégia de pesquisa, e essa seleção pode mudar em futuras versões do SCEPman, especialmente com base no número de certificados no seu ambiente.

* Para `"fullTextSearch": true`, o SCEPman utiliza uma correspondência de **subcadeia** sem distinção entre maiúsculas e minúsculas nos campos de número de série, assunto, SANs, UPN, solicitante, revogador e tipo de certificado.
* Para  `"fullTextSearch": false`, a pesquisa encontra correspondências apenas no **início** de um campo. Os campos pesquisados são o número de série, UPN, solicitante, revogador e assunto. A pesquisa no assunto inclui tanto o assunto bruto como o RDN do Common Name. Por exemplo, uma pesquisa por `device01` encontraria um certificado com o assunto `CN=device01`.

{% hint style="warning" %}
Como os clientes da API não podem controlar a estratégia específica utilizada, não deve confiar na utilização de uma estratégia específica e deve conseguir lidar com ambos os volumes de certificados.&#x20;
{% endhint %}

### Resposta de erro

#### **Token de continuação inválido**

```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
```

```json
{
  "errorMessage": "The continuation token is invalid. Please repeat the search without a continuation token.",
  "errorCode": 4014
}
```

O erro com errorCode 4014 ocorre quando não é possível interpretar um token de continuação. Repita a pesquisa a partir da primeira página, sem um token de continuação.

## **API de revogação**

**`PATCH /api/manage/revoke/{serialNumber}`**

Revoga um certificado identificado pelo respetivo número de série.

O corpo do pedido contém:

* `revocationReason` - um número inteiro que indica o motivo da revogação. Consulte a tabela abaixo para ver os valores possíveis
* `revoker` *(opcional)* - um identificador de texto livre da pessoa ou do sistema que solicita a revogação

{% hint style="info" %}
Se especificado, recomendamos utilizar o UPN para o campo do responsável pela revogação. Caso contrário, será utilizado o UPN do utilizador com sessão iniciada. Mesmo que seja especificado, o UPN do utilizador com sessão iniciada continua a ser adicionado no formulário "{revoker} através do utilizador da API ${logged on user}".

Este valor é utilizado para auditoria e em pesquisas.
{% endhint %}

### **Exemplo**

```bash
curl -X PATCH "https://scepman.contoso.com/api/manage/revoke/ABC123" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "revocationReason": 4,
    "revoker": "pkiAdmin@contoso.com"
  }'
```

#### **Resposta bem-sucedida**

```http
HTTP/1.1 200 OK
```

#### **Certificado não encontrado**

```http
HTTP/1.1 404 Not Found
Content-Type: application/json
```

```json
{
  "errorMessage": "Certificate not found.",
  "errorCode": 7012
}
```

#### **Já revogado**

```http
HTTP/1.1 409 Conflict
Content-Type: application/json
```

```json
{
  "errorMessage": "The certificate is already revoked.",
  "errorCode": 5013
}
```

### Motivos de revogação suportados

A API suporta os motivos de revogação especificados na [RFC 5280](https://datatracker.ietf.org/doc/html/rfc5280#section-5.3.1):

| Valor | Motivo da revogação       |
| ----- | ------------------------- |
| 0     | Não especificado          |
| 1     | Comprometimento da chave  |
| 2     | Comprometimento da AC     |
| 3     | Afiliação alterada        |
| 4     | Substituído               |
| 5     | Cessação de funcionamento |
| 6     | Certificado suspenso      |
| 8     | Remover da CRL            |
| 9     | Privilégios retirados     |
| 10    | Comprometimento da AA     |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.scepman.com/pt/gestao-de-certificados/management-rest-api.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
