Layout de integração com webservices de clientes. Serviço de autenticação do beneficiário

Transcrição

1 Layut de integraçã cm webservices de clientes Serviç de autenticaçã d beneficiári Alterações n dcument Data Autr Assunt Descriçã 20/04/2015 Gerald Felix Junir Legislaçã O layut fi alterad para inclusã de nvs camps para atender a RN 360 de dezembr de 2014 padrnizaçã d cartã de identificaçã 21/04/2015 Gerald Félix Junir Melhria O layut sfreu uma melhria que permite envi de infrmações sbre as carências para serem impressas n cartã virtual. 20/12/2015 Gerald Félix Júnir Melhria 1=Crreçã da grafia ds camps 2=Inclusã de nvs camps referente RN 389 3=Melhria estrutural 19/01/2015 Gerald Félix Júnir Melhria Tratament para retrn multi-perfil 04/09/2016 Gerald Félix Júnir Melhria Tratament de camps da RN 389 e PTU /10/2016 Gerald Félix Júnir Melhria Inclusã de um nv métd de recuperaçã d númer d cartã Objetiv Este dcument tem cm bjetiv rientar a cnstruçã de um cnjunt de webservices para autenticaçã de beneficiáris para serem utilizads pela Platafrma Mbile da Mbile Saúde. Descriçã ds serviçs Neste dcument vams descrever tds s serviçs d prcess de autenticaçã de usuáris, n entant, vcê deverá desenvlver e ns dispnibilizar apenas aqueles que atendem a prcess da sua empresa. Lista de métds que serã descrits: Lgin: autentica um usuári pr mei de lgin e senha implementaçã brigatória Lembrar senha: recuperaçã de senha cm envi ds dads pr - implementaçã brigatória Trcar senha: alteraçã de senha d usuári - implementaçã brigatória Criar usuári: cria um usuári de acess primeir acess - implementaçã pcinal Recuperar númer d cartã: retrna tds s cartões vinculads a um CPF Observaçã: nme d webservice, ds métds e ds camps cntids neste layut sã sugestões e nã uma exigência. Sinta-se a vntade para nmear webservice, s métds e s camps cm desejar. Padrões de webservices Estams familiarizads a trabalhar cm webservice ns padrões REST e SOAP. Detalhament ds serviçs e das regras de negci envlvids Serviç lgin: ws_lgin_service Métd: lgin

2 Descriçã d métd Este serviç é utilizad para autenticar usuári pr mei de lgin e senha previamente cadastrada. Regas de negci Este webservice deverá validar tdas as regras de negóci da empresa e só permitir acess a usuáris autrizads. O webservice deverá retrnar usuári que fez lgin e também s membrs da sua família (dependentes) Quand usuári fr um titular! Retrna s seus dads + dads ds dependentes Quand usuári fr cônjuge! Retrna s seus dads + s demais dependestes e exclui titular d retrn Quand fr utr tip de dependente! Retrna apenas s seus dads e de nenhum utr dependente u titular Quand perfil fr Empresa, nã é necessári retrnar nenhum beneficiári. Cas beneficiári pssua mais de um cntrat, esses devem ser descrits n item Cntrats e array Familia deve cnter s membrs de tds s cntrats. Ex.: Beneficiári pssui um plan de saúde cm um filh dependente e um plan dntlógic sem dependentes. Os dis cntrats precisam estar descrits n array Cntrats e array Familia vai cnter 3 bjets (dis d plan de saúde e um d plan dntlógic) Parâmetrs de entrada usuari_lgin String Sim Id de identificaçã d beneficiári. Aqui pde ser uma matrícula d funcinári, e- mail, númer d cartã, etc. usuari_psw String Sim Senha de acess infrmada pel usuári n mment d lgin. Observaçã sbre criptgrafia: cas seja necessári criptgrafar a senha, sugerims frnecer um acess via HTTPS a invés de usar algritms própris. Estrutura de retrn status Blean Sim True = indica que lgin fi bem sucedid e usuári fi autenticad pel sistema. False = Indica que lgin fi mal sucedid e usuári nã pde acessar sistema. mtiv_critica String Nã Quand status fr igual a False, envie nesta prpriedade mtiv pel qual acess fi negad. Este camp é brigatóri quand status igual a False usuari_lgad Objet usuari Sim Retrna um bjet únic cm a estrutura usuari (definiçã abaix), cntend s dads d usuári que realizu lgin familia cntrats permisses Array de Objets usuari Array de Objets Cntrat Objet permisses Sim Nã Retrna uma lista de estruturas usuari (definiçã abaix), cntend s membrs da família d beneficiári que realizu lgin Cas cliente pssua mais de um cntrat Retrna um bjet únic cm a estrutura permisses (definiçã abaix) cntend as instruções sbre quais funcinalidades pderã ser acessadas u nã pel beneficiári lgad. alerta String Nã Cas queira enviar algum alerta para ser apresentad a beneficiári n at d lgin, basta enviar neste item. Um exempl de alerta após Lgin: Entrar em cntat cm a peradra para

