Pular para o conteúdo principal
Version: 4.42

Referência da API — Gerenciamento de certificados

Visão geral​

Os certificados são o recurso central do Redtrust. Esta documentação descreve os métodos mais relevantes para quem precisa gerenciar o ciclo de vida dos certificados por meio da API: associar usuários a certificados, atualizar suas propriedades, alterar seu status, excluí-los e consultá-los.

Antes de começar​

Antes de testar esses métodos, você precisa configurar o SoapUI.

important

Os comentários <!--Optional:--> exibidos nas solicitações SOAP são gerados automaticamente e podem marcar incorretamente campos obrigatórios como opcionais.

Esta documentação indica explicitamente quais campos são obrigatórios ou opcionais. Sempre confie nesta documentação.

Associar um usuário a um certificado​

AddCertificateUser​

Cria um usuário do tipo certificado em um domínio. Esse tipo de usuário se autentica no Redtrust por meio de um certificado digital em vez de nome de usuário e senha.

NomeTipoObrigatórioDescrição
domainIdintegerSimID do domínio onde o usuário será criado. Localize o valor em ListDomains.
usernamestringSimNome de usuário. Aceita letras (A-Z, a-z), números (0-9) e os caracteres -, _ e . como separadores.
namestringSimNome completo do usuário.
emailstringSimEndereço de e-mail do usuário. Deve estar em um formato válido.
activebooleanSimIndica se a conta está ativa (true) ou desativada (false).
issuerIdsarray de inteirosNão*IDs dos certificados CA locais que devem aparecer na cadeia de certificação do certificado do usuário. Localize os valores em ListCACertificates usando certType=LOCAL_CA_ROOT.
certDirectiveIdsarray de inteirosNão*IDs das diretivas de certificado que o certificado do usuário deve cumprir. Localize os valores em ListCertificateDirectives.
certAttributesarray de CertificateAttributeDataNão*Atributos de certificado que o certificado do usuário deve ter. Cada elemento inclui: id (tipo de atributo, de ListCertificateAttributes), name (nome do atributo, de ListCertificateAttributes), type (operador de comparação: EXISTS, IS_EQUAL, NOT_EXISTS, NOT_EQUALS, CONTAINS) e value (o valor a comparar; não obrigatório para EXISTS e NOT_EXISTS).

(*) Você deve fornecer pelo menos um desses três campos. Se os três forem omitidos, o servidor retorna um erro.

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:urn="urn:evolium:redtrust:administration:ws" xmlns:arr="http://schemas.microsoft.com/2003/10/Serialization/Arrays" xmlns:rtad="http://schemas.datacontract.org/2004/07/RTAdminService.Types">
    <soap:Header/>
    <soap:Body>
        <urn:AddCertificateUser>
            <urn:domainId>2</urn:domainId>
            <urn:username>ana.garcia</urn:username>
            <urn:name>Ana García</urn:name>
            <urn:email>ana.garcia@example.com</urn:email>
            <urn:active>true</urn:active>
            <urn:issuerIds>
                <arr:int>5</arr:int>
            </urn:issuerIds>
            <urn:certDirectiveIds>
                <arr:int>1</arr:int>
            </urn:certDirectiveIds>
            <urn:certAttributes/>
        </urn:AddCertificateUser>
    </soap:Body>
</soap:Envelope>

EditCertificateUser​

Atualiza um usuário do tipo certificado existente em um domínio. Os campos do tipo array (issuerIds, certDirectiveIds, certAttributes) substituem os valores atuais por completo; omitir um deles o remove.

