Retornando Múltiplas Extensões

Imagine o seguinte cenário: você quer disponibilizar para o cidadão o PDF de uma guia e também devolver o código para pagamento de uma ou mais parcelas. Ou melhor ainda, deixar disponível que ele selecione se deseja o PDF, código para pagamento, ou ambos. Para isso, existe o atributo condicoes, que permite definir critérios para chamar uma extensão específica ou ainda a mesma extensão, mas com parâmetros diferentes.

Os resultados das extensões serão entregues individualmente, conforme forem sendo concluídas e o atendimento será encerrado quando todas as extensões forem entregues para o usuário.

Condições de Execução de Extensões

Os critérios para as condições de execução servem para todos os tipos de dados. Por exemplo: é possível ter um critério que verifica se uma variável do tipo data é maior igual a uma outra data. A imagem abaixo é mais intuitiva sobre a estrutura e funcionamento de uma condição.

Imagem N: Exemplo de Condição, uma ou mais extensões

variaveis: [
    // ...
    [
        nome: 'formatoRetorno',
        rotulo: 'Como você quer receber suas guias',
        tipo: 'lista',
        opcoes: [
            [ valor: 'pdf', texto: 'Boleto em PDF' ],
            [ valor: 'codigoBarras', texto: 'Código da parcela' ],
            [ valor: 'ambos', texto: 'Quero receber o PDF e o código das parcelas' ]
        ]
    ]
],
encerrar: [
  [
    condicoes: [
      [
        variavel: 'formatoRetorno', criterio: '=', valor: ['pdf', 'ambos']
      ]
    ],
    tipo: 'relatorio',
    identificador: '1ad00fab-085d-40e4-8edb-57b05824e854', // ... Demais atributos abaixo omitidos
  ],
  [
    condicoes: [
      [
        variavel: 'formatoRetorno', criterio: '=', valor: ['codigoBarras', 'ambos']
      ]
    ],
    tipo: 'script',
    identificador: '5c7eb1fc-7246-4235-aa32-4d58230a2788', // ... Demais atributos abaixo omitidos
  ]
]

Tabela N: Mapa Condição

Atributo	Tipo	Descrição
variavel	String	Variável a ser comparada com de acordo com o critério e valor.
criterio	String (Veja tabela “Critério para Condicionais”)	Lógica de comparação para que a condição seja verdadeira.
valor	String ou Lista de Strings	Lista de possíveis valores para que a condição seja verdadeira.

Tabela N: Critério para Condicionais

Critério	Descrição
= ou igual	Se a variável é igual o valor
!= ou diferente	Se a variável é diferente do valor
< ou menor	Se a variável é menor que o valor
> ou maior	Se a variável é maior que o valor
<= ou menor_igual	Se a variável é menor ou igual ao o valor
>= ou maior_igual	Se a variável é maior ou igual ao o valor

Caso exista mais uma condição, o operador lógico entre elas é E (AND), o exemplo abaixo, ambas as condições devem ser verdadeiras para que a extensão seja solicitada:

Imagem N: Exemplo de Condição, uma ou mais extensões

// ... Declaração de variáveis omitidas
encerrar: [
  [
    condicoes: [
      [
        variavel: 'formatoRetorno', criterio: '=', valor: ['pdf', 'ambos'],
        variavel: 'anoIPTU', criterio: '<', valor: ['2017'], // Supondo que exista um layout de relatório (uma extensão diferente) para alguns anos.
      ]
    ],
    tipo: 'relatorio',
    identificador: '1ad00fab-085d-40e4-8edb-57b05824e854', // ... Demais atributos abaixo omitidos
  ]
]

Ainda sobre o exemplo anterior, o comparador consegue inferir automaticamente o tipo da variável para processar a condição. Por exemplo: se a variável ano IPTU for do tipo inteiro ou valor/moeda, o critério funcionará mesmo que seja criada uma condição com o valor seja colocado como ‘2017’ ou 2017.

Suspendendo o Atendimento

Como visto na especificação simplificada, é possível encerrar a qualquer momento o atendimento de acordo com alguma condição. Porém, é normal que a condição de encerramento esteja dentro de uma variável. Por exemplo, supondo que exista uma lista de seleção de imóvel, onde: Opção 1 é o imóvel X, Opção 2 é o imóvel Y, Opção 3 é uma opção que diz que o usuário não pode prosseguir, por exemplo “3 - Não encontrei o imóvel que estava procurando”.

O atributo suspender, no retorno da crítica, permite que seja avaliada uma ou mais condições em relação a uma variável específica, para que o atendimento seja interrompido, sem prosseguir com a chamada de extensões. Perceba que o atributo suspender possui uma lista de condições. A estrutura de dados é a mesma que as condições de execução de uma extensão (critérios e valores).

Atributo Suspender

