Gateway – Web Service GSurf

Introdução

O Web Service GW SSL GSurf é um serviço, disponibilizado pela GSurf através de um servidor web seguro, que permite gerenciar os clientes de comunicação segura. Nele épossível criar novas contas, consultar situação das contas,adicionar e remover serviços, bloquear, desbloquear, cancelar, ativar contas e obter a chave de instalação do certificado.

Web Service

O Web Service GSurf utiliza a especificação REST, sob o protocolo HTTP. Os métodos do Web Service retornam os dados em formato JSON e recebem os parâmetros no corpo da requisição (application/x-www-form-urlencoded).

Segue abaixo a URL utilizada para testes:

https://rest.homolog.gsurfnet.com/

URL utilizada em produção:

https://rest.gsurfnet.com/

Necessário enviar no Header das requesições o User-agent onde se define uma nomeclatura para o mesmo.

Exemplo:

Autenticação

A autenticação é feita através de quatro parâmetros que devem ser enviados a cada requisição: chave do web service, usuário do web service, usuário da Central de Parceiros GSurf e um token dinâmico.
Estes dados são fornecidos pelo departamento comercial da GSurf.

Token

O token éuma string de 40 caracteres que é renovada a cada requisição.Em cada resposta das requisições haveráum campo,
chamado "token", que deve ser armazenado no sistema cliente para utilizar na próxima requisição.
Em alguns casos o campo "token" não aparecerá na resposta. Nestes casos o token que foi utilizado na requisição deve ser utilizado na próxima também.
Ou seja, só se deve sobrescrever o token caso o campo "token" esteja presente na resposta.
A primeira requisição do cliente ao web service não requer token. Porém, caso a resposta contenha o campo "token", as próximas requisições devem informar o token. Uma vez que o web service enviar o token não será mais possível realizar requisições sem ele.

Parâmetros de autenticação

Os parâmetros de autenticação devem estar presentes em todas as requisições.

Métodos

Políticas

GET /policies

Retorna a lista de políticas comerciais que poderão ser atribuídas aos terminais cadastradas pelo parceiro.

OBS : Não é obrigado a passar CNPJ podem consultar direto.

Retorno:

{
"result":true,
"policies":[
{
"id":25,
"description":"Politica 1"
},

{
"id":43,
"description":"Politica 2"
}
],
"token":"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2",
"error_message":""(Mensagem descrevendo o motivo do erro em caso o result seja false)
}

Serviços

GET /services

Retorna a lista de serviços que poderão ser a tribuídos às contas cadastradas pelo parceiro.

Não é necessário passar parametros, basta rodar o endpoint passando os dados de acesso.

Retorno:

{
"result":true,
"services":[
{
"id":36,
"description":"Servico1"
},
{
"id":97,
"description":"Servico2"
}
],
"token":"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2",
"error_message":"(Mensagem descrevendo o motivo do erro em caso o result seja false)"
}

Clientes

POST /customer-cpf

Cadastrar cliente com CPF. Apenas para parceiros cuja cobrança é ao parceiro.

Retorno:

{
"result":true,
"customer_id":”25”,
"error_message":"(Mensagem descrevendo o motivo do erro em caso o result seja false)

}

POST /customer-cnpj

Cadastrar clientes com CNPJ.

Retorno:

{
"result":true,
"customer_id":”26”,
"error_message":"(Mensagem descrevendo o motivo do erro em caso o result seja false)

}

PUT /customer

Editar clientes.

Retorno:

{
"result":true,
"error_message": (Mensagem descrevendo o motivo do erro em caso o resultseja false) 
}

GET /customer

Busca clientes. Os parâmetros são usados como filtros para a busca.

Retorno:

