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 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çã pcinal Trcar senha: alteraçã de senha d usuári - implementaçã pcinal Criar usuári: cria um usuári de acess a aplicativ / prtal d beneficiári primeir acess - implementaçã pcinal Observaçã 1: apenas métd de lgin é brigatóri. Os demais métds sã pcinais, e nã necessariamente precisam ser cnstruíds pr sua empresa. Pr exempl: se prcess de autenticaçã de usuári da sua empresa só pssuir s passs de Lgin e Lembrar senha, sinta-se a vntade para desenvlver e ns dispnibilizar apenas estes métds. Observaçã 2: 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 nmes ds 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 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 cntat@ R. Agenr Amar ds Sants, 785 sala 3 - Vitória-ES CEP

2 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 regularizaçã financeira. Definiçã da estrutura usuari. Essa estrutura cntém s dads básics de um beneficiári de plan de saúde. prpriedade Tip Obrig Descriçã 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 cntat@ R. Agenr Amar ds Sants, 785 sala 3 - Vitória-ES CEP

3 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. nme String Sim Nme d usuári sex String Sim Infrmar sex d usuári F = Feminin M = Masculin N = Nã se aplica nasciment Date Nã Data de nasciment d beneficiári Frmat: yyyy-mm-dd cpf String Nã CPF d usuári celular String Nã 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 estad String Nã Estad inclusa Date Nã Data de inclusã d usuári Frmat: yyyy-mm-dd tip_usuari String Nã T = Titular D = Dependente A = Agregad matricula_titular String Nã Indica a matricula d titular quand camp tip_usuari fr diferente de T = Titular Observaçã imprtante: brigatóri para s dependentes 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_cntrataca String Sim Data da cntrataçã d plan de saúde. Obrigatóri PIN-SS cnfrme RN 389. 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 PIN-SS cnfrme 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 Nã Text descritiv d nme d plan (prdut) d beneficiári. Infrmar nme cmercial junt a ANS cntat@ R. Agenr Amar ds Sants, 785 sala 3 - Vitória-ES CEP

4 cnveni_abrangencia String Nã Text descritiv da abrangência d plan d beneficiári, segund a ANS 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 Escreva um text cmplet sbre tip de cntrat que este beneficiári pssui cm sua peradra. Infrmaçã sbre tip de cntrataçã d plan privad de assistência à saúde, cnfrme RN 195. Envie um cnteúd cm mdel abaix: I individual u familiar; II cletiv empresarial; III cletiv pr adesã. cnveni_regulamentaca Este é um camp text, prtant que fr enviad será exibid. A infrmaçã deve estar cmpleta, pis a Mbile Saúde nã mdifica / adicina nenhum text pr cnta própria. String Sim Escreva um text cmplet sbre a regulamentaçã d plan de saúde que este beneficiári pssui. Pr infrmaçã sbre a regulamentaçã d plan, entende-se: I) Plan Regulamentad celebrad após 1º de janeir de 1999; II) Plan Nã-regulamentad celebrad até 1º de janeir de 1999; u III) Plan Adaptad celebrad até 1º de janeir de 1999 e adaptads às regras da Lei nº 9.656, de 1998; Este é um camp text, prtant que fr enviad será exibid. A infrmaçã deve estar cmpleta, pis a Mbile Saúde nã mdifica / adicina nenhum text pr cnta própria. id_imagem_carta String Sim Infrme códig d mdel d cartã, definid n mment da implantaçã d layut da carteirinha virtual. Detalhament: cada mdel de cartã de sua peradra precisa de um códig únic. Indique aqui códig únic d mdel de cartã para que sistema exiba mdel d cartã crret. cntat@ R. Agenr Amar ds Sants, 785 sala 3 - Vitória-ES CEP

5 carta_validade Date Nã Indica a data de validade d cartã vigente d beneficiári Frmat: yyyy-mm-dd carta_via Int Nã Indica numer da via d cartã vigente d beneficiári chave_empresa String Nã Códig identificadr da empresa cntratante d plan d beneficiári (ns cass de plans cletivs pr adesã u cletivs empresariais). 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 empresa_nme String Nã Nme da empresa cntrat_empresa String Sim Numer d cntrat/apólice. Obrigatóri PIN-SS cnfrme RN 389. numer_cns String Sim Numer d Cartã Nacinal de Saúde. Obrigatóri n cartã d beneficiári cnfrme RN 389. cnveni_ans String Sim 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. Frmat desejad: yyyy-mm-dd 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. Obrigatóri PIN-SS cnfrme RN 389. 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 Definiçã da estrutura cntrats. Estrutura que cntém td s cntrats que usuári lgad está vinculad. prpriedade Tip Obrig Descriçã 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. 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 prpriedade Tip Obrig Descriçã carta_virtual Blean Sim True = permite acess a reembls n-line False = Nega acess a reembls n-line reembls Blean Sim True = permite acess a reembls n-line cntat@ R. Agenr Amar ds Sants, 785 sala 3 - Vitória-ES CEP

6 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 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. Imprtante: se sua empresa fr uma peradra de saúde regulamentada pela ANS, essa infrmaçã é brigatória. prpriedade Tip Obrig Descriçã 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. 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. cntat@ R. Agenr Amar ds Sants, 785 sala 3 - Vitória-ES CEP

7 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. 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. Frmat desejad: yyyy-mm-dd 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 cntat@ R. Agenr Amar ds Sants, 785 sala 3 - Vitória-ES CEP

8 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, , 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. cntat@ R. Agenr Amar ds Sants, 785 sala 3 - Vitória-ES CEP

9 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. 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 permisses 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. cntat@ R. Agenr Amar ds Sants, 785 sala 3 - Vitória-ES CEP