Cartões Virtuais

Permite gerar cartões virtuais dinamicamente e exibir no aplicativo/portal mobileX. Só permite a configuração de um cartão por endpoint. Para gerar e visualizar os cartões você deve:

• Criar uma funcionalidade no adapter para obter os dados da carteira no cliente

  • O adapter foi construído de forma que o template do JSON de retorno deve ter o seguinte formato { "pageContent": <dados> }, onde <dados> são os dados que precisam ser exibidos no cartão virtual.

• Criar uma configuração de aparência de carteira para o endpoint

  • Isso deve ser feito via POSTMAN.

    • Método: POST

    • URL: <api-url>/api/manager/canvas/cardconfig

    • Header contendo o AppCompanyId

    • JSON no seguinte formato:

{
  "screenTitle": "Cartão do convênio",
  "rotate": false,
  "navigationBackgroundColor": "#FF0000",
  "navigationTextColor": "#FFFFFF",
  "cardConfigurations": [
    {
      "cardImageUrl": "https://cartaobeneficiar.com.br/fundo-capa-site.png",
      "titles": [
        {
          "title": "{{{nome_titular}}}",
          "allowsAbbreviation": true,
          "fontSize": 40,
          "position": {
            "x": 53,
            "y": 193,
            "width": 1000
          },
          "color": "#ff0000"
        },
        ...
      ],
      "images": [
        {
          "url": "https://cartaobeneficiar.com.br/logo.png",
          "rect": {
            "x": 762,
            "y": 29,
            "width": 300,
            "height": 140
          }
        },
        ...
      ]
    },
    ...
  ]
}

• screenTitle: Título da tela que será exibido no mobile/portal.

• rotate: Se deve rotacionar a imagem em 90 graus para a direita.

• navigationBackgroundColor: Define a cor de fundo da barra de navegação. Omitir esta propriedade ou passar null faz com que a cor padrão do endpoint seja utilizada.

• navigationTextColor: Define a cor do texto da barra de navegação. Omitir esta propriedade ou passar null faz com que a cor padrão do endpoint seja utilizada.

• cardConfiguration: Lista de configurações de cartões. Cada item desse array representa uma imagem de cartão.

  • cardImageUrl: Url da imagem de fundo do cartão

  • titles: Lista de textos para serem plotados no cartão

    1. title: Título que vai ser plotado no cartão

       • title: Título que vai ser plotado no cartão

         1. O título pode ser um texto fixo ou um mapeamento para alguma propriedade do <dados> retornado pela funcionalidade do adapter.

         2. O mapeamento é feito usando tags mustache. Ou seja, caso a funcionalidade do adapter retorne um JSON com a propriedade card_number, você pode mapear essa propriedade no title usando a tag mustache como conteúdo da propriedade da seguinte forma: {{#card_number}}{{{card_number}}}{{/card_number}}

       • allowsAbbreviation: Se permite que, caso o title seja muito grande, o texto seja abreviado, exibindo a primeira letra de cada palavra seguida de ponto. OBS: A primeira e última palavra não são abreviadas.

       • fontSize: Tamanho da fonte do title.

       • color: Cor do texto

       • position: Posição em que o texto vai ficar.

         1. x: Posição x do texto

         2. y: Posição y do texto

         3. width: Largura máxima do texto.

  • images: Lista de imagens para serem plotadas no cartão

    1. url: URL da imagem a ser plotada no cartão

    2. rect: Posição, largura e altura da imagem.

Configurando a action

Uma vez configurada a aparência do cartão você precisa configurar a integração que retornará os dados a serem exibidos no mesmo.

Para isso a action deve ser configurada da seguinte forma:

{
  "path": "MS_CANVAS", 
  "name": "open-view",
  "parameters": [
    {
      "title": "querystring",
      "value": "?path=<id-mapeamento>&<parametros-adicionais>"
    }
  ],
  "permissionLevel": 2,
  "publishLevel": 1,
  "order": 0,
  "icon": ""
}

Onde:

• path: Deve ser sempre MS_CANVAS, pois é desta forma que o backend identifica que precisa ser gerado um cartão.

• name: Deve ser sempre open-view, pois o cartão é retornado como um HTML.

• parameters: Deve conter pelo menos um item com title = querystring e value contendo um parâmetro path, que contém o id do mapeamento que retorna os dados a serem exibidos no cartão.

Formato dos dados retornados na integração

O JSON retornado pela integração configurada na action deve ter o seguinte formato:

"pageContent": {
  "screenActions": [
    {
      "icon": "EAAE",
      "name": "save-in-wallet",
      "order": 0,
      "parameters": [
        {
          "title": "querystring",
          "value": "?path=wallet"
        }
      ],
      "path": "MS_PASS",
      "permissionLevel": 2,
      "publishLevel": 1
    }
  ],
  "mtmCardModels": [
    {
      "cardVersion": "1",
      "name": "Rinaldo Silva",
      "numCartao": "4564 8795 1235",
      "data_val": "20/09/2025"
    }
  ]
}

• pageContent.screenActions: Lista de actions que podem ser exibidar no lado direito da barra de navegação da tela que exibe o cartão virtual.

• mtmCardModels: Lista de dados a serem exibidos no cartão virtual. Cada item da lista deve conter um cardVersion.

  • cardVersion: Id do cartão existentes nas configurações de aparência do Cartão Virtual.

  • Todos os outros parâmetros são chaves e valores para os mapeamentos do mustache nas configurações de aparência do Cartão Virtual.

Para acessar o cartão no frontend é obrigatório que o usuário esteja autenticado no app mobile/portal.