Callback - Envio de Formulários

Tópicos:

1 - URL base API

Ambientes	URL
Homologação	https://ms3.tapcore.com.br/mssuite/
Produção	https://ms3.tapcore.com.br/mssuite/

Como configurar a URL de Callback

Acesse o seu painel administrativo em: painel.tapcore.com.br e no menu lateral busque a funcionalidade:

Beneficiário -> Nome da Feature -> Configuração

Preencha o campo: URL de Callback com a URL que receberá a requisição de callback após inserção de uma nova solicitação de cartão.

2 - Segurança das URLs

IMPORTANTE

Todas as imagens que estão sob nosso domínio não são disponibilizadas de forma pública, favor seguir as recomendações abaixo!

Por questões de segurança todas as imagens ou objetos disponíveis através de uma URL serão enviadas com uma assinatura, desta forma, o download dos objetos ou imagens disponíveis, só serão possíveis por um período de aproximadamente 15 minutos.

Recomenda-se que seja feito o download da imagem ou objeto assinado assim que receber este payload e não salve a URL pois ela ficará indisponível após o tempo pré-determinado.

Em casos que seja necessário o acesso a este objeto ou imagem depois desse período, re-envie o callback através do painel para receber uma nova assinatura válida por mais 15 minutos

Exemplo da url ->https://autorizacao.s3-sa-east-1.amazonaws.com/AWSAccessKeyId=ABC&Expires=1616095118&Signature=ABCD

2.1 - Segurança da informação

ATENÇÃO

É importante frizar que a Mobile Saúde está implementando novas políticas de segurança, estamos implementando um novo sistema de Firewall (WAF) para bloqueios que identificarmos como nocivos, onde iremos fortemente atuar em:
Requisições que não sejam consideradas válidas;
Requisições identificadas como instruções de SQL Injection;
Recomendamos fortemente a tratativa de: Mensagens de erro não tratadas (as famosas excepctions), pois o envio de muitas destas requisições ocasionará que o seu serviço de callback seja paralizado.
Nos casos em que identificamos como tentativas nocivas aos serviçõs da Mobile Saúde repetidamente, iremos adotar o BLOQUEIO do ip de origem e com isso os serviços da operadora podem ser paralizados, em casos de falso positivo entre imediatamente em contato com o setor de Atendimento da Mobile Saúde, pelo nosso chat ou telefone para contato.

3 - Endpoints

ATENÇÃO

Utilize abaixo apenas o endpoint do serviço contratado, todos os serviços necessitam de auxilio/implementação da Mobile Saúde.

Atualização Cadastral

Feature	Endpoint	Método	Descrição
Atualização Cadastral	formulario/submit_formulario	POST	Responsável por inserir uma nova solicitação de atualização cadastral para análise, o beneficiário envia seus dados pessoais, correções e alterações de seu cadastro e arquivos de comprovante.

2 via de Cartão

Feature	Endpoint	Método	Descrição
2 via de Cartão	solicitacao/solicitacao_cartao	POST	Responsável por inserir uma nova solicitação de segunda via de cartão para análise, o beneficiário informa que deseja um novo cartão, motivo e forma de entrega, por fim os atendentes/colaboradores autorizam ou não a segunda via.

Reembolso

Feature	Endpoint	Método	Descrição
Reembolso	reembolso/inserir	POST	Responsável por inserir uma nova solicitação de reembolso para análise, o beneficiário informa um novo reembolso que por fim os atendentes/colaborador autorizam o reembolso ou não.

Cancelamento de Plano

Feature	Endpoint	Método	Descrição
Cancelamento de plano	formulario/submit_formulario	POST	Responsável por inserir uma nova solicitação de cancelamento de plano para análise, o beneficiário envia seus dados pessoais, correções e alterações de seu cadastro e arquivos de comprovante.

Solicitação de Autorização

Feature	Endpoint	Método	Descrição
Solicitação de Autroização	/solicitacao_autorizacoes/api/v1/ws/formulario/get_all_status	GET	Retorna os tipos de status de Solicitações de Autorizações.

4- Parâmetros

Atualização Cadastral

