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 e-mail - 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 29.052-280
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 29.052-280
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) 9999-9999 u (999) 99999-9999 Observaçã imprtante: se dependente nã pssuir telefne, enviar telefne d titular email String Nã Email 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 29.052-280
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 29.052-280
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 29.052-280
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, email 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 29.052-280
Parâmetrs de entrada usuari_lgin String Sim Id de identificaçã d usuári. Aqui pde ser uma matrícula d funcinári, e-mail, 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ã, email, 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. email String Sim Email d beneficiári. O sistema da Mbile Saúde irá enviar s dads para este endereç de email. telefne String Nã Telefne d beneficiári. Quand nã tiver um email 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 e-mail, envie um alerta assim: Os dads de acess fram enviads para email 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 29.052-280
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, e-mail, 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, e-mail, 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 29.052-280
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 29.052-280