3 agente_relacina ment Objet Agente Nã regularizaçã financeira. Retrna um bjet únic cm a estrutura agente (definiçã abaix) cntend as infrmações de cntat d agente de relacinament da cnta d beneficiári. Definiçã da estrutura usuari. Essa estrutura cntém s dads básics de um beneficiári de plan de saúde. chave_beneficiari String Nã Chave única de identificaçã d beneficiári n seu sistema de gestã. Este camp será utilizad pel aplicativ cm chave d beneficiári em tdas as demais integrações, cm pr exempl: blets, extrats, agendament nline e entre utrs. Ele deve ser únic pr beneficiári e nã pde se repetir em nenhuma hipótese. matricula String Sim Matricula d beneficiári. Infrmar a matricula cmpleta, sem espaçs u caracteres especiais matricula_antiga String Nã Matricula d beneficiári n sistema antig. Em alguns cass cliente cntinua utilizand a matricula d sistema antig mesm após trcar de sistema de gestã, para manter funcinand integrações cm utrs sistemas legads. Pr este mtiv é imprtante terms essa infrmaçã. matricula_funcinari String Nã Indicar códig da matricula de funcinári na empresa patrcinadra, cas aplicável. matricula_titular String Nã Infrme a matricula d titular quand camp tip_usuari fr diferente de T = Titular Observaçã: brigatóri para dependentes nme_titular String Sim Infrme nme d titular quand camp tip_usuari fr diferente de T = Titular Observaçã: brigatóri para dependentes nme String Sim Nme d usuári sex String Sim Infrmar sex d usuári F = Feminin M = Masculin N = Nã se aplica data_nasciment Date Sim Data de nasciment d beneficiári cpf String Nã CPF d usuári celular String Sim Infrmar numer d telefne celular d usuári Frmat: (999) u (999) Observaçã imprtante: se dependente nã pssuir telefne, enviar telefne d titular String Nã enderec String Nã Endereç bairr String Nã Bairr cep String Nã Cep cidade String Nã Cidade