Feature	Parâmetro	Obrigatório	Tipo	Descrição
Atualização Cadastral	protocolo	true	String
Atualização Cadastral	id_operadora	true	Inteiro	Id da operadora para a qual serão buscados os grupos de menu.
Atualização Cadastral	mshash	true	String	HASH que identifica de qual ambiente (Homologação ou Produção) os dados serão buscados.
Atualização Cadastral	tipo	false	String	Tipo de beneficiário a que as informações se referem, conforme seu grau de dependência (t =Titular, d = Dependente, a = Agregado).
Atualização Cadastral	nome	true	String
Atualização Cadastral	matricula	true	String	Matrícula do usuário que está logado.
Atualização Cadastral	matricula_titular	true	String	Matrícula do titular da conta.
Atualização Cadastral	campos	true	Array	Propriedade que enviará os campos do formulário.
Atualização Cadastral	campos.id	true	Inteiro	ID do tipo de campo que será enviado.
Atualização Cadastral	campos.label	true	String	Label da opção preenchida ou selecionada pelo usuário.
Atualização Cadastral	campos.name	true	String	Nome do campo que foi preenchido.
Atualização Cadastral	campos.value	true	String	Valor do campo preenchido pelo usuário.

Exemplo de RAW enviado para a url de callback:

Atualização Cadastral - Exemplo de RAW enviado para a url de callback: Expandir origem

{ "protocolo":" XYZ", "id_operadora" : 9999, "mshash" : "" , "tipo" : "" , "nome" : "Nome 1" , "matricula" : "" , "matricula_titular" : "999", "campos" : [ { "id": "10", "label": "País", "name": "atualizacao_cadastral_pais", "value": "android test" }, { "id": "5", "label": "Telefone residencial", "name": "atualizacao_cadastral_telefone_residencial", "value": "1212121" }, { "id": "49", "label": "Número", "name": "atualizacao_cadastral_numero_2", "value": "android test" }, { "id": "859" "label": "Comprovante de endere\u00e7o", "name": "atualizacao_cadastral_comprovante_de_endereco", "value": "https:\/\/atualizacao-cadastral.s3-sa-east-1.amazonaws.com\/969542b3-4ab6-4d54-9261-6196f2eaba5a.1616074616142.png?AWSAccessKeyId=AKIA34OGA4QDSSXFT3F4&Expires=1616076000&Signature=6bH3weEUx5otIY49asdxY%2BN%2Bw0%3D", } ] }

2 via de Cartão

Feature	Parâmetro	Obrigatório	Tipo	Descrição
2 via de Cartão	protocolo	true	String
2 via de Cartão	mshash	true	String	HASH que identifica de qual ambiente (Homologação ou Produção) os dados serão buscados.
2 via de Cartão	id_solicitacao_cartao	true	Int
2 via de Cartão	id_operadora	true	Inteiro	Id da operadora para a qual serão buscados os grupos de menu
2 via de Cartão	id_aplicacao	true	Inteiro
2 via de Cartão	id_status_cartao	true	Inteiro
2 via de Cartão	id_motivo_solic_cartao	true	Inteiro
2 via de Cartão	id_forma_entrega_cartao	true	Inteiro
2 via de Cartão	nome_titular	true	String
2 via de Cartão	cpf_titular	true	Inteiro
2 via de Cartão	matricula_titular	true	String
2 via de Cartão	telefone_titular	true	Inteiro
2 via de Cartão	estado_civil_titular	true	String
2 via de Cartão	email_titular	true	String
2 via de Cartão	patrocinadora_titular	false	String
2 via de Cartão	descricao	false	String
2 via de Cartão	protocolo	true	String
2 via de Cartão	data	true	String
2 via de Cartão	forma_entrega	true	String
2 via de Cartão	motivo	true	String
2 via de Cartão	arquivos	true	Array
2 via de Cartão	arquivos.id_arquivo	true	Inteiro
2 via de Cartão	arquivos.nome	true	String
2 via de Cartão	arquivos.diretorio	true	String
2 via de Cartão	arquivos.url	true	String
2 via de Cartão	arquivos.id_solicitacao_cartao	true	String
2 via de Cartão	beneficiarios	true	Array
2 via de Cartão	beneficiarios.id_beneficiario_cartao	true	Inteiro
2 via de Cartão	beneficiarios.nome	true	String
2 via de Cartão	beneficiarios.matricula	true	String
2 via de Cartão	beneficiarios.parentesco	true	String
2 via de Cartão	beneficiarios.data_nascimento	true	String
2 via de Cartão	beneficiarios.id_solicitacao_cartao	true	Inteiro
2 via de Cartão	endereco_alternativo	false	String
2 via de Cartão	status	true	String

Exemplo de RAW enviado para a url de callback:

Exemplo de RAW enviado para a url de callback: Expandir origem

