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 scope certificate.create.

Requisição

Requisição HTTP

HTTP

POST https://api.sandbox.bankly.com.br/partners/{{companyKey}}/certificates

cURL

--location
--request POST '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 Projetos via Slack.

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.

JSON

{
    "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.

JSON

{
  "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.

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.