{

"result":true,
"total":2,
"customers":[{
"customer_id":"485",
"cnpj_partner":"12345678912345",
"cnpj":"12345678912345",
"company_name":"CNPJ cadastro",
"fantasy_name":"CNPJ cadastro",
"contact":"John Doe",
"city":"Garopaba",
"uf":"SC",
"ddd":"55",
"phone":"111111111",
"email":"johndoe@teste.com",
"street":"Rua teste",
"number":"0",
"district":"Bairro",
"complement":"Apt",
"cep":"12345678",
"responsible":"John Doe",
"responsible_cpf":"12345678912",
"street_cob":"Rua teste",
"number_cob":null,
"district_cob":"Bairro",
"complement_cob":"Apt",
"cep_cob":"12345678",
"city_cob":"Garopaba",
"uf_cob":"SC"
},
{
"customer_id":"488",
"cnpj_partner":"12345678912345",
"cpf":"12345678912",
"name":"Cliente CPF",
"contact":"Fulano",
"city":"Garopaba",
"uf":"SC",
"ddd":"48",
"phone":"111111111",
"email":"fulano@teste.com"
     }
  ],
  "error_message":""
}

GET /customer-retailer

Busca revendas. Os parâmetros são usados como filtros para a busca.

Retorno:

{
"result":true,
"total":2,
"retailers":[
  {
    "is_active":"1",
    "company_name":"Alisson 1 Revenda 2",
    "fantasy_name":"Alisson 1 Revenda 2",
    "cnpj":"44160227000170",
    "responsible":"john doe",
    "responsible_cpf":"10558201911",
    "ddd":"11",
    "phone":"12345678",
    "email":"teste@teste.com"
  },

  {

   "is_active":"1",
   "company_name":"Alisson 1 Revenda 1",
   "fantasy_name":"Alisson 1 Revenda 1",
   "cnpj":"09959907000157",
   "responsible":"Alisson",
   "responsible_cpf":"10558201911",
   "ddd":"00","phone":"00000000",
   "email":"alisson.pereira@gsurfnet.com"

   }

  ]

}

Terminais

GET /terminals

Retorna a lista de terminais de um determinado cliente.

Retorno:

{
  "result":true,
  "total":10,
  "terminals":[
        {

   "terminal_id":"abcd12345678901234a",
   "status":1,
   "description":"Descricao personalizada",
   "services":[
       {
          "id":"1",
          "descricao":"Teste serviço”,
          "porta":"22084”
          }
        ],"
        installation_key":"12345678"
    },

  {
    "terminal_id":"abcd12345678901234b",
    "status":8,
    "description":"Descricao personalizada",
    "services":[
      {
        "id":"1",
        "descricao":"Teste serviço”,
        "porta":"22084”
        }
     ],
     "installation_key":"87654321"

  }

],
"token":"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2",
"error_message":""

}

POST /terminal-description
Altera a descrição de um terminal.

Retorno:

{
  "result":true,
  "total":10,
  "token":"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2",
  "error_message":"" (Mensagem descrevendo o motivo do erro em caso o resultseja false)

}

GET /all-terminals

Listar terminais vinculados a um cliente.

Retorno:

{

"12345678901234":{
  "result":true,
  "total":29,
  "terminals":[
    {
      "terminal_id":"sxgs12345678901234a",
      "status":8,
      "description":null,
      "services":[
        {
          "id":"1",
          "descricao":"Teste serviço”,
          "porta":"22084”
        }
        ],
        "installation_key":"1234567890"
        }
        ],
        },
        "12345678901234":{
          "result":true,
          "total":34,
          "terminals":[
            {
              "terminal_id":"sxgs12345678905678a",
              "status":8,
              "description":null,
              "services":[],
              "installation_key":"109486831"
              }
              ],
              }
}

GET /terminal-status

Retorna o código de situação do terminal.

Retorno:

