Cartões

A API de cartões é uma solução completa para a gestão de cartões, integrando a API Portadores no processo inicial e utilizando os endpoints da API Cards para todas as etapas subsequentes.

Figura 1. Fluxo de cartões

1. Iniciar Processo na API Portadores

Para iniciar a jornada, o emissor deve cadastrar o portador utilizando a API Portadores. Este cadastro inclui informações essenciais como CPF, nome, e detalhes do produto associado.

Endpoint Principal:

Criar o portador e associar um cartão ao CPF.

2. Gerenciamento do Cartão via API Cards

Após o cadastro, todas as operações relacionadas ao cartão são realizadas através da API Cards, garantindo uma gestão completa e integrada.

Endpoints Principais:

Alterar a senha do cartão.

Gerar um novo cartão virtual associado ao titular.

Bloqueia temporariamente o cartão.

Desbloqueia o cartão previamente bloqueado.

Enviar confirmações e notificações ao portador através de SMS.

Serviços Disponíveis

Expanda a seção a seguir para uma breve descrição de cada endpoint disponível na API Cards.

Cartões

Tipo	Endpoint	Descrição
`POST`	`/api/v1/cartoes/segunda-via`	Solicitar segunda via cartão.
`POST`	`/api/v1/cartoes/{idCartao}/troca/confirmacao`	Trocar cartão pendente
`GET`	`/api/v1/cartoes/{idCartao}/criptografia`	Buscar cartão criptografado
`GET`	`/api/v1/cartoes/{idCartao}/cancelamentos/historico`	Listar histórico de cancelamento
`GET`	`/api/v1/cartoes/bandeirados/cancelamentos/tipos`	Listar tipos de cancelamento
`POST`	`/api/v1/cartoes/virtuais`	Gerar um cartão virtual
`GET`	`/api/v1/cartoes/virtuais/{idCartao}`	Listar cartão virtual
`GET`	`/api/v1/cartoes/{idCartao}`	Buscar cartão pelo id
`GET`	`/api/v1/cartoes/numero`	Buscar cartão pelo número
`GET`	`/api/v1/cartoes/cpf/{cpf}`	Buscar cartão pelo CPF
`GET`	`/api/v1/cartoes/bandeirados`	Buscar cartão bandeirado
`GET`	`/api/v1/cartoes/token/merci`	Token Merci
`PATCH`	`/api/v1/cartoes/troca`	Trocar cartão do portador
`GET`	`/api/v1/cartoes/cartao-adicional-pj`	Cadastrar Pessoa Jurídica
`GET`	`/api/v1/cartoes/solicitacao-troca`	Solicitar troca de um cartão
`GET`	`/api/v1/cartoes/bin`	Listar BIN

Portadores

Tipo	Endpoint	Descrição
`GET`	`/api/v1/cartoes/titular`	Buscar cartão pelo titular
`POST`	`/api/v1/cartoes/portador-adicional`	Cadastrar portador adicional
`GET`	`/api/v1/cartoes/portador-adicional/{idPortadorAdicional}/cartoes`	Listar cartões do adicional
`POST`	`/api/v1/cartoes/portador-adicional/{idPortadorAdicional}/cartoes`	Gerar cartão adicional

Senha

Tipo	Endpoint	Descrição
`POST`	`/api/v1/cartoes/{idCartao}/senha`	Cadastrar senha
`PUT`	`/api/v1/cartoes/{idCartao}/senha`	Alterar senha
`POST`	`/api/v1/cartoes/{idCartao}/senha/autenticacao`	Autenticar senha do cartão
`PATCH`	`/api/v1/cartoes/{idCartao}/senhas/sms`	Gerar senha e enviar por SMS

CVV Virtual

Tipo	Endpoint	Descrição
`POST`	`/api/v1/cartoes/virtuais/{idCartao}/cvv`	Ativar CVV Virtual do titular
`PATCH`	`/api/v1/cartoes/virtuais/{idCartao}/cvv/invativacao`	Inativar CVV Virtual
`PATCH`	`/api/v1/cartoes/virtuais/{idCartao}/cvv/ativacao`	Atualizar data de expiração do CVV

Bloqueios e desbloqueios