NomeTipoObrigatórioDescrição
domainIdintegerSimID do domínio onde o usuário existe. Localize o valor em ListDomains.
userIdintegerSimID do usuário de certificado que você deseja atualizar. É o valor retornado em ResultData por AddCertificateUser.
namestringSimNome completo do usuário.
emailstringSimEndereço de e-mail do usuário. Deve estar em um formato válido.
activebooleanSimIndica se a conta está ativa (true) ou desativada (false).
issuerIdsarray de inteirosNão*IDs dos certificados CA locais que devem aparecer na cadeia de certificação do certificado do usuário. Localize os valores em ListCACertificates usando certType=LOCAL_CA_ROOT.
certDirectiveIdsarray de inteirosNão*IDs das diretivas de certificado que o certificado do usuário deve cumprir. Localize os valores em ListCertificateDirectives.
certAttributesarray de CertificateAttributeDataNão*Atributos de certificado que o certificado do usuário deve ter. Mesma estrutura que em AddCertificateUser.

(*) Você deve fornecer pelo menos um desses três campos. Se os três forem omitidos, o servidor retorna um erro.

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:urn="urn:evolium:redtrust:administration:ws" xmlns:arr="http://schemas.microsoft.com/2003/10/Serialization/Arrays">
    <soap:Header/>
    <soap:Body>
        <urn:EditCertificateUser>
            <urn:domainId>2</urn:domainId>
            <urn:userId>42</urn:userId>
            <urn:name>Ana García</urn:name>
            <urn:email>ana.garcia@example.com</urn:email>
            <urn:active>true</urn:active>
            <urn:issuerIds>
                <arr:int>5</arr:int>
            </urn:issuerIds>
            <urn:certDirectiveIds>
                <arr:int>1</arr:int>
            </urn:certDirectiveIds>
            <urn:certAttributes/>
        </urn:EditCertificateUser>
    </soap:Body>
</soap:Envelope>

Atualizar um certificado​

EditCertificate​

Atualiza as propriedades locais de um certificado. A maioria dos campos são operações de escrita: o valor enviado substitui o valor atual, por isso você deve enviar o estado completo desejado em cada solicitação, não apenas os campos que deseja alterar. As exceções estão descritas na tabela.

NomeTipoObrigatórioDescrição
certIdintegerSimID do certificado que você deseja atualizar. Localize o valor no campo certificateHandler retornado por ListCertificates.
aliasstringNãoNome descritivo do certificado visível no console. Se você enviar um valor vazio, o alias atual será removido.
commentstringNãoComentário livre sobre o certificado. Se você enviar um valor vazio, o comentário atual será removido.
requirePinbooleanSimIndica se o certificado requer PIN para ser usado. Envie false para remover o PIN atual.
pinstringNãoNovo PIN do certificado. Envie vazio ou nulo para manter o PIN atual. Envie este parâmetro apenas quando quiser alterá-lo.
requireUsageReasonbooleanSimIndica se o certificado requer que o usuário informe um motivo de uso.
activebooleanSimIndica se o certificado está ativo (true) ou desativado (false).
ownerUIDstringNãoUID do proprietário do certificado. Envie uma string vazia para remover o proprietário atual. Envie nulo para manter o proprietário atual.
userPinPolicyCertificateUserPinPolicySimPolítica de PIN do usuário: NO_USER_PIN, ASK_USER_PIN, FORCE_ASK_USER_PIN.
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:urn="urn:evolium:redtrust:administration:ws">
    <soap:Header/>
    <soap:Body>
        <urn:EditCertificate>
            <urn:certId>14</urn:certId>
            <urn:alias>Certificado de assinatura - Contabilidade</urn:alias>
            <urn:comment>Renovado em março de 2026</urn:comment>
            <urn:requirePin>false</urn:requirePin>
            <urn:pin></urn:pin>
            <urn:requireUsageReason>false</urn:requireUsageReason>
            <urn:active>true</urn:active>
            <urn:ownerUID></urn:ownerUID>
            <urn:userPinPolicy>NO_USER_PIN</urn:userPinPolicy>
        </urn:EditCertificate>
    </soap:Body>
</soap:Envelope>

Redefinir o PIN de um certificado​

ResetPin​

Redefine o PIN de um certificado e envia um e-mail ao proprietário para que escolha um novo.

