Integração Gateway Genérica
00 | Considerações iniciais
Nessa documentação, percorreremos o método de integração de uma gateway genérica que fará disparos de Webhook para uma URL especificada no JSON de integração. Assim, pode ser utilizada para diversas gateways, dado seu método abrangente.
Para uso da mesma, será necessário no mínimo:
- URL que receberá os webhooks
- Versão do sistema superior à disponibilizada dia 25/09/2024
As ações disparadas, atualmente, dessa gateway, são:
- Cadastro de Serviço (cadastrar)
- Alteração do Cadastro (atualizar)
- Alteração de Plano (alterar_plano)
- Alteração de Status do contrato (alterar_status)
A requisição sempre será via POST, e a enviará/receberá JSONs. Consideraremos que todas as respostas de êxito de seu servidor devam ser 200, 201 ou 204. Em caso de resposta distinta, o processo em curso será impedido no SGP, e informaremos que algo ocorreu de errado. Caso seu servidor dispare, junto com um status distinto de 200/201/204 um JSON chamado error, esse erro será exibido na tela do SGP ao invés do erro padrão, exemplo:
--- status code ---
403
--- response ---
{
"error": "Falha na autenticação."
}01 | Integração da Gateway
Siga para Sistema -> Gateways -> Gateway Outros -> Consultar/Cadastrar:
Na página, prossiga para a criação de uma nova gateway em Adicionar Gateway Genérico. Nessa tela, após selecionar o tipo Genérica, e definir um nome identificador da integração, os parâmetro JSON deve ser preenchido com a URL que receberá nosso webhook.
Se necessário, também são aceitos parâmetros de autorização que serão enviados na requisição. Os mesmos podem ir no body ou header, conforme exemplo à seguir:
{
"url": "https://url.que.receberá.o/webhook",
"body": {
"api_key": "efa623ce-6e05-403d-893c-adf56cc7f436",
"api_secret": "d274ef39-5480-4b6b-8794-f8b8bff0b713"
},
"headers": {
"x-key": "Bearer token[...]"
}
}Exemplo visual dos campos preenchidos e finalização do cadastro da Gateway:
Lembrando, apenas a URL de fato é obrigatória, exemplo:
{
"url": "https://url.que.receberá.o/webhook"
}02 | Criação dos planos
Após a criação da gateway, será necessário criar planos que façam uso dela, ou nenhum webhook será disparado por parte do SGP. Para isso, criaremos planos genéricos no sistema em Administração -> Planos -> Consultar -> Planos Outros.
Lá, criaremos um novo plano genérico em Cadastrar -> Serviços. A aba inicial do cadastro do plano chamada Dados Básicos do Plano deve ser preenchida com informações básicas, como nome do plano, valores a serem cobrados, dentre outros. Logo em seguida, na aba Dados Técnicos, a gateway que criamos deve ser selecionada.
Assim, o plano já estará correto e pronto para uso.
03 | Criação do serviço genérico
Por fim, faremos a criação do nosso contrato junto do serviço genérico. Demonstrarei o processo, como será a recepção do webhook e que parâmetros receberemos no response de seus servidores.
Ao criarmos nosso contrato com o plano acima no cliente, verifique que temos dois campos dentro de um contrato do tipo Serviço, sendo eles "Gateway ID" e "Gateway Extra":
Esses parâmetros serão os identificadores desse "serviço", e serão enviados sempre por nossos webhooks dados que algumas das ações supracitadas sejam feitas no contrato em questão.
Por padrão, Gateway ID e Gateway Extra serão enviados, respectivamente, como o ID do serviço genérico (valor numérico crescente) e vazio, pelo SGP.
Dado que o servidor (url configurada na gateway) responda alguma de nossas ações com os status 200, 201 ou 204, e informe (não obrigatório) os parâmetros "gateway_id" ou "gateway_params_extra" com algum valor (alfanumérico), esses serão salvos nesse contrato/serviço genérico no SGP, e passarão a ser representados por nós por esses valores especificados.
Exemplo de um response válido partindo de seu servidor:
{
"gateway_id": "informacao que ficara no gateway id",
"gateway_params_extra": "informacao que ficara no gateway extra"
}Aqui está um exemplo de nossa requisição de cadastro:
{
"acao": "cadastrar",
"data": "15/10/2024 14:30:35.246801",
"cliente": {
"contatos": {
"telefones": [
"8433332222"
],
"celulares": [
"84988889999"
],
"emails": [
"[email protected]",
"[email protected]"
]
},
"cpfcnpj": "00011122233",
"id": 94,
"tipo": "F",
"nome": "NOME DO CLIENTE"
},
"contrato": {
"dia_vencimento": 5,
"endereco": {
"complemento": "COMPLEMENTO",
"bairro": "BAIRRO",
"cidade": "CIDADE",
"logradouro": "RUA LOGRADOURO",
"numero": 123,
"cep": "54321123",
"estado": "UF"
},
"isento": 0,
"fidelidade": {
"data_inicio": "01/10/2024",
"descricao": "NOME DA FIDELIDADE",
"data_fim": "01/10/2025"
},
"portador": {
"id": 1,
"descricao": "COBRANCA GENERICA",
"codigo_banco": "999"
},
"id": 28,
"pop": {
"id": 1,
"descricao": "NOME DO POP"
},
"forma_cobranca": "BOLETO"
},
"servico": {
"status": "ATIVO",
"gateway_id": 28,
"endereco": {
"complemento": "COMPLEMENTO",
"bairro": "BAIRRO",
"cidade": "CIDADE",
"logradouro": "RUA LOGRADOURO",
"numero": 123,
"cep": "54321123",
"estado": "UF"
},
"gateway_params_extra": "",
"login_password": "",
"plano": {
"gateway_id": "",
"id": 157,
"valor": 10,
"grupo": "generico",
"gateway": {
"id": 5,
"descricao": "Gateway Genérica"
},
"descricao": "Plano genérico do tipo Outros"
},
"login": "",
"id": 28
}
}  |
 |
 |
 |
 |
Acesso ao nosso site
www.tsmx.net.br