Tipo	Endpoint	Descrição
`PATCH`	`/api/v1/cartoes/{idCartao}/bloqueio/temporario`	Bloquear temporariamente
`PATCH`	`/api/v1/cartoes/{idCartao}/bloqueio/permanente`	Bloquear permanentemente
`GET`	`/api/v1/cartoes/{idCartao}/bloqueio/historico`	Listar histórico de bloqueios
`GET`	`/api/v1/cartoes/bloqueios/tipos`	Listar tipos de bloqueio
`PATCH`	`/api/v1/cartoes/{idCartao}/desbloqueio`	Desbloquear cartão

No Name

Tipo	Endpoint	Descrição
`GET`	`/api/v1/cartoes/no-name/lotes`	Listar lotes de cartão
`POST`	`/api/v1/cartoes/no-name/lotes`	Criar lote de cartões
`PATCH`	`/api/v1/cartoes/no-name/{idCartao}`	Destruir cartão
`PATCH`	`/api/v1/cartoes/no-name/{idCartao}/vincula-titular`	Vincular cartão ao titular
`PATCH`	`/api/v1/cartoes/no-name/{idCartao}/vincula-adicional`	Vincular cartão adicional
`PATCH`	`/api/v1/cartoes/no-name/lotes/{id}`	Destruir lote de cartões
`PATCH`	`/api/v1/cartoes/no-name/lotes/{id}/embossing`	Embossar cartões por lote
`GET`	`/api/v1/cartoes/no-name`	Listar cartões

Casos de Uso

A seguir, detalhamos os principais casos de uso na Jornada de Cartões, explicando como cada operação é realizada através das APIs disponíveis.

Gerando segunda via

Para emitir uma segunda via do cartão, utilize o endpoint. Este processo é essencial em casos de perda ou dano do cartão original.

Exemplo de request body :

{
 "idCartao": 1792618,
  "idTipoBloqueioCartao": 5
}'

Exemplo de response:

{
  "idCartaoCancelado": 3,
  "idTipoBloqueioCartao": 24,
  "idNovoCartao": 1792891
}

Buscando cartão pelo ID

Para buscar um cartão pelo id, utilize esse endpoint. Esse processo é essencial para buscar cartão pelo seu identificador.

Exemplo Path parameter:

 "idCartao": 1792618

Exemplo Query Parameters :

 "idProduto": 2001

Exemplo de response:

{
  "id": 2001,
  "idPortadorCredito": 2001,
  "idPortadorDebito": 2001,
  "cpf": "11111111111",
  "funcaoCartao": "CREDITO",
  "virtual": true,
  "nome": "PORTADOR INVENTADO FICTICIO",
  "statusEmbossing": "AGUARDANDO EMBOSSING",
  "status": "ATIVO",
  "dataValidade": "2028-03-15",
  "idAdicional": 1,
  "numeroMascarado": "9999XXXXXXXX9999",
  "telefone": {
    "area": "99",
    "telefone": "999999999"
  },
  "dataEmissao": "2024-03-15",
  "tipoCartao": "P",
  "permiteImpressao": true,
  "possuiSenha": true
}

Buscando cartão pelo CPF

Use este endpoint para buscar as informações de um cartão pelo titular.

Exemplo de Path Parameters:

"cpf": "96921196020"

Exemplo de response:

 {
  "id": 2001,
  "bandeira": "teste",
  "idPortadorCredito": 2001,
  "idPortadorDebito": 2001,
  "cpf": "11111111111",
  "funcaoCartao": "CREDITO",
  "virtual": false,
  "nomePortadorCartao": "Nome Ficticio",
  "statusEmbossing": "EMBOSSADO",
  "statusCartao": "CARTAO_VALIDO",
  "dataExpiracao": "2028-03-24T00:00:00.000+0000",
  "idAdicional": 2002,
  "panMascarado": "9999XXXXXXXX9999",
  "bloqueioCartao": {
    "dataBloqueio": "2024-02-29T13:08:59.442+0000",
    "observacao": "Bloqueado",
    "tipoBloqueio": {
      "chave": "1",
      "descricao": "Bloqueado",
      "id": 1
    }
  },
  "cancelamentoCartao": {
    "dataCancelamento": "2024-02-29T13:08:59.442+0000",
    "observacao": "CANCELADO",
    "tipoCancelamento": {
      "chave": "CANCELAMENTO_TESTE",
      "descricao": "CANCELADO",
      "id": 1
    },
    "id": 2001,
    "idCartaoCancelado": 2001
  },
  "telefone": {
    "area": "99",
    "telefone": "999999999"
  },
  "dataEmissao": "2023-03-24T09:45:06.000+0000",
  "codigoExterno": "teste1234ca=1"
}