4 estad String Nã Estad tip_usuari String Sim T = Titular D = Dependente A = Agregad grau_parentesc_id String Nã Códig d grau de parentesc d beneficiári em relaçã a titular grau_parentesc_descrica String Nã Descriçã d Grau de Parentesc data_inici_cbertura String Sim data d iníci da cbertura cntratual d beneficiári n plan privad de assistência à saúde Obrigatóri n cartã devid a RN 389 cnveni_id String Nã Códig d plan (prdut) d usuári. Este códig é fundamental para diferenciaçã da imagem d cartã, direcinament (segmentaçã) de campanhas, mensagens e ntícias, além de diversas utras funções n aplicativ e web. cnveni_descrica String Sim Text descritiv d nme d plan (prdut) d beneficiári. Infrmar nme cmercial junt a ANS Obrigatóri n cartã devid a RN 389 cnveni_abrangencia String Nã Text descritiv da abrangência d plan d beneficiári, segund a ANS Cnveni_abrangencia_ve rs Observações PTU 5.1: Camp de frente d cartã; Camp brigatóri String Nã Text descritiv da abrangência cntid n vers d cartã d PTU 5.1. Observaçã PTU 5.1: camp brigatóri cnveni_acmdaca String Nã Text descritiv d padrã de acmdaçã d plan d beneficiári, cnfrme ANS cnveni_mdalidade_c branca String Nã Text descritiv da mdalidade de cbrança d cntrat d beneficiári, cm pr exempl: Pré-pagament, Pós-pagament e etc. cnveni_padra_cnfrt String Nã Text descritiv d padrã de cnfrt d plan (prdut) cnveni_participativ String Nã Camp para infrmar se plan (prdut) d beneficiári pssui cparticipaçã u nã. S = Sim, plan pssui cparticipaçã N Nã, plan nã pssui cparticipaçã cnveni_segmentaca String Nã Text descritiv da segmentaçã d plan d (prdut). Exempl de segmentaçã: Ambulatrial + Hspitalar cm Obstetrícia. Sugere-se utilizar as segmentações definidas pela ANS, cnfrme registr de prduts. cnveni_tip_pessa String Nã Tip de cntrat d plan (prdut) d beneficiári F = Pessa Física J = Pessa Jurídica cnveni_tip_cntrat String Sim Infrmaçã sbre tip de cntrataçã d plan privad de assistência à saúde, cnfrme RN 195. Exempls: I individual u familiar; II cletiv empresarial; III cletiv pr adesã.

5 cnveni_regulamentaca String Sim infrmaçã sbre a regulamentaçã d plan, entendend-se pr: I) Plan Regulamentad; II) Plan Nã-regulamentad; III) Plan Adaptad carta_validade Date Nã Indica a data de validade d cartã vigente d beneficiári carta_via Int Nã Indica numer da via d cartã vigente d beneficiári chave_empresa_cntrata nte String Sim Códig identificadr da empresa cntratante d plan d beneficiári (ns cass de plans cletivs pr adesã u cletivs empresariais). nme_empresa_cntrata nte Observaçã: este códig é fundamental para diferenciaçã da imagem d cartã, direcinament (segmentaçã) de campanhas, mensagens e nticias, além de diversas utras funções n aplicativ e web String Sim Nme da empresa cntratante Obrigatóri PIN-SS cnfrme RN 389. Numer d cntrat/apólice. Obrigatóri PIN-SS cnfrme RN 389. cntrat_empresa_cntra tante numer_cns String Nã Numer d Cartã Nacinal de Saúde. Obrigatóri n cartã d beneficiári cnfrme RN 389. cnveni_ans String Nã Numer de registr d plan (prdut d beneficiári) junt à ANS. Obrigatóri n cartã d beneficiári cnfrme RN 389. data_final_cpt Date Nã Data final da CPT d cliente quand huver. Obrigatóri n cartã d beneficiári cnfrme RN 389. carencias Array de bjets carencia Nã Retrna uma lista de estruturas carencia (definiçã abaix) cntend as instruções sbre as carências d usuári. Essa infrmaçã só é necessária se huver necessidade de apresentar as carências n cartã virtual. cdig_cntrat String Nã Códig que identifica de qual cntrat esse usuári está vinculad. Este códig deve ser mesm d camp cdig_cntrat da estrutura cntrats rede_atendiment String Nã Infrme códig e a descriçã da Rede de Atendiment d beneficiári Definiçã da estrutura cntrats. Observaçã PTU 5.1: camp brigatóri Estrutura que cntém td s cntrats que usuári lgad está vinculad. nme String Sim Nme d cntrat cdig_cntrat String Sim Códig d cntrat que será referenciad pel camp cdig_cntrat n Objet Usuári. Definiçã da estrutura permisses. Essa estrutura cntém as instruções sbre quais funcinalidades d aplicativ usuári lgad pderá ter acess, cnfrme as regras de negci da peradra.

