Certificados

Algumas fontes de consulta do Plexi requerem a utilização de certificados digitais, e para utilizar seus próprios certificados através do Plexi você precisará cadastra-los.

URL Base:

https://api.plexi.com.br/

Informações essenciais

O CNPJ passado no endpoint /api/organizations/:cnpj/certificates refere-se ao CNPJ do cliente PLEXI, que está solicitando a operação. É importante garantir que o CNPJ informado corresponda ao cliente autorizado, pois ele será utilizado para validações internas de segurança e permissão.

Cadastrar certificados

Endpoint: POST /api/organizations/:cnpj/certificates

É possível cadastrar um certificado digital enviando seu conteúdo em formato pfx codificado em base64 juntamente com a senha.

{
    "name": "certificado-1",
    "metadata": "Qualquer informação extra que possa ajudar na identificação do certificado",
    "certificate": {
        "pfx": "base64 encoded",
        "password": "123"
     }
}

Também é possível enviar diretamente o conteúdo do certificado junto com sua chave privada, já descriptografada, ambos codificados em base64

{
    "name": "certificado-1",
    "metadata": "Qualquer informação extra que possa ajudar na identificação do certificado",
    "certificate": {
        "cert": "base64 encoded",
        "key": "base64 encoded"
     }
}

O campo name é um controle interno da organização para identificar a qual certificado ele se refere.

Atualizar certificado

Endpoint: PUT /api/organizations/:cnpj/certificates/:uuid

Para atualizar um certificado basta enviar os dados do certificado como na endpoint de criação, sem o campo name no corpo.

{
    "metadata": "Qualquer informação extra que possa ajudar na identificação do certificado",
    "certificate": {
        "cert": "base64 encoded",
        "key": "base64 encoded"
     }
}

ou

{
    "metadata": "Qualquer informação extra que possa ajudar na identificação do certificado",
    "certificate": {
        "pfx": "base64 encoded",
        "password": "123"
    }
}

Listar certificados

Endpoint: GET /api/organizations/:cnpj/certificates

Exemplo de retorno:

[
    {
        "id": "d9a8e33f-3a36-4758-81aa-c6afa7e347da",
        "name": "certificado-cliente-1",
        "metadata": "Qualquer informação extra que possa ajudar na identificação do certificado",
        "certificate" : {
           "common_name": "FULANO DE TAL 1234567890",
           "fingerprint": "VXRpbC9IdG1sSnNvbkZpbmRlci5waHAK",
           "due_date": "2024-01-01 00:00:00"
        }
     },
    {
        "id": "7c1f9b2e-5a83-4d16-b0e9-2c6a4f81773d",
        "name": "certificado-cliente-1",
        "metadata": "Qualquer informação extra que possa ajudar na identificação do certificado",
        "certificate" : {
           "common_name": "FULANO DE TAL 1234567890",
           "fingerprint": "VXRpbC9IdG1sSnNvbkZpbmRlci5waHAK",
           "due_date": "2024-01-01 00:00:00"
        }
     },
]

Os certificados no Plexi tem 3 status: active, deleted e expired. Por padrão a listagem de certificados lista apenas os certificados active, mas é possível mudar este comportamento adicionando o parâmetro statusdesta forma: GET /api/organizations/:cnpj/certificates?status=status

Detalhes do certificado

Endpoint: GET /api/organizations/:cnpj/certificates/:uuid

Exemplo de retorno:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "certificado-cliente-1",
  "metadata": "Qualquer informação extra que possa ajudar na identificação do certificado",
  "certificate" : {
    "common_name": "FULANO DE TAL 1234567890",
    "fingerprint": "VXRpbC9IdG1sSnNvbkZpbmRlci5waHAK",
    "due_date": "2024-01-01 00:00:00"
  }
}

Deletar certificado

Endpoint: DELETE /api/organizations/:cnpj/certificates/:uuid

Como utilizar o certificado em uma consulta

As fontes de consulta que exigem certificado digital recebem o certificado no campo certificate, no corpo (JSON) da requisição. O valor deve ser o UUID do certificado cadastrado. Exemplo:

{
  "certificate": "550e8400-e29b-41d4-a716-446655440000",
  "cpfCnpj": "99999999999"
}