Emissão de cartão físico
stable pré pós
Este endpoint permite que o parceiro Bankly ofereça a seus clientes a possibilidade de adquirir um cartão físico.
Pré-requisitos
Para que seja possível utilizar este endpoint, é necessário que:
- O parceiro defina um programa para seus cartões;
- O cliente do parceiro possua uma conta ativa.
Nota
Para realizar a emissão de cartões do tipo Panless, o parceiro deve obter a certificação Digital First.
Requisição (Request)
Requisição HTTP
POST https://api-mtls.sandbox.bankly.com.br/cards/physical
--request POST \
--url 'https://api-mtls.sandbox.bankly.com.br/cards/physical' \
--header 'Authorization: Bearer {{Token}}'\
--header 'accept: application/json' \
--header 'api-version: 1' \
--header 'x-bkly-license: f64197e4-80b3-4820-bfae-1419049b15b5'\
--header 'content-type: application/json'\
--data '{
"documentNumber": "47742663023",
"cardName": "Nísia Floresta",
"alias": "Cartão principal",
"bankAgency": "0001",
"bankAccount": "15164",
"programId": "1234",
"password": "1234",
"address": {
"zipCode": "68060100",
"address": "Rua 6 de Março",
"number": "2500",
"neighborhood": "Alter do Chão",
"complement": "",
"city": "Santarém",
"state": "PA",
"country": "BR"
},
"metadata":{
"updatedAt": "2022-12-30T01:11:07.4019873Z",
"versao": "1.0"
}
}'
Autorização
Para garantir a segurança nas requisições, todos os endpoints do Bankly utilizam scopes como parte do seu fluxo de autorização.
Esta requisição requer o scope descrito a seguir:
Scope | Descrição |
---|---|
card.create | Concede acesso para emitir um novo cartão. |
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. |
x-bkly-license | Identificador da licença bancária utilizada pelo parceiro. Observação: caso esse header não seja enviado, será considerada a licença do Bankly na requisição. |
Parâmetros da rota (Path)
Não é necessário enviar parâmetros no path desta requisição.
Corpo da requisição (Body)
No body, envie os seguintes campos em formato JSON:
Nome | Tipo | Descrição | Especificação |
---|---|---|---|
documentNumber | string | Obrigatório. Número de documento de CPF ou CNPJ. | Informe somente os números. |
cardName | string | Obrigatório. Nome que será impresso no cartão. | Não é permitido o uso de números e caracteres especiais e o tamanho máximo é de 19 caracteres. |
alias | string | Obrigatório. Apelido do cartão. | Não é permitido o uso de caracteres especiais e o tamanho máximo é de 16 caracteres. |
bankAgency | string | Obrigatório. Número da agência. | — |
bankAccount | string | Obrigatório. Número da conta ao qual o cartão será vinculado. | — |
programId | string | Obrigatório. Identificador do programa previamente definido. | — |
password | string | Obrigatório. Senha do cartão. Importante: dependendo da configuração do programa, o envio deste campo pode ser opcional. Neste caso, a senha é gerada randomicamente. | Preencha com apenas 4 dígitos, como por exemplo: “4853”. |
metadata | object | Objeto que deverá conter informações adicionais pertinentes ao contexto, representadas por meio de pares de chave e valor. | — |
Nota
Para que o parceiro possa utilizar a opção de senha randômica, é necessário que seja feita uma avaliação pelo time de segurança do Bankly e que o usuário tenha acesso à senha, seja pelo kit enviado, seja pelo endpoint de consulta de senhas.
Caso o cliente não tenha informado o endereço de entrega no momento do cadastro, preencha:
Nome | Tipo | Descrição |
---|---|---|
address | object | Objeto que deverá conter informações sobre o endereço do titular do cartão ao qual deve ser realizado a entrega. |
address.zipCode | string | Obrigatório. Código postal do endereço. |
address.address | string | Obrigatório. Logradouro (nome da rua, avenida etc.). |
address.number | string | Obrigatório. Número do imóvel. |
address.neighborhood | string | Obrigatório. Nome do bairro. |
address.complement | string | Complemento do endereço. |
address.city | string | Obrigatório. Nome da cidade. |
address.state | string | Obrigatório. Nome do estado. |
address.country | string | Obrigatório. Nome do país. |
Entretanto, caso o cliente já possua um endereço cadastrado, o preenchimento do campo address
é opcional.
Atenção
Para evitar problemas na entrega devido à desatualização do endereço cadastrado, recomendamos que o campo
address
seja preenchido mesmo que o cliente já tenha informado um endereço previamente.
{
"documentNumber": "47742663023",
"cardName": "Nísia Floresta",
"alias": "Cartão principal",
"bankAgency": "0001",
"bankAccount": "15164",
"programId": "1234",
"password": "1234",
"address": {
"zipCode": "68060100",
"address": "Rua 6 de Março",
"number": "2500",
"neighborhood": "Alter do Chão",
"complement": "",
"city": "Santarém",
"state": "PA",
"country": "BR"
},
"metadata":{
"updatedAt": "2022-12-30T01:11:07.4019873Z",
"versao": "1.0"
}
}
Resposta (Response)
Os status code 202 indica que a solicitação foi aceita e o cartão está sendo criado.
Sendo bem-sucedido, o retorno irá trazer os seguintes campos em formato JSON:
Nome | Tipo | Descrição |
---|---|---|
proxy | string | Código identificador do cartão. |
activateCode | string | Código atrelado ao cartão no momento de sua emissão. |
{
"proxy": "2370021007715002820",
"activateCode": "A0DDDC0951D1"
}
Dica
Para simular uma requisição nesse endpoint, acesse o API Reference.
Erros
Este endpoint pode retornar alguns erros específicos, conforme a tabela a seguir:
Status Code | Código | Descrição |
---|---|---|
400 | 110 | O dia de pagamento não foi informado no programa. |
401 | — | Sem autorização para realizar a solicitação. |
401 | 115 | O programa não pertence ao lote. |
406 | 013 | O cartão físico necessita de um endereço para entrega. |
406 | 101 | Requisição válida, porém, não foi aceita devido a alguma regra de negócio contratada. |
406 | 102 | Nenhum programa definido para a operação. |
406 | 202 | A conta não pertence ao cliente. |
406 | 203 | Conta inativa. |
406 | DUPLICATE_CARD_NAME | Nome já cadastrado para o CPF informado. Não é possível ter dois cartões físicos ativos com o mesmo nome para o mesmo CPF. |
409 | 012 | A requisição com os dados enviados já foi realizada e está em processamento. |
409 | ANALYSIS_CREDIT_NOTFOUND | Análise de crédito não encontrada para o documento e o programa informado. |
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
Caso o parceiro deseje receber mensagens referentes aos eventos relacionados a esse endpoint, é preciso configurar o webhook. Os eventos são:
Nome do evento | Descrição |
---|---|
CARD_WAS_ISSUED | O cartão foi emitido. |
Updated about 1 month ago