{ "id_solicitacao_cartao": 999, "id_operadora": 99, "id_aplicacao": 7, "id_motivo_solic_cartao": 6, "id_forma_entrega_cartao": 3, "id_status_cartao": 1, "matricula_titular": "000100020003", "nome_titular": "Nome de teste", "cpf_titular": 12121166742, "telefone_titular": 27000666898, "estado_civil_titular": "Solteiro", "email_titular": "teste@gmail.com", "patrocinadora_titular": null, "descricao": null, "data": "2017-08-02 13:34:38", "endereco_alternativo": "", "protocolo" : "xyz123", "mshash" : "", "motivo": "Perda", "forma_entrega": "Entregar ao Titular pelos correios", "arquivos": [{ "id_arquivo": 59, "nome": "c094be33c587e163ee702662491cd1a55ca6f854f.pdf", "diretorio": null, "url": https://s3-sa-east-1.amazonaws.com/solicitacao-cartao-ms/AWSAccessKeyId=ABC&Expires=1616095118&Signature=ABCD, "id_solicitacao_cartao": 117 }], "beneficiarios": [{ "id_beneficiario_cartao": 133, "id_solicitacao_cartao": 117, "nome": "Teste Romano Teste Rizzi", "matricula": "000100020003", "parentesco": "Titular", "data_nascimento": "1991-02-23", }], "status": "Solicitado" }

Reembolso

Parâmetro	Obrigatório	Tipo	Descrição
id_reembolso	true	string	id do reembolso no banco de dados da mobile saude
id_operadora	true	string	id da operadora no banco de dados da mobile saude
id_status_reembolso			id status do reembolso sempre como 1 ( novo)
nome_titular			nome do titular do contrato do beneficiario
cpf_titular			cpf do titular do contrato do beneficiario
telefone			telefone do beneficiario
matricula_titular			matricula do titular do contrato.
matricula_beneficiario			matricula do beneficiario que está solicitando o reembolso
id_sistema_interno
observacao_interna
protocolo			protocolo gerado pela Mobile Saúde
mshash			MSHASH único da operadora.
operadora_ans			número da operadora na ANS
despesas		array objetos
despesas / id_despesa_reembolso			id da despesa do reembolso
despesas / utilizador_matricula			matricula beneficiario solicitante do reembolso
despesas / utilizador_nome			nome beneficiario solicitante do reembolso
despesas / data_despesa			data da consulta/exame do reembolso
despesas / prestador_documento			Numero do prestador que efetuou a consulta
despesas / valor_despesa			valor da despesa do reembolso
despesas / id_tipo_reembolso
despesas / prestador_estado			estado do prestador de serviço
despesas / prestador_cidade			cidade do prestador de serviço
despesas / observacao_interna
despesas / arquivos		array objetos
despesas / arquivos [0] / nome
despesas / arquivos [0] / diretorio
despesas / arquivos [0] / url
despesas / arquivos [1] / nome
despesas / arquivos [1] / diretorio
despesas / arquivos [1] / url
terceiro_passo		array objetos	Caso possua implementado o 3 passo
terceiro_passo / banco			numero do banco
terceiro_passo / agencia			numero agencia
terceiro_passo / conta			numero conta
terceiro_passo / nome			nome do titular da conta
terceiro_passo / cpf			CPF do titular da conta
terceiro_passo / hospital
terceiro_passo / observação
terceiro_passo / prestador			nome do prestador

Exemplo de RAW enviado para a url de callback:

Exemplo de RAW enviado para a url de callback: Expandir origem

{ "id_reembolso": "508923", "id_operadora": "9999", "id_status_reembolso": "1", "nome_titular": "BENEFICIARIO DEMONSTRACAO DA SILVA", "cpf_titular": "99999999999", "telefone": "49909090913", "matricula_titular": "315263333333", "matricula_beneficiario": "315263333333", "id_sistema_interno": "2544890", "observacao_interna": null, "protocolo": "999999920210531000242", "mshash": "LAKSJDFLKAJSDLFKJASLDKFJALKSDJFLKAJSDLKFJASLKDJF==", "operadora_ans": "98989-8", "despesas": [ { "id_despesa_reembolso": "586336", "utilizador_matricula": "31526292", "utilizador_nome": "BENEFICIARIO DEMONSTRACAO DA SILVA", "data_despesa": "2021-05-27", "prestador_documento": "98989898989898", "valor_despesa": "199.00", "id_tipo_reembolso": "171", "prestador_estado": "PR", "prestador_cidade": "CURITIBA", "observacao_interna": null, "arquivos": [ { "nome": "imagem-1-temp.jpeg", "diretorio": "reembolsos", "url": "http://abcdefghil.jpeg" }, { "nome": "imagem2-temp.jpeg", "diretorio": "reembolsos", "url": "http://abcdefghil2.jpeg" } ] } ], "terceiro_passo": { "banco": "999", "agencia": "111222333", "conta": "555666777", "nome": "BENEFICIARIO DEMONSTRACAO DA SILVA", "cpf": "999.999.999-22", "hospital": "Medicos de Olhos", "observacao": "aos devs: referente a todos os atributos do 3o passo: estes campos podem ser modificados (3o passo) portanto nao sao obrigatorios, podendo nem mesmo existir", "prestador": "teste teste teste" } }

Cancelamento de Plano

Fature	Parâmetro	Obrigatório	Tipo	Descrição
Cancelamento de Plano	id_motivo_solic_cancelamento	true	String	Conforme cadastro dos motivos de cancelamento, configurados pelo cliente no painel de administração (CMS).
Cancelamento de Plano	id_operadora	true	Inteiro	Id da operadora para a qual serão buscados os grupos de menu.
Cancelamento de Plano	mshash	true	String	HASH que identifica de qual ambiente (Homologação ou Produção) os dados serão buscados.
Cancelamento de Plano	id_status_cancelamento	false	String	Status do cancelamento, conforme regra: 1 - Solicitado; 2 - Em processamento; 3 - Concluído

Exemplo de RAW enviado para a url de callback:

Exemplo de RAW enviado para a url de callback: Expandir origem

{ "id_solicitacao_cancelamento":"48", "id_protocolo":"1228", "id_operadora":"16", "id_motivo_solic_cancelamento":"3", "id_status_cancelamento":"1", "matricula_titular":"00010061003247003", "nome_titular":"NOME DO BENEFICIARIO DE EXEMPLO", "cpf_titular":"94243280010", "telefone_titular":"02733410188", "email_titular":"teste@emaildobeneficiario.com.br", "patrocinadora_titular":"", "descricao":"", "texto_complementar":"LOREM IPSUM", "data_solicitacao":"2020-11-14 09:28:30", "protocolo":"20171114500003", "mshash":"ZDhkNjY0MDY3NTgwMTg0Y2I4ZWE3ZmZiZGEyNDM0NmMwZDI0YmQwYw==", "beneficiarios":[ { "nome":"NOME DO BENEFICIARIO DE EXEMPLO", "matricula":"90909090909090909", "parentesco":"Titular", "data_nascimento":"1978-08-01", "convenio_segmentacao":"AMBULATORIAL + HOSPITALAR COM OBSTETRICIA + ODONTOLOGICO", "numero_contrato":"00010061000000000002001000000011001", "texto_complementar":null, "data_inclusao":"2020-04-01", "convenio_ans":"1001" }, { "nome":"NOME DO BENEFICIARIO DEPENDENTE DE EXEMPLO", "matricula":"90909090909090909222", "parentesco":"Dependente", "data_nascimento":"1978-08-01", "convenio_segmentacao":"AMBULATORIAL + HOSPITALAR COM OBSTETRICIA + ODONTOLOGICO", "numero_contrato":"00010061000000000002001000000011001", "texto_complementar":null, "data_inclusao":"2020-04-01", "convenio_ans":"1001" } ], "status":"Solicitado", "motivo":"Reajuste no valor do plano" }

Solicitação de Autorização

Feature
Solicitação de Autorização	protocolo	true	String
Solicitação de Autorização	id_operadora	true	Inteiro	Id da operadora para a qual serão buscados os grupos de menu.
Solicitação de Autorização	mshash	true	String	HASH que identifica de qual ambiente (Homologação ou Produção) os dados serão buscados.
Solicitação de Autorização	tipo	true	String	Tipo de formulário a ser enviado.
Solicitação de Autorização	nome	true	String	Nome do usuário.
Solicitação de Autorização	matricula	true	String	Matrícula do usuário que está logado.
Solicitação de Autorização	matricula_titular	true	String	Matrícula do titular da conta.
Solicitação de Autorização	campos	true	Array	Propriedade que enviará os campos do formulário.
Solicitação de Autorização	equipe_atendimento_cms	true	String	Equipe Responsável pelo Atendimento
Solicitação de Autorização	login	true	String	Credencial utilizada para realizar login
Solicitação de Autorização	id_ms_usuario	true	String
Solicitação de Autorização	tipo_guia	true	String	Valor para o tipo de guia do profissional
Solicitação de Autorização	id_tipo_guia	true	String	id da guia do profissional
Solicitação de Autorização	label	true	String	Titulo do formulário
Solicitação de Autorização	name	true	String
Solicitação de Autorização	value	true	String	Valor preenchido no formulário
Solicitação de Autorização	id	true	String	id do formulário

Exemplo de RAW enviado para a url de callback:

Exemplo de RAW enviado para a url de callback: Expandir origem

{ "id_operadora": "38", "protocolo": "34968220200910800114", "tipo_guia": "Profissional \/ Servi\u00e7o Auxiliar de Diagn\u00f3stico e Terapia (SP \/ SADT)", "id_tipo_guia": "117", "matricula": "00010014001500001", "tipo": "d", "nome": "PAULO ADRIANO SCHMITZ", "matricula_titular": "00010014001500001", "id_ms_usuario": "1103", "login": "93862806049", "mshash": "NDVmMTJlYmNlMzYyZGNmYTQwZTkxMjY1NzllMjIyMDY5N2MxYmNkZA==", "equipe_atendimento_cms": "Equipe Especial" "campos": [ { "label": "Nome do contato", "name": "solic_autorizacoes_nome_contato", "value": "HILDA CARLA DIAS NERY", "id": "781" }, { "label": "Telefone do contato", "name": "solic_autorizacoes_telefone", "value": "(51)99177-0431", "id": "782" }, { "label": "Matr\u00edcula", "name": "solic_autorizacoes_matricula", "value": "00010014001500010", "id": "772" }, { "label": "Nome", "name": "solic_autorizacoes_nome", "value": "HILDA CARLA DIAS NERY", "id": "772" }, { "label": "Whatsapp", "name": "solic_autorizacoes_whatsapp", "value": "(51)99177-0431", "id": "783" }, { "label": "E-mail", "name": "solic_autorizacoes_email", "value": "pauloschmitz.44@gmail.com", "id": "784" }, { "label": "Imagem da guia", "name": "solic_autorizacoes_imagens", "value": "https:\/\/atualizacao-cadastral.s3-sa-east-1.amazonaws.com\/AWSAccessKeyId=ABC&Expires=1616095118&Signature=ABCD", "id": "785" } ] }

5- Exemplo de retorno API (Sucesso)

ATENÇÃO

Todo callback executado, que tenha como retorno status header 200 será considerado uma conexão de sucesso, independente do seu retorno.
É possível também alterar o status da solicitação de atualização cadastral, basta que o serviço de integração retorne em seu body um JSON no padrão abaixo.

Atualização Cadastral

Retorno API sucesso Expandir origem

{ "protocolo" : "3139042017080113117" , "mshash" : "NjA1ZDhkNjkzN2RjMzE3NTg2ZjUyMzgyZTk5ZTkyMGU4MDA2ZGFiNg==" , "status" : "2" }

2 via de cartão

Retorno API sucesso Expandir origem

{ "protocolo" : "3139042017080113117" , "mshash" : "NjA1ZDhkNjkzN2RjMzE3NTg2ZjUyMzgyZTk5ZTkyMGU4MDA2ZGFiNg==" , "id_status_cartao" : "2" }

Reembolso

Retorno API sucesso Expandir origem

{ "protocolo" : "3139042017080113117" , "mshash" : "NjA1ZDhkNjkzN2RjMz213bNTg2ZjUyMzgyZTk5ZTkyMGU4MDA2ZGFiNg==" , "status" : "2" }

Cancelamento de Plano

Retorno API sucesso Expandir origem

{ "protocolo" : "3139042017080113117" , "mshash" : "NjA1ZDhkNjkzN2RjMzE3NTg2ZjUyMzgyZTk5ZTkyMGU4MDA2ZGFiNg==" , "status" : "2" }

Solicitação de Autorização

Retorno API sucesso Expandir origem

{ "protocolo" : "3139042017080113117" , "mshash" : "NjA1ZDhkNjkzN2RjMzE3NTg2ZjUyMzgyZTk5ZTkyMGU4MDA2ZGFiNg==" , "status" : "2" }

ATENÇÃO

Esse endpoint não possui retorno de erro mesmo enviando dados inválidos ele retorna como se não tivesse registro.