NomeTipoObrigatórioDescrição
certIdintegerSimID do certificado. Localize o valor no campo certificateHandler retornado por ListCertificates.
emailstringSimEndereço de e-mail do proprietário do certificado. A notificação de redefinição é enviada para este endereço.
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:urn="urn:evolium:redtrust:administration:ws">
    <soap:Header/>
    <soap:Body>
        <urn:ResetPin>
            <urn:certId>14</urn:certId>
            <urn:email>ana.garcia@example.com</urn:email>
        </urn:ResetPin>
    </soap:Body>
</soap:Envelope>

Ativar ou desativar certificados​

ChangeCertificatesStatus​

Altera o status ativo ou inativo de um ou mais certificados simultaneamente.

NomeTipoObrigatórioDescrição
certIdsarray de inteirosSimIDs dos certificados que você deseja atualizar. Localize os valores no campo certificateHandler retornado por ListCertificates. Você pode enviar vários IDs conforme mostrado no exemplo.
statusbooleanSimStatus a aplicar: ativo (true) ou inativo (false).
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:urn="urn:evolium:redtrust:administration:ws" xmlns:arr="http://schemas.microsoft.com/2003/10/Serialization/Arrays">
    <soap:Header/>
    <soap:Body>
        <urn:ChangeCertificatesStatus>
            <urn:certIds>
                <!--Zero or more repetitions:-->
                <arr:int>243</arr:int>
                <arr:int>244</arr:int>
            </urn:certIds>
            <urn:status>true</urn:status>
        </urn:ChangeCertificatesStatus>
    </soap:Body>
</soap:Envelope>

Excluir certificados​

DeleteCertificate​

Exclui permanentemente um ou mais certificados do sistema.

NomeTipoObrigatórioDescrição
certIdsarray de inteirosSimIDs dos certificados que você deseja excluir. Localize os valores no campo certificateHandler retornado por ListCertificates. Você pode enviar vários IDs conforme mostrado no exemplo.
certTypeCertificateTypeSimTipo dos certificados que você deseja excluir. Todos os IDs em certIds devem pertencer ao mesmo tipo. Valores: CA_ROOT, PRIVATE, PUBLIC_KEY_EMAIL, LOCAL_CA_ROOT, PRELOADED.
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:urn="urn:evolium:redtrust:administration:ws" xmlns:arr="http://schemas.microsoft.com/2003/10/Serialization/Arrays">
    <soap:Header/>
    <soap:Body>
        <urn:DeleteCertificate>
            <urn:certIds>
                <!--Zero or more repetitions:-->
                <arr:int>14</arr:int>
                <arr:int>15</arr:int>
            </urn:certIds>
            <urn:certType>PRIVATE</urn:certType>
        </urn:DeleteCertificate>
    </soap:Body>
</soap:Envelope>

Recuperar informações de certificados​

ListCertificates​

Retorna uma lista paginada de certificados com seus dados principais.

NomeTipoObrigatórioDescrição
viewTypeCertificatesViewTypeSimFiltra os certificados por status. Valores: ViewAll, ViewExpired, ViewNotExpired, ViewWithOwner, ViewWithoutOwner, ViewActive, ViewInactive, ViewAssignable, ViewNoAssignable, ViewRenewal.
filterstringSimTexto que os resultados devem conter. Se estiver vazio, retorna todos.
numBlockintegerSimNúmero do bloco de resultados a retornar. Começa em 0.
orderColumnOrderCertificatesColumnSimColuna usada para ordenar os resultados: ORDER_BY_NAME, ORDER_BY_ACTIVE, ORDER_BY_EXPIRATION_DATE, ORDER_BY_TOTAL_USES, ORDER_BY_DATETIME_LAST_USAGE.
orderTypeOrderTypeSimDireção da ordenação: ORDER_ASCENDING ou ORDER_DESCENDING.