6 Pr exempl: se aplicativ dispnibilizar a funcinalidade Slicitaçã de Reembls Online, mas apenas s beneficiáris de um plan superir puderem acessar essa funcinalidade, a tag reembls deverá ser enviad TRUE apenas quand usuári fr um beneficiári d plan superir enquant para s demais, a tag reembls deverá ser enviada False. Observaçã: pr padrã, tdas as funcinalidades sã permitidas reembls Blean Sim True = permite acess a reembls n-line False = Nega acess a reembls n-line agendament Blean Sim True = permite acess a agendament n-line False = Nega acess a agendament n-line cparticipaçã_utilizaca Blean Sim True = permite acess a extrat de cparticipaçã False = Nega acess a extrat de cparticipaçã atualiza_cadastr Blean Sim True = permite acess a frmulári de atualizaçã cadastral False = Nega acess a frmulári de atualizaçã cadastral busca_medicament Blean Sim True = permite acess a busca de medicaments False = Nega acess a busca de medicaments blets Blean Sim True = permite acess a lista de blets False = Nega acess a lista de blets Infrme_ir Blean Sim True = permite acess a infrme de impst de renda False = Nega acess a infrme de impst de renda carta_virtual Blean Sim True = permite acess a cartã virtual False = Nega acess a cartã virtual Definiçã da estrutura carencia. Esta estrutura cntém as infrmações sbre as carências d beneficiári para serem impressas n cartã virtual. As infrmações enviadas nesta estrutura já devem estar prntas para serem apresentadas para beneficiári. tip_servic String Sim Text cm tip de serviç, exempl: Cnsulta, Exames, Internaçã, Part... carencia String Sim Infrmar text a ser apresentad, exempl: Vencida, u 31/12/2015, u 12 meses, u da frma cm fr necessári. Definiçã da estrutura agente. Esta estrutura cntém as infrmações de cntat d agente de relacinament da cnta d beneficiári. Essas infrmações aparecerã em destaque na área de cntats d aplicativ e d prtal d beneficiári. Observaçã: se nã fr infrmad nenhum u telefne, a infrmaçã nã será apresentada na área de cntats. Nme String Sim Nme cmplet d agente de relacinament Telefne1 String Nã Númer d telefne principal de cntat d agente. Infrmar númer cmplet e já frmatad Frmats aceits: (27) (27)

7 Se nã fr infrmad, telefne trnasse brigatóri. Telefne2 String Nã Númer d telefne alternativ de cntat d agente. Infrmar númer cmplet e já frmatad Frmats aceits: (27) (27) String Nã d agente de relacinament. Se nenhum telefne fr infrmad, trna-se brigatóri. Link_ft String Nã Infrme link da ft d agente de relacinament, se huver. titul_apresentaca String Nã Infrme text que será utilizad cm títul de apresentaçã d agente de relacinament. Pr padrã, aplicativ chama essa funcinalidade de Agente de Relacinament, mas se a sua peradra quiser apresentar utr text, envie nesta tag, pr exempl Gestra de Relacinament. Métd: lembrar_senha Descriçã d métd Este serviç é utilizad para recuperar s dads d beneficiári quand ele nã se lembrar d usuári e senha de acess. Regras de negóci O webservice deverá cnfrntar as infrmações frnecidas pel usuári e só recuperar a senha cas a validaçã seja psitiva e a regra de negóci da empresa permitir acess a usuári Quand alguma infrmaçã frnecida pel usuári nã fr válida, retrnar uma mensagem indicand claramente qual fi a infrmaçã que nã cnfere, pr exempl Se a data de nasciment nã bater: A data de nasciment d beneficiári nã cnfere. O envi das infrmações a beneficiári será feit pel servidr da Mbile Saúde, prtant, webservice deverá retrnar usuári, a senha, e / u telefne d beneficiári para que pssams enviar via mensageria O webservice pde ptar pr recuperar a senha gradava n banc u gerar uma nva senha aleatória entre 8 e 16 dígits, cntend pel mens uma letra, cnfrme regras da TISS. Parâmetrs de entrada usuari_lgin String Sim Id de identificaçã d usuári. Aqui pde ser uma matrícula d funcinári, , númer d cartã e etc. Depende da regra de acess da peradra.

