Plugin de Integração ReceitaWS

O plugin de integração com a ReceitaWS (https://receitaws.com.br/) tem os seguintes propósitos funcionais

• Facilitar a consulta/preenchimento de dados de clientes vindos do banco de dados da Receita Federal, apenas exigindo o preenchimento do CNPJ, para agilizar o cadastro de clientes e garantir a qualidade dos dados de clientes, sempre casados com o cadastro formal na Receita Federal.
• Possibilitar que o sistema possa bloquear cadastros inativos ou com bloqueios na Receita Federal.

PRECIFICAÇÃO

O plugin com a ReceitaWS está sujeito às precificações da utilização da API do fornecedor, que hoje possui plano gratuito inicial, com algumas restrições.

Para consultar quais são as restrições / benefícios / custos dos planos da ReceitaWS, acesse https://receitaws.com.br/#section-plans

CONFIGURAÇÃO

Para utilizar o plugin de integração, acesse a tela da aplicação Web "Configuração > Integração > Plugins de Integração", e clique no botão CONFIGURAR.

Na tela de configuração, haverá as seguintes seções:

• Configurações da ReceitaWS: Aqui, serão disponibilizados campos que influenciarão na chamada da requisição HTTP para o fornecedor, cujos campos editáveis são:
  
  • Token: Campo textual referente ao token do plano contratado, quando utilizado os planos não gratuitos. O valor será disponibilizado na conta do usuário no site da ReceitaWS. Caso possua dúvidas, consulte https://receitaws.com.br/faq
  • Dias defasagem: Campo numérico referente ao número de dias relativo à data de atualização do cliente que se aceita buscar os dados de clientes da base interna da ReceitaWS ao invés de buscar diretamente no banco de dados da Receita Federal.
• Configurações do SFA: Aqui, serão disponibilizados campos que influenciarão no comportamento do SFA, após a resposta da requisição à ReceitaWS ser recebida com sucesso. Os campos editáveis são:
  • Timeout consulta: Tempo máximo, em segundos, que o sistema permanecerá aguardando a resposta da ReceitaWS antes de abortar a requisição e notificar o usuário: "O servidor da ReceitaWS não respondeu a tempo"
  • Tipo local: Campo de seleção de tipos de local que serão mapeados no preenchimento dos campos vindos da API consultada. Se selecionado, por exemplo: "PRINCIPAL", somente os locais do tipo PRINCIPAL serão atualizados com os campos retornados.
  • Tipo e-mail: Campo de seleção de tipos de e-mail que serão mapeados no preenchimento dos campos vindos da API consultada. Se selecionado, por exemplo: "NFE", somente os e-mails do tipo NFE serão atualizados/inseridos com os campos retornados.
  • Tipo telefone: Campo de seleção de tipos de telefones que serão mapeados no preenchimento dos campos vindos da API consultada. Se selecionado, por exemplo: "NFE", somente os telefones do tipo NFE serão atualizados/inseridos com os campos retornados.
  • Exibir botão buscar: Campo de opções fixas, com opções:
    • Adição: Opção que determinará que o botão de buscar dados na receita aparecerá no cadastro de um novo cliente
    • Edição: Opção que determinará que o botão de buscar dados na receita aparecerá na edição de um cliente cadastrado
    • Adição e Edição: Opção que determinará que o botão de buscar dados na receita aparecerá no cadastro de um novo cliente e na edição de um cliente cadastrado
  • Mapeamento de campos: Aqui, serão disponibilizados os mapeamentos dos campos do SFA com os campos retornados pela API consultada. O campo editável nessa seção é o seguinte:
    
    • Situação: Esse campo pode ser marcado/desmarcado para estar, ou não, na relação de campos que o sistema irá preencher após a consulta.
      • Por exemplo, se não é desejado que o campo de telefone seja atualizado, poderá der desmarcado o campo do SFA local.telefone
  • Comportamento por situação: Aqui, será possível mapear os valores dos campos de retorno "situação" e "situacaoespecial" para que possam servir de critério de filtro para o comportamento definido no campo "Comportamento", cujos campo editáveis são:
    • Situação cadastral: Campo textual para definir qual o código da propriedade "situacao" que definirá o comportamento do cadastro pelo campo "Comportamento"
    • Situação especial: Campo textual para definir qual o código da propriedade "situacaoespecial" que definirá o comportamento do cadastro pelo campo "Comportamento"
    • Comportamento: Campo de opções fixas, com opções:
      • Não permitir finalização: Opção fará com que o cadastro do cliente não possa ser finalizado, caso encontre valores de resposta da API iguais (restrição AND) aos definidos pelos campos "Situação cadastral" e "Situação especial"
      • Permitir finalização, gerando aprovação: Opção fará com que o cadastro do cliente seja finalizado, porém o mesmo seja atualizado para status de aprovação (Tipo situação aprovação = PENDENTE), caso encontre valores de resposta da API iguais (restrição AND) aos definidos pelos campos "Situação cadastral" e "Situação especial"
    • Para que se possa saber os possíveis valores dos campos "situação" e "situacaoespecial" retornados pela API da ReceitaWS, utilize o link https://receitaws.com.br/v1/cnpj/${cnpj} substituindo o ${cnpj} com o CNPJ desejado, sem pontuações. Com o resultado em tela, observar os campos "situação" e "situacaoespecial".

PS: Para devido funcionamento, é necessário Configurar o serviço de integração Pentaho Carte