Os resultados são retornados em blocos de 1000 itens. Use numBlock (começando em 0) para paginar pelos resultados. Divida TotalItems da resposta por 1000 e arredonde para cima para obter o número total de blocos.

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:urn="urn:evolium:redtrust:administration:ws">
    <soap:Header/>
    <soap:Body>
        <urn:ListCertificates>
            <urn:viewType>ViewAll</urn:viewType>
            <urn:filter></urn:filter>
            <urn:numBlock>0</urn:numBlock>
            <urn:orderColumn>ORDER_BY_EXPIRATION_DATE</urn:orderColumn>
            <urn:orderType>ORDER_DESCENDING</urn:orderType>
        </urn:ListCertificates>
    </soap:Body>
</soap:Envelope>

GetCertificateData​

Retorna os dados detalhados de um certificado específico.

NomeTipoObrigatórioDescrição
certIdintegerSimID do certificado. Localize o valor no campo certificateHandler retornado por ListCertificates.
certTypeCertificateTypeSimTipo do certificado. Valores: CA_ROOT, PRIVATE, PUBLIC_KEY_EMAIL, LOCAL_CA_ROOT, PRELOADED.
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:urn="urn:evolium:redtrust:administration:ws">
    <soap:Header/>
    <soap:Body>
        <urn:GetCertificateData>
            <urn:certId>14</urn:certId>
            <urn:certType>PRIVATE</urn:certType>
        </urn:GetCertificateData>
    </soap:Body>
</soap:Envelope>

ListCACertificates​

Retorna a lista de certificados CA de um tipo específico. Use este método para obter os IDs válidos para o parâmetro issuerIds em AddCertificateUser.

NomeTipoObrigatórioDescrição
certTypeCertificateTypeSimTipo de certificados CA a listar. Valores válidos: CA_ROOT, LOCAL_CA_ROOT, PUBLIC_KEY_EMAIL.
filterstringNãoTexto que os resultados devem conter. Se estiver vazio, retorna todos.
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:urn="urn:evolium:redtrust:administration:ws">
    <soap:Header/>
    <soap:Body>
        <urn:ListCACertificates>
            <urn:certType>LOCAL_CA_ROOT</urn:certType>
            <urn:filter></urn:filter>
        </urn:ListCACertificates>
    </soap:Body>
</soap:Envelope>

ListCertificateAttributes​

Retorna a lista de tipos de atributos de certificado disponíveis no sistema. Use este método para obter os valores válidos de id para o parâmetro certAttributes em AddCertificateUser.

NomeTipoObrigatórioDescrição
filterstringNãoTexto que os resultados devem conter. Se estiver vazio ou omitido, retorna todos os atributos.
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:urn="urn:evolium:redtrust:administration:ws">
    <soap:Header/>
    <soap:Body>
        <urn:ListCertificateAttributes>
            <urn:filter></urn:filter>
        </urn:ListCertificateAttributes>
    </soap:Body>
</soap:Envelope>

Diretivas de certificado​

AddCertificateDirective​

Cria uma nova diretiva de certificado. Use este método para adicionar diretivas que podem ser atribuídas a usuários de certificado por meio do parâmetro certDirectiveIds em AddCertificateUser.

NomeTipoObrigatórioDescrição
directivestringSimNome da diretiva que você deseja criar.
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:urn="urn:evolium:redtrust:administration:ws">
    <soap:Header/>
    <soap:Body>
        <urn:AddCertificateDirective>
            <urn:directive>Diretiva de exemplo</urn:directive>
        </urn:AddCertificateDirective>
    </soap:Body>
</soap:Envelope>

ListCertificateDirectives​

Retorna a lista de diretivas de certificado configuradas no sistema. Use este método para obter os IDs válidos para o parâmetro certDirectiveIds em AddCertificateUser.

NomeTipoObrigatórioDescrição
filterstringNãoTexto que os resultados devem conter. Se estiver vazio ou omitido, retorna todas as diretivas.
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:urn="urn:evolium:redtrust:administration:ws">
    <soap:Header/>
    <soap:Body>
        <urn:ListCertificateDirectives>
            <urn:filter></urn:filter>
        </urn:ListCertificateDirectives>
    </soap:Body>
</soap:Envelope>