Download do certificado TLS
stable
Este endpoint possibilita baixar o certificado TLS emitido pelo Bankly.
O certificado TLS será gerenciado pela private CA (Certificate Authority) do Bankly e possui um tempo de vida de até 365 dias.
Importante
O parceiro terá acesso à emissão e download de, no máximo, dois certificados.
Pré-requisito
Para que seja possível utilizar este endpoint, é necessário que:
- O
legacy_access_token
tenha sido gerado previamente.
Nota
O
legacy_access_token
deve ser gerado com o scopecertificate.create
.
Requisição (Request)
Requisição HTTP
POST https://api.sandbox.bankly.com.br/partners/{{companyKey}}/certificates
--request POST \
--url 'https://api.sandbox.bankly.com.br/partners/{companyKey}/certificates' \
--header 'api-version: 1' \
--header 'Authorization: Bearer {legacy_access_token}' \
--header 'Content-Type: application/json' \
--data-raw '{
"passphrase": "{strong_passphrase}",
"ttlInDays": 365
}'
Cabeçalhos (Headers)
Nome | Descrição |
---|---|
api-version | Obrigatório. Versão da API. Atualmente estamos na versão 1.0. |
Authorization | Obrigatório. Token de autorização do tipo Bearer. |
Content-Type | Obrigatório. Indica o tipo de dado que o arquivo contém. Nesse caso, application/json . |
Parâmetros da rota (Path)
No path desta requisição envie o seguinte campo:
Nome | Tipo | Descrição |
---|---|---|
companyKey | path | Obrigatório. Identificador que discrimina a operação do parceiro dentro do Bankly. A companyKey funciona como um tenant, que nos auxilia a segregar as contas vinculadas a um parceiro. |
Dica
Caso você não conheça sua
companyKey
, entre em contato com o time de Implantação.
Corpo da requisição (Body)
No body, envie os seguintes campos em formato JSON:
Nome | Tipo | Descrição | Especificação |
---|---|---|---|
passphrase | string | Obrigatório. Senha forte de 64 caracteres. | A senha deve conter: letras maiúsculas, minúsculas, números e alguns dos seguintes caracteres especiais: !@#$%&*( )? Exemplo: cx@123aacx@123aacx@123aacx@123aacx@123aacx@123aacx@123aacx@123aa |
ttlInDays | number | Número de dias para a expiração do certificado. Caso o valor não seja informado, será assumido o valor padrão 365. | O número deve ser de 1 a 365. |
{
"passphrase": "{{strong_passphrase}}",
"ttlInDays": 365
}
Resposta (Response)
O status code 200 indicará que o certificado mTLS foi baixado com sucesso.
Sendo bem-sucedido, o retorno irá trazer os seguintes campos em formato JSON:
Nome | Tipo | Descrição |
---|---|---|
subjectDn | string | Descreve os atributos de um objeto DN que devem estar presentes no certificado de assinatura para que ela seja aceitável. |
certificate | string | Certificado TLS. Importante: o parceiro deverá transformar todos os "\n" em quebras de linha e salvar o valor do certificado em qualquer formato, como .txt, por exemplo. |
certificateChain | string | Este campo pode ser desconsiderado, pois não será utilizado nos próximos endpoints. |
privateKey | string | Chave privada atrelada ao certificado, que fica disponível uma única vez. Importante: o parceiro deverá transformar todos os "\n" em quebras de linha e salvar o valor da chave privada em qualquer formato, como .txt, por exemplo. |
passphrase | string | Senha criada pelo parceiro que foi enviada nesta requisição. |
uuid | string | Identificador gerado na emissão, em formato UUID v4. |
issuedAt | string | Data e hora de emissão do certificado, no formato ISO 8601 - UTC. |
status | string | Situação da emissão e dowloand do certificado. No caso desse endpoint, o status será sempre ACTIVE. |
createdAt | string | Data e hora do envio da requisição, no formato ISO 8601 - UTC. |
updatedAt | string | Data e hora da atualização da requisição, no formato ISO 8601 - UTC. |
{
"subjectDn": "serialNumber = {{ cnpj }}, businessCategory = {{ OPEN_API | FULL_BANK }}, UID = {{ Partner_UUID }}, C = BR, O = {{ Razão Social }}, ST = {{ state }}, L = {{ city }}, OU = {{ company_key }}, CN = {{ service_domain_name }}",
"certificate": "-----BEGIN CERTIFICATE-----\nMIIGJzC...FlxkTQ8uA==\n-----END CERTIFICATE-----",
"certificateChain": "-----BEGIN CERTIFICATE-----\nMIIEtz...2mRVNRYKb\n-----END CERTIFICATE-----",
"privateKey": "-----BEGIN ENCRYPTED PRIVATE KEY-----\nMIIJQwI...8AfD+dQjc=\n-----END PRIVATE KEY-----\n",
"passphrase": "cX@123aacx@123aacx@123aacx@123aacx@123aacx@123aacx@123aacx@123aa",
"uuid": "UUID v4",
"issuedAt": "2022-03-16T13:28:11.229549Z",
"status": "ACTIVE",
"createdAt": "2022-03-16T13:28:13.3213872Z",
"updatedAt": "2022-03-16T13:28:13.3213873Z"
}
Dica
Para simular uma requisição nesse endpoint, acesse o API Reference.
Por se tratar de dados altamente sensíveis, nós disponibilizaremos somente dois certificados para cada parceiro, sendo fundamental que eles sejam armazenados em local seguro, como um key vault (cofre de chaves), por exemplo.
Atenção
A chave privada (
privateKey
) atrelada ao certificado retornado só fica disponível uma única vez. Ou seja, em caso de nova requisição, esse campo não será retornado.
É preciso inserir o certificado, a privateKey
e o passphrase
em todas as requisições após o processo de emissão do certificado.
Se você estiver utilizando o Postman ou o Insomnia, poderá consultar os seguintes materiais que ajudarão nesse processo:
- Postman: working with certificates;
- Insomnia: client certificates.
Erros
Este endpoint pode retornar erros específicos, conforme a tabela a seguir:
Status Code | Código | Mensagem | Descrição |
---|---|---|---|
403 | CLIENT_CERTIFICATE_WAS_REVOKED | Client certificate was revoked. | O certificado do client foi revogado. Entre em contato com o Bankly. |
403 | CLIENT_CERTIFICATE_NOT_PRESENTED | Client certificate not presented or called route has no mtls policy. | Tentativa de acesso ao recurso sem apresentar o certificado mTLS, necessário para autenticação. |
403 | CLIENT_CERTIFICATE_IS_UNKNOWN | Client certificate is unknown. | O certificado do client apresentado durante uma tentativa de conexão não é reconhecido ou não é válido para autenticação. |
403 | CLIENT_CERTIFICATE_IS_INVALID | Client certificate is invalid. | O certificado do client fornecido durante a tentativa de conexão não atende aos critérios de validade ou integridade exigidos para realizar a autenticação. |
403 | CLIENT_CERTIFICATE_ID_IS_UNKNOWN | Client certificate subject DN doesn't have a defined organization unit name (OU) as partner identification. | O identificador associado ao certificado do client apresentado durante a tentativa de conexão não é reconhecido ou não corresponde a um ID válido para autenticação. |
403 | CLIENT_CERTIFICATE_HAS_EXPIRED | Client certificate has expired. | O certificado do client expirou. O parceiro deverá emitir um novo certificado. |
403 | CLIENT_AUTHENTICATION_IS_REQUIRED | tls client authentication is required. | A autenticação do client é obrigatória para acessar o recurso solicitado. |
422 | PARTNER_NOT_FOUND | Partner with company key {companyKey} not found. | O parceiro não foi encontrado. |
422 | PARTNER_HAS_REACHED_MAX_CERTIFICATES | Partner {companyKey} has reached the max number of certificates: {maxCertificates}. | Esse parceiro já emitiu o número máximo de certificados permitido (dois). |
500 | CLIENT_AUTHENTICATION_FAILURE | Unknown tls client authentication failure. | Ocorreu um erro desconhecido referente à autenticação tls de client. |
500 | CLIENT_NETWORK_FAILURE | Unknown client network failure. | Erro interno durante a validação de IP. |
Recordamos que esta API também poderá retornar erros comuns entre todos os endpoints. Portanto, recomendamos a consulta da documentação de erros, onde é possível encontrar as mensagens comuns em inglês que acompanham os erros 400 (se houver).
Eventos
Este endpoint não possui eventos relacionados a ele.
Updated about 2 months ago