```json
{
"result":true,
"status":1,
"token":"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2",
"error_message":(Mensagem descrevendo o motivo do erro em caso o resultseja false)
}

**PUT /add-terminal**

Adiciona novo terminal para um determinado cliente.

Parâmetros | Tipo | Descrição | Obrigatório
---------|----------|---------| ------
client_id | Alfanumérico | Identificação do terminal. | Sim
cnpj_retailer | Alfanumérico | Cnpj da revenda a qual ocliente pertence. | Não
model | Alfanumérico | Modelo do terminal. | Sim
policy_id | Inteiro |  ID da política comerciala ser atribuída ao terminal, obtido no método GET/policies | Não
service_ids | Alfanumérico |   Ids dos serviços a serem atribuídos ao terminal, separadospor vírgula.   | Não
description  | Alfanumérico | Descrição fornecida pelo parceiro.    | Não

Retorno:


 ```json
{
  "result":true,
  "terminals_id":"abcd12345678901234a",
  "installation_key":"12345678",
  "token":"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2",
  "error_message":(Mensagem descrevendo o motivo do erro em caso o resultseja false)
}

POST /lock-terminal

Altera a situação de um terminal para bloqueado. Após bloqueado o terminal não poderá mais conectar ao servidor.

Retorno:

```json

{
"result":true,
"token":"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2",
"error_message": (Mensagem descrevendo o motivo do erro em caso o resultseja false)
}

**POST /unlock-terminal**

Altera a situação de um terminal para ativo. Após desbloqueado o terminal poderá se conectar ao servidornormalmente.

Parâmetros | Tipo | Descrição | Obrigatório
---------|----------|---------| ------
 terminal_id | Alfanumérico | Identificação do terminal. | Sim

 Retorno:


```json
{
"result":true,
"token":"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2",
"error_message":(Mensagem descrevendo o motivo do erro em caso o resultseja false)
}

POST /activate-terminal

Altera a situação de um terminal.

{
"result":true,
"token":"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2",
"error_message":(Mensagem descrevendo o motivo do erro em caso o resultseja false)
}

POST /cancel-terminal

Altera a situação de um terminal para cancelado.

Retorno:

{
"result":true,
"token":"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2",
"error_message":(Mensagem descrevendo o motivo do erro em caso o resultseja false)
}

POST /terminal-description

Altera a descrição de um terminal.

Retorno:

{
"result":true,
"token":"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2",
"error_message":(Mensagem descrevendo o motivo do erro em caso o resultseja false)
}

GET /terminal

Retorna os dados de um terminal.

Retorno:

{
"result":true,
"terminal":{
  "terminal_id":"abc12345678901234b",
  "status":8,
  "description":"Descricao personalizada",
  “services”:[
    {
      “id”:”1”,
      “descricao”:
      ”Teste 1”,
      “porta”:”4096”
      }
      ],
      "installation_key":"8765432190",
      },
      "token":"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2",
      "error_message":(Mensagem descrevendo o motivo do erro em caso o resultseja false)
      }

GET /installation-key

Retorna a chave de instalação do certificado.

Retorno:

{
  "result":true,
  "installation_key":"8765432190",
  "token":"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2",
  "error_message":(Mensagem descrevendo o motivo do erro em caso o result seja false)
}

PUT /add-services

Adiciona serviços ao terminal.

Retorno:

{
  "result":true,
  "token":"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2",
  "error_message":(Mensagem descrevendo o motivo do erro em caso o resultseja false)
  }

DELETE/remove-services

Remove serviços do terminal.

Retorno:

{
  "result":true,
  "token":"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2",
  "error_message":(Mensagem descrevendo o motivo do erro em caso o resultseja false)
  }

PUT/reinstall-certificate

Habilita a reinstalaçãodo terminal.

ATENÇÃO: Utilizar essa opção inutiliza o terminal até sua próxima reinstalação. Método não habilitado para terminais do tipo mobile, por causa da forma que os mesmos são instalados.

Retorno:

{
  "result":true,
  "installation_key":"1234567897",
  "error_message":(Mensagem descrevendo o motivo do erro em caso o resultseja false)
  }

Tabelas

POLÍTICAS

SERVIÇOS

CÓDIGO DE MODELO

CÓDIGOS DE SITUAÇÃO

CÓDIGO DE SITUAÇÃO DE REVENDA

Histórico de versões