8 usuari_cpf String Sim Camp de CPF d beneficiári, para que pssa ser utilizad para cmprvaçã d individu. usuari_nasciment Date Sim Camp data de nasciment. A ideia é que cruzament ds camps usuari_id + usuari_cpf + usuari_nasciment permita a sistema identificar beneficiári, validar s dads e retrnar a senha se tud estiver k. Estrutura de retrn status Blean Sim True = indica que as infrmações frnecidas pel usuári cnferem e a recuperaçã de senha fi bem sucedida False = Indica que as infrmações frnecidas pel usuári nã cnferem e a recuperaçã de senha fi mal sucedida mtiv_critica String Nã Quand status fr False, envie nesta prpriedade mtiv pel qual nã fi pssível lembrar a senha. Este camp é brigatóri quand status igual a False lgin String Nã Retrna usuári de acess. Pde ser a matricula, numer d cartã, , cpf e etc. Iss depende da regra da peradra. Esse camp é brigatóri quand status fr TRUE. senha String Nã Retrna a senha de acess. Esse camp é brigatóri quand status fr TRUE. String Sim d beneficiári. O sistema da Mbile Saúde irá enviar s dads para este endereç de . telefne String Nã Telefne d beneficiári. Quand nã tiver um cadastrad, sistema da Mbile Saúde pde enviar s dads de acess pr SMS, via mensageria. enviad Blean Sim Se, durante at da recuperaçã de senha seu webservice realizar envi autmátic cm s dads d usuári, retrne True neste camp. Iss fará cm que a Mbile Saúde nã envie nenhuma ntificaçã neste mment. Cas cntrári, infrme False alerta String Nã Cas queira enviar um alerta para beneficiári, utilize esta prpriedade. Exempl de us: se seu ws tenha enviad , envie um alerta assim: Os dads de acess fram enviads para xxxx@xxxx.cm.br Métd: trcar_senha Descriçã d serviç Este serviç é utilizad para alterar a senha de acess d beneficiári. O beneficiári pderá slicitar a alteraçã de senha dele, pr mei de uma pçã nas cnfigurações d aplicativ. Regras de negóci Enviarems usuári e a nva senha. O sistema altera a senha e retrna True cas tenha sucess, u False e mtiv da negativa cas nã tenha sucess na alteraçã da senha A cnfirmaçã de senha será feita na própria interface de alteraçã de senha e nã é necessária n webservice Parâmetrs de entrada usuari_lgin String Sim Id de identificaçã d usuári. Aqui pde ser uma matrícula d funcinári, ,

9 númer d cartã e etc. Depende da regra de acess da peradra. senha_atual String Sim Senha atual d usuári para que webservice valide a autenticidade nva_senha String Sim Nva senha infrmada pel usuári Estrutura de retrn status Blean Sim True = indica que a trca da senha fi bem sucedida False = Indica que a trca de senha fi mal sucedida mtiv_critica String Nã Quand status fr igual a False, envie nesta prpriedade mtiv pel qual nã fi pssível trcar a senha. Este camp é brigatóri quand status igual a False alerta String Nã Cas queira enviar algum alerta para ser apresentad a beneficiári aps a trca de senha, enviar nesta prpriedade Métd: nv_usuari Descriçã d serviç Este serviç é utilizad para criar acess a nvs usuáris, que pr mtivs peracinais, ainda nã pssuem senha de acess a aplicativ e prtal d beneficiári. Em terms prátics, este webservice seria cnsumid pr um link chamad Crie seu acess na tela de lgin. A sua existência é pcinal e depende ds prcesss peracinais de criaçã de acess da peradra. Regas de negci Este webservice deverá validar tdas as regras de negci da empresa e só permitir a criaçã d acess d usuári cas ele seja um beneficiári ativ e que tenha direit de us. O webservice deverá criar usuári de acess na base de dads da empresa e retrnar s dads d beneficiári vinculad, assim cm de td seu grup familiar cnfrme regra abaix: Quand usuári acessand fr um titular! Retrna s seus dads + grup familiar Quand usuári acessand fr cônjuge! Retrna s seus dads + s demais dependestes e exclui titular d retrn Quand fr utr tip de dependente! Retrna apenas s seus dads e de nenhum utr dependente u titular N retrn d webservice deverá cnstar uma prpriedade que sinalize qual usuári que fez lgin N retrn d webservice deverá cnstar uma prpriedade que sinalize qual usuári é titular A ideia é que se a criaçã d usuári seja bem sucedida, app já faça lgin imediatamente Parâmetrs de entrada usuari_lgin String Sim Id de identificaçã d usuári. Aqui pde ser uma matrícula d funcinári, , númer d cartã e etc. Depende da regra de acess da empresa. usuari_cpf String Sim Camp de CPF d usuári indicad n camp usuari_lgin, para cmprvaçã d individu. usuari_nasciment Date Sim Camp data de nasciment. A ideia é que cruzament ds camps usuari_id + usuari_cpf + usuari_nasciment permita a sistema identificar beneficiári cm segurança para a criaçã d usuári de acess.