return [
...
variaveis: ...,
suspender: [
    condicoes: [
      [
        variavel: 'idImovel',
        criterio: '=',
        valor: 'nao_encontrei',
        mensagem: 'Desculpe, mas estes são os imóveis que temos cadastrados em seu nome. Entre em contato com o setor imobiliário da Prefeitura para que possamos verificar se existe alguma pendência.'
      ]
    ]
],
encerrar: ...
...

Outro exemplo de uso seria: Imagine que existe um valor máximo de renda para que o cidadão solicite um determinado serviço, como isenção de imposto. É possível colocar uma restrição com critério de > (maior) na variável correspondente a renda que o usuário informou. Ou ainda, imagine que essa renda está cadastrada é consultada via fonte de dados. É possível salvar o valor como uma variável fixa da crítica e depois utilizá-la nas condições de encerramento.

Utilizando um Script para Responder o Atendimento

A integração com uma extensão do tipo Script é semelhante a uma integração com relatórios. A diferença está no formato de retorno que o script deve obrigatoriamente fornecer. Uma extensão do tipo script possui como retorno um arquivo ZIP. Logo, para que a Beth possa processar o conteúdo e entregar para o usuário, o script deve escrever um ou mais arquivos de texto (.txt) com o conteúdo da mensagem de retorno para o usuário.

Por exemplo: supondo que o script retorne um código de barras de uma parcela. O script deve escrever ao menos um arquivo txt com o conteúdo.

• Arquivo obrigatório:

  • padrao.txt => Arquivo obrigatório que contém o retorno utilizado para todos os canais

• Retornos opcionais, podendo ser definidos por canal, criando um arquivo específico, por exemplo:

  • whatsapp.txt => Retorno para o WhatsApp
  • webchat.txt => Retorno para o site beth.chat
  • site.txt => Retorno para o site da prefeitura / componentes do webchat

Algumas restrições:

O tamanho máximo do zip com os retornos para o canal não pode exceder 10 Kb.

Retornando um PDF

É possível responder um atendimento retornando um PDF junto com a mensagem ou como anexo. Este tipo de retorno permite integração com sistemas de terceiros, ou até mesmo com relatórios que não foram construídos dentro da Plataforma Betha. Também é possível disponibilizar relatórios e documentos estáticos do próprio município, por exemplo.

Para disponibilizar um PDF no atendimento, só é necessário definir o tipo e URL, podendo ter outros detalhes customizados conforme a necessidade.

return [
    mensagem: 'Estou solicitando sua cartilha, só um momentinho...',
    encerrar: [
      [
          tipo: 'pdf',
          url: 'https://www.epagri.sc.gov.br/wp-content/uploads/2020/04/coronavirus-cartilha.pdf'
      ]
    ]
]

Note que o tipo de retorno é semelhante as integrações com script e relatórios. Também é possível definir mensagens específicas para o caso de sucesso e erro, assim como utilizar mais de um documento no retorno. É possível utilizar uma ou mais extensões em conjunto com um ou mais PDFs fixos para responder um atendimento.

É possível especificar de forma detalhada como ocorrerá a integração, como por exemplo na necessidade de definir algum cabeçalho ou até mesmo o verbo HTTP que deve ser utilizado.

return [
    mensagem: 'Estou solicitando sua cartilha, só um momentinho...',
    encerrar: [
      [
          tipo: 'pdf',
          url: 'https://www.epagri.sc.gov.br/wp-content/uploads/2020/04/coronavirus-cartilha.pdf',
          headers: [
        'header-customizado': 'valor-header',
    'outro-header': ['valor1', 'valor2'],
      'valor-dinamico': Variavel.token_api_externa
    ],
    verbo: 'get'
      ]
]

Algumas restrições:

• O tamanho máximo do PDF pode variar de acordo com o canal de atendimento. No caso do WhatsApp, quando o tamanho do anexo exceder o tamanho máximo, a Beth irá entregar ao usuário um link para download do PDF;
• Somente são permitidas integrações utilizando HTTPS;
• As integrações HTTP devem obedecer os seguintes critérios:
  • Responder em até 2 minutos;
  • Estabelecer uma conexão dentro de até 2 minutos;
  • Possuir certificado HTTPs válido;

Abaixo, a tabela especifica detalhadamente as propriedades que podem ser informadas especificamente para o tipo de integração que retorna um PDF. Demais atributos que já estão presentes na tabela “Tipo Encerrar” foram omitidos para simplificar o texto.

Tabela N: Tipo de Retorno PDF (Atributos Já presente no Tipo Encerrar foram omitidos)

Atributo	Tipo	Descrição
url	String	URL HTTPS com o endereço que possui o PDF ou irá gerar um tipo de mídia do tipo PDF ao ser invocado.
verbo	String	Verbo HTTP que será utilizado ao realizar a chamada para API. Padrão: GET - Tipos suportados: GET, POST, PUT, DELETE
headers	Mapa chave e valor	Mapa dos headers a serem propagados ao invocar a URL especificada. São suportados headers multivalores.

API’s disponíveis

Quase todas as API’s de Script estão disponíveis dentro da criação de críticas de atendimento.

Tabela N: Lista de API’s Disponíveis

Atributo
API de Fontes de Dados
API de Variáveis
API de Arquivos
API HTTP
API Soap
API de Notificações