Buscando cartão pelo número

Use este endpoint para listar informações do cartão a partir o seu número criptografado.

Exemplo de header :

"numero": "TNGpbCi8e1JQB1l3keNjeDHz3B0m18P9pvmIspOzwTY"

Exemplo de response:

{
  "idCartao": 16,
  "numeroCartaoFormatado": "6392 0000 0000 0016",
  "nomeLojaCadastro": "REDE NUMERO 19 LTDA",
  "enderecoResponse": {
    "uf": "PB",
    "cidade": "JOAO PESSOA",
    "complemento": "COMPLEMENTO DO END",
    "numero": "16",
    "logradouro": "NOME DA RUA. END NUM 16",
    "bairro": "NOME DO BAIRRO. END NUM 16",
    "cep": "58000000"
  },
  "dataEmissao": "2015-03-17T00:00:00.000Z",
  "idLojaCadastro": 19,
  "descricaoProduto": "PRODUTO PADRAO 1",
  "tipoProprietarioCartao": "T",
  "siglaRedeCredenciada": "SGL",
  "cpfCliente": "34409592955",
  "trilha": "6392000000000016=6392000000000016",
  "idProduto": 1,
  "idCliente": 13040,
  "dataValidade": "2020-03-31T00:00:00.000Z",
  "nomeImpresso": "CARTAO DA CONTA 13040",
  "dataCadastroCliente": "2012-12-18T00:00:00.000Z"
}

Buscando cartão pelo titular

Use este endpoint para buscar as informações de um cartão pelo titular.

Exemplo de *Query Parameters :

idClienteTitular: 1

Exemplo de response:

  [
  {
    "id": 123456,
    "bandeira": "ELO",
    "idPortadorCredito": 123456,
    "idPortadorDebito": 1234,
    "cpf": "12345678900",
    "funcaoCartao": "CREDITO",
    "virtual": false,
    "nome": "BILBO BAGGINS",
    "statusEmbossing": "EMBOSSADO",
    "status": "ATIVO",
    "dataValidade": "2028-03-15",
    "idAdicional": 1234,
    "numeroMascarado": "123456XXXXXX1234",
    "bloqueioCartao": {
      "dataBloqueio": "2024-02-29T13:08:59.442+0000",
      "observacao": "Bloqueado",
      "tipoBloqueio": {
        "id": 8,
        "descricao": "Bloqueado",
        "chave": "BLOQUEIO_SENHA_INVALIDA"
      }
    },
    "cancelamentoCartao": {
      "dataCancelamento": "2024-02-29T13:08:59.442+0000",
      "observacao": "CANCELADO",
      "tipoCancelamento": {
        "id": 9,
        "descricao": "CANCELADO",
        "chave": "CANCELAMENTO_PERDA"
      },
      "idCartaoCancelado": 1234,
      "id": 1234
    },
    "telefone": {
      "area": "83",
      "telefone": "999999999"
    },
    "dataEmissao": "2023-03-15",
    "tipoCartao": "P",
    "possuiSenha": true,
    "codigoExterno": "c68a761a-e46a-4375-b7fe-2fb0aabd3a18",
    "permiteImpressao": true
  }
]

Listando tipos de bloqueio

Use este endpoint para listar os tipos de bloqueios para os cartões.

Exemplo de response:

[
  {
    "cancelaCartao": false,
    "sistema": "N",
    "geraNovoCartao": "N",
    "permiteAlterarLimite": "N",
    "resumo": "BLOQUEADO",
    "isentarTaxaSegundaViaCartao": "S",
    "permitirDesbloqueioCartaoLoja": "N",
    "id": 15,
    "permitirBloqueioCartaoLoja": "N",
    "permitirDesbloqueioModAtend": "N",
    "descricao": "BLOQUEADO"
  },
  {
    "cancelaCartao": true,
    "sistema": "S",
    "geraNovoCartao": "N",
    "permiteAlterarLimite": "N",
    "resumo": "Bloqueia o TAC quando passar sua validade.",
    "isentarTaxaSegundaViaCartao": "S",
    "permitirDesbloqueioCartaoLoja": "N",
    "id": -6,
    "permitirBloqueioCartaoLoja": "N",
    "permitirDesbloqueioModAtend": "N",
    "descricao": "BLOQUEIO DE VENCIMENTO DE TAC"
  }
]