> 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 Edição Enterprise do SCEPman Aplicável à versão 3.1 e superior {% endhint %} A Management API 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 endpoints estão disponíveis em `/api/manage` e requerem um utilizador autenticado com a **Manage.All** função no SCEPman-api. {% hint style="info" %} Se você atualizar a partir de uma versão anterior do SCEPman, talvez ainda não tenha a função Manage.All. Execute `Complete-SCEPmanInstallation` novamente em um shell de nuvem para adicioná-la automaticamente à sua aplicação SCEPman-api. {% endhint %} ### Autenticação A API usa autenticação Entra. Muitas vezes, a forma mais fácil de autenticar é a Microsoft Authentication Library (MSAL). Uma forma de obter um token bearer para a Management API é com o Azure CLI. O valor necessário para o parâmetro \`--resource\` é o URI do ID da aplicação do seu registo de aplicação SCEPman-api (normalmente o seu 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 usar esse token nas chamadas da 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 certificados emitidos e devolve um conjunto de resultados paginado. #### Parâmetros de pesquisa **`searchText`** Termo de pesquisa em texto livre usado para encontrar certificados correspondentes. Isto é normalmente usado para pesquisas baseadas em subcadeias, por exemplo, correspondendo ao requisitante ou a outros metadados de certificado pesquisáveis. **`pageSize`** Número máximo de certificados devolvidos numa única página de resposta. * Padrão: 50 **`continuationToken`** Token de paginação opcional usado para solicitar a página seguinte de resultados.\ Passe de volta o `continuationToken` devolvido por uma resposta de pesquisa anterior para continuar a obter mais certificados. **`certValidity`** Filtra certificados pelo estado de validade. * Padrão: `Any` Os valores válidos são `Any`, `Active`, `Expirado`, `Revoked`. **`certType`** Filtra certificados por tipo de certificado. * Padrão: `Any` Isto pode ser usado para restringir o conjunto de resultados a categorias específicas de certificados. Os valores válidos são `Static`, `DC`, `Usuário`, `Dispositivo`, e `Any`. **`Sources`** Filtra certificados pelo endpoint através do qual foram emitidos. Pode especificar este filtro várias vezes, uma por fonte. * Padrão: Sem restrição Os valores válidos são mostrados na tabela abaixo; deve especificar a fonte usando os seus valores inteiros: | Fonte | Valor | | ----------------- | ------------------------------------------------ | | CertificateMaster | 0 | | Intune | 1 ou 9 (use ambos para garantir encontrar todos) | | Static | 3 | | StaticAAD | 4 | | Jamf | 5 | | DomainController | 6 | | API | 7 | | RadiusAPI | 8 | | Active Directory | 10 | A resposta é uma lista paginada de registos de certificados mais um token de continuação para obter a página seguinte. **Exemplo** ```bash curl -X GET "https://scepman.contoso.com/api/manage/search?searchText=507AEAC03CCEF83F106914418D9222E466A629C1&pageSize=10&certValidity=Any&certType=Any" \ -H "Authorization: Bearer " \ -H "Accept: application/json" ``` **Exemplo de resposta** ```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": "..." } ``` ### **API de revogação** **`PATCH /api/manage/revoke/{serialNumber}`** Revoga um certificado identificado pelo seu número de série. O corpo do pedido contém: * `revocationReason` - um inteiro para o motivo da revogação. Veja a tabela abaixo para possíveis valores * `revoker` *(opcional)* - um identificador em texto livre para a pessoa ou sistema que solicita a revogação {% hint style="info" %} Se especificado, recomendamos usar o UPN para o campo revoker. Se não for especificado, será usado o UPN do utilizador com sessão iniciada. Mesmo que seja especificado, o UPN do utilizador com sessão iniciada continua a ser adicionado na forma "{revoker} por meio do utilizador da API ${logged on user}". Este valor é usado para auditoria e em pesquisas. {% endhint %} **Exemplo** ```bash curl -X PATCH "https://scepman.contoso.com/api/manage/revoke/ABC123" \ -H "Authorization: Bearer " \ -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": "Certificado não encontrado.", "errorCode": 7012 } ``` **Já revogado** ```http HTTP/1.1 409 Conflict Content-Type: application/json ``` ```json { "errorMessage": "O certificado já está revogado.", "errorCode": 5013 } ``` #### Motivos de revogação suportados A API suporta os motivos de revogação especificados em [RFC 5280](https://datatracker.ietf.org/doc/html/rfc5280#section-5.3.1): | Valor | Motivo de revogação | | ----- | ----------------------- | | 0 | Não especificado | | 1 | Compromisso da chave | | 2 | Compromisso da AC | | 3 | Mudança de afiliação | | 4 | Substituído | | 5 | Cessação da operação | | 6 | Retenção do certificado | | 8 | Remover do CRL | | 9 | Retirada do privilégio | | 10 | Compromisso 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 dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.scepman.com/pt/gestao-de-certificados/management-rest-api.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.