Sobre o documento
Descreve a integração com os serviços de Callback da Mobile Saúde, padrões de entrada e retorno, parâmetros e protocolos utilizados.
Definições sobre a plataforma de callback
O callback é uma integração oferecida pela Mobile Saúde, onde é possível cadastrar uma url que servirá de ponto de comunicação entre as APIs da Mobile Saúde e seu sistema, os pontos de entrada serão descritos nesse documento.
Tentativas de acesso
Caso sua aplicação possua uma url de calback configurada, o sistema da Mobile Saúde realizará uma chamada ao serviço sempre que determinada ação for executada. Toda tentativa de comunicação será logada e novas tentativas poderão ser acionadas pelos administradores.
Se houver algum problema de comunicação ou falha na execução do serviço, a Mobile Saúde executará automaticamente novas tentativas de comunicação.
Definições sobre a API
A API documentada, é a mesma utilizada pelos aplicativos, área do beneficiário web e painel administrativo. O parâmetro que identifica sua operadora e também a aplicação contratada se chama "mshash" e deve ser enviado em quase todas as requisições para identificação e segurança. O valor desse parâmetro pode ser encontrado em seu painel administrativo.
método: solicitacao/solicitacao_cartao
Responsável por inserir uma nova solicitação de segunda via de cartão para análise, o beneficiário informa os beneficiários que desejam novos cartões, motivo e forma de entrega, por fim os administradores autorizam ou não a segunda via.
Como configurar a URL de callback:
Acesse o seu painel administrativo em: painel.tapcore.com.br , no menu lateral busque a funcionalidade: Beneficiário > Solicitações de Cartão > 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 .
Especificação do callback de Segunda via de Cartão:
O callback será feito através de uma requisição HTTP do tipo POST ao serviço cadastrado, os parâmetros serão enviados via RAW no formato JSON, conforme as especificações abaixo:
Exemplo de RAW enviado para a url de callback:
{
"protocolo" : "xyz123" ,
"mshash" : "" ,
"id_solicitacao_cartao": 999,
"id_operadora": 99,
"id_aplicacao": 7,
"id_status_cartao": 1,
"id_motivo_solic_cartao": 6,
"id_forma_entrega_cartao": 3,
"nome_titular": "Nome de teste",
"cpf_titular": 12121166742,
"matricula_titular": "000100020003",
"telefone_titular": 27000666898,
"estado_civil_titular": "Solteiro",
"email_titular": "teste@gmail.com",
"patrocinadora_titular": null,
"descricao": null,
"protocolo": "3139042017080200355",
"data": "2017-08-02 13:34:38",
"forma_entrega": "Entregar ao Titular pelos correios",
"motivo": "Perda",
"arquivos": [
{
"id_arquivo": 59,
"nome": "c094be33c587e163ee702662491cd1a55ca6f854f.pdf",
"diretorio": null,
"url": https://s3-sa-east-1.amazonaws.com/solicitacao-cartao-ms/teste.pdf,
"id_solicitacao_cartao": 117
}
],
"beneficiarios": [
{
"id_beneficiario_cartao": 133,
"nome": "Teste Romano Teste Rizzi",
"matricula": "000100020003",
"parentesco": "Titular",
"data_nascimento": "1991-02-23",
"id_solicitacao_cartao": 117
}
],
"endereco_alternativo": null,
"status": "Solicitado"
}
Retornos de sucesso callback - Segunda via de cartã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 de uma solicitação de segunda via de cartão, basta que o serviço de integração retorne em seu body um json no padrão abaixo.
Retorno de alteração de status:
{
"protocolo" : "3139042017080113117" ,
"mshash" : "NjA1ZDhkNjkzN2RjMzE3NTg2ZjUyMzgyZTk5ZTkyMGU4MDA2ZGFiNg==" ,
"id_status_cartao" : "2"
}
Para lista de status, consultar o endpoint: /solicitacao_cartao/v1/api/status/listar
API – Solicitação Segunda Via de Cartão
Além da integração via callback, é possível integrar sua aplicação diretamente pela API. Utilize os métodos a seguir:
- Lista completa de status de solicitação de cartão:
- Endpoint:/solicitacao_cartao/v1/api/status/listar
- Tipo: GET
- Parâmetros:
- id_operadora
- mshash
- Retorno padrão:
{
"status": true,
"data": [
{
"id_status_cartao": 1,
"nome": "Solicitado",
"imagem": null,
"cor": null
},
{
"id_status_cartao": 2,
"nome": "Em Processamento",
"imagem": null,
"cor": null
},
{
"id_status_cartao": 3,
"nome": "Enviado",
"imagem": null,
"cor": null
}
],
"critica": null,
"timestamp": "2017-08-02T14:13:51-03:00",
"msg": "Sucesso"
}
- Detalhes de uma solicitação de cartão:
- Endpoint:/solicitacao_cartao/api/v1/ws/formulario/carregar
- Tipo: GET
- Parâmetros:
- mshash (string)
- id_operadora (int)
- id_solicitacao_cartao (int)
- Retorno padrão:
{
"status": true,
"data": [{
"id_solicitacao_cartao": 30,
"id_operadora": 71,
"id_aplicacao": 7,
"id_status_cartao": 1,
"id_motivo_solic_cartao": 3,
"id_forma_entrega_cartao": 4,
"nome_titular": "TESTE TESTE",
"cpf_titular": 999999999,
"matricula_titular": "999999",
"telefone_titular": 21996235225,
"estado_civil_titular": null,
"email_titular": teste@teste.com,
"patrocinadora_titular": null,
"descricao": null,
"protocolo": "3139042017010500105",
"data": "2017-01-05 09:21:43",
"arquivos": [
{
"id_arquivo": 9,
"nome":"c785bd95c4ed662adb4aa04bba9.png",
"diretorio": null,
"url": "https://s3-sa-east-1.amazonaws.com/solicitacao-cartao-ms/teste.png",
"id_solicitacao_cartao": 999999999
}
],
"beneficiarios": [
{
"id_beneficiario_cartao": 31,
"id_operadora": 71,
"id_aplicacao": 7,
"nome": "TESTE STELLA TESTE",
"matricula": "213123123123123",
"parentesco": "Esposo(a)",
"data_nascimento": "1942-06-17",
"id_solicitacao_cartao": 30
}
],
"endereco_alternativo": null,
"forma_entrega": "Pessoalmente",
"motivo": "Furto ou roubo com BO",
"status": "Solicitado"
} ],
"critica": null,
"timestamp": "2017-08-02T14:13:51-03:00",
"msg": "Sucesso"
}],
"critica": null,
"timestamp": "2017-08-02T14:13:51-03:00",
"msg": "Sucesso"
}
- Lista de motivos de solicitação de segunda via e cartão cadastradas no painel:
- Endpoint:/solicitacao_cartao/v1/api/motivoSolicitacao/listar
- Tipo: GET
- Parâmetros:
- id_operadora (int)
- mshash (string)
- Retorno padrão:
{
"status": true,
"data": [
{
"id_motivo_solic_cartao": 12,
"descricao": "",
"id_operadora": 71,
"id_aplicacao": 4,
"nome": "Extravio",
"tem_anexo": 0
},
{
"id_motivo_solic_cartao": 11,
"descricao": "Anexe o arquivo de BO",
"id_operadora": 71,
"id_aplicacao": 4,
"nome": "Furto ou roubo com BO",
"tem_anexo": 1
},
],
"critica": null,
"timestamp": "2017-08-02T14:22:07-03:00",
"msg": "Listagem de motivos feita com sucesso"
}
- Lista de formas de entrega de cartão cadastradas:
- Endpoint:/solicitacao_cartao/v1/api/formaEntrega/listar
- Tipo: GET
- Parâmetros:
- id_operadora (int)
- mshash (string)
- Retorno padrão:
{
"status": true,
"data": [
{
"id_forma_entrega_cartao": 99999,
"descricao": "Entrega na Recepção ao Titular ou
Portador devidamente identificado",
"observacao": null,
"exige_endereco": null,
"id_operadora": 71,
"id_aplicacao": 4
},
{
"id_forma_entrega_cartao": 7,
"descricao": "Entregar ao Titular via malote",
"observacao": null,
"exige_endereco": null,
"id_operadora": 71,
"id_aplicacao": 4
}
],
"critica": null,
"timestamp": "2017-08-02T14:31:31-03:00",
"msg": "Listagem de formas de entregas de cartão feita com sucesso"
}
- Alterar Status
- Endpoint:/solicitacao_cartao/v1/api/solicitacao/atualizarStatus
- Tipo: POST
- Parâmetros:
- id_solicitacao_cartao (int)
- id_status_cartao (int)
- mshash (string)
- Retorno padrão:
{
"status": true,
"data": [
{
"id_solicitacao_cartao": 9999999,
"id_operadora": 99999,
"id_aplicacao": 4,
"id_status_cartao": 2,
"id_motivo_solic_cartao": 30,
"id_forma_entrega_cartao": 27,
"nome_titular": "Vinicius Fiorio",
"cpf_titular": "921.880.839-70",
"matricula_titular": null,
"telefone_titular": null,
"estado_civil_titular": null,
"email_titular": null,
"patrocinadora_titular": null,
"descricao": null,
"protocolo": "33221120190506800001",
"data": "2019-05-06 09:52:18",
"forma_entrega": "Entrega na Recepção ao Titular ou Portador devidamente identificado",
"motivo": "Perda",
"arquivos": [],
"beneficiarios": [
{
"id_beneficiario_cartao": 1194,
"id_operadora": 23,
"id_aplicacao": 4,
"nome": "Conjuge",
"matricula": "2320180525180050-2",
"parentesco": "Esposa(o)",
"data_nascimento": "1990-05-06",
"id_solicitacao_cartao": 1017
}
],
"endereco_alternativo": null,
"status": "Em Processamento"
}
],
"critica": null,
"timestamp": "2019-05-06T10:35:14-03:00",
"msg": "Solicitação salva com sucesso!"
}
0 Comentários