10 Frmat desejad: yyyy-mm-dd usuari_senha String Sim Senha infrmada pel usuári Estrutura de retrn status Blean Sim True = indica que a criaçã d usuári fi bem sucedida e ele fi autenticad pel sistema. False = Indica que a criaçã d usuári fi mal sucedida e nã pde acessar sistema. mtiv_critica String Nã Quand status fr igual a False, envie nesta prpriedade mtiv pel qual a criaçã d usuári fi negada. Este camp é brigatóri quand status igual a False usuari_lgad Objet usuari Sim Retrna um bjet únic cm a estrutura usuari (definiçã acima), cntend s dads d usuári que se cadastru familia permisses Array de Objets usuari Objet permices Sim Retrna uma lista de estruturas usuari (definiçã acima), cntend s membrs da família d beneficiári que se cadastru Retrna um bjet únic cm a estrutura permisses (definiçã acima) que cntend as instruções sbre quais funcinalidades pderã ser acessadas u nã pel beneficiári lgad. alerta String Nã Cas queira enviar algum alerta para ser apresentad a beneficiári n at d lgin, basta enviar neste item. Um exempl de alerta para Lgin: Entrar em cntat cm a peradra para regularizaçã financeira. Métd: recupera_carta Descriçã d serviç Este serviç é utilizad para retrnar tds s cartões vinculads a um númer de CPF. Este métd é útil quand acess a aplicativ é feit pel numer d cartã e usuári nã tem esse númer na hra de fazer lgin. Regas de negci O webservice deverá receber CPF e a data de nasciment e retrnar s dads de tds s cartões vinculads a CPF infrmad. O webservice deve validar tdas as regras de negci da empresa e só retrnar s cartões válids para lgin Parâmetrs de entrada usuari_cpf String Sim Camp de CPF d usuári indicad n camp usuari_lgin, para cmprvaçã d individu. usuari_nasciment Date Sim Camp data de nasciment. A ideia é que cruzament ds camps usuari_cpf + usuari_nasciment permita a sistema identificar beneficiári cm segurança para retrnar as infrmações ds cartões.

11 Estrutura de retrn status Blean Sim True = indica que a requisiçã fi bem sucedida. False = Indica que a requisiçã fi mal sucedida. mtiv_critica String Nã Quand status fr igual a False, envie nesta prpriedade mtiv pel qual a requisiçã fi mal sucedida cartes Array de Objets carta Sim Retrna um array de bjets cntend a estrutura carta (definiçã abaix) Definiçã da estrutura carta. Essa estrutura cntém as infrmações ds cartões lcalizads para CPF infrmad nme_usuari String Sim Nme impress n cartã nme_empresa String Nã Nme da empresa cntratante impress n cartã, se huver numer_cntrat String Nã Númer d cntrat da empresa cntratante impress n cartã, se huver numer_carta String Sim Númer d cartã utilizad para lgin d usuári