logo ← gs-charge / Integração Módulo de cobranças

Integração Módulo de cobranças

Integração Módulo de cobranças

Introdução

Este documento tem como objetivo guiar terceiros na integração com o módulo de cobranças GS-Charge, explicando o processo de obtenção de credenciais, autenticação e consumo das APIs disponíveis a fim de percorrer todo o processo de cadastro das cobranças dos estabelecimentos comerciais.

Acesso às APIs

Antes de iniciar a integração, é necessário criar um App Client no portal SC3 para obter credenciais de acesso.

Passos para criar um App Client:

Acesse o portal SC3 pelo link:

   https://portal.homolog.gsurfnet.com/gsurf/login

Nota: substitua "gsurf" pelo nome da sua empresa na URL.

Acesse o menu principal: Configurações > Acesso > App Clients

appclient.jpg

Selecione os endpoints conforme imagem abaixo:

appclient_gs_charge.png

Após feito isso, para obter o token de acesso às APIs, é necessário seguir o seguinte passo:

Após salvar, copie e armazene com segurança os seguintes dados:
- Client Secret (visível apenas na tela de criação).
- Client ID (visível posteriormente).

clientID_clientSecret.jpg

📌 Requisição Token

🛠 Método: POST
🔗 URL: 

https://api-hml.gsurfnet.com/gmac-v1/oauth2/token

Autenticação: Basic Auth

Resultado: Obtenção do access_token

1 -Cobranças

1.1 - Cadastro de cobranças

Este endpoint cria o cadastro de uma cobrança para um estabelecimento comercial. Múltiplas cobranças podem ser cadastradas para um estabelecimento comercial, podendo ser vinculada, ou não, a um terminal, de forma mensal ou única. É possível criar perfís de cobrança, com o intuito de facilitar a criação das cobranças e para utilizá-lo, basta passar seu identificador único na requisição abaixo (para criar perfil, ver passo tópico de Perfil de cobranças)

Em caso de primeiro cadastro de uma cobrança de um estabelecimento comercial, o sistema irá cadastrar o estabelecimento comercial automaticamente.

Nota 1: Cada terminal cadastrado pode ter apenas uma cobrança simultaneamente ativa, bem como estar vinculado apenas a um estabelecimento comercial simulataneamente.

Nota 2: Devemos ter em mente a premissa de que as cobranças tem a sua data de cobrança sempre como o primeiro dia do mês.

Nota 3: Mesmo que informando o identificador único de um perfil, caso seja especificado os mesmos campos na cobrança, como por exemplo "amount", os valores que prevalecerão serão os do cadastro da cobrança.

📌 Requisição

🛠 Método: POST
🔗 URL: 

https://api-hml.gsurfnet.com/gs-charge/charge

Request

Body

application/json

Dados para cadastro de uma cobrança para um terminal de um estabelecimento comercial.

{
  "profile_id": "string", // Identificador único de um perfil de cobranças.
  "amount": "integer", // Valor da cobrança.
  "description": "string", // Descrição da cobrança.
  "waiting_period": "integer", // Tempo de carência da cobrança.
  "discount": { // Dados do desconto dado na cobrança.
    "type": "string", // Tipo do desconto.
    "value": : "integer" // Valor do desconto
  },
  "merchant": { // Dados do estabelecimento comercial.
    "description": "string", // Descrição do estabelecimento comercial.
    "document": "string" // CPF/CNPJ vinculado ao estabelecimento comercial.
  },
  "terminal": { // Dados do terminal, se aplicável.
    "serial_number": "string", // Número de série do terminal.
    "terminal_code": "string", // Código do terminal.
    "model": "string", // Modelo do terminal.
    "gsurf_correlation_id": "string", // Identificação do terminal nos sistemas da GSURF.
    "habituality_amount": "integer" // Meta de vendas do terminal para isenção
    }
  },
  "recurrence": "string", // Tipo de recorrência de cobrança.
  "charge_type": "string" // Tipo da cobrança
}

Valores Permitidos para recurrence

Valores Permitidos para type (discount)

Valores Permitidos para charge_type

Nota: Em valores expressando grandezas monetárias ou percentuais, faz-se necessário o envio do campo no formato RealCentavo. Exemplo de 10(dez) reais, os centavos devem vir juntos, sem pontuação sendo 1000.
Já no caso de 10(dez) reais e 50(cinquenta) centavos espera-se 1050 e no caso de 10(dez) centavos basta 10. No caso das porcentagens, 10% (dez porcento) deve vir 1000, se fossem 10,5% seriam 1050 e meio porcento apenas 50.

Responses

Código Descrição
201 Created (Cadastro realizado com sucesso)
400 Bad Request (Erro nos parâmetros da requisição)
500 Internal Server Error (Erro interno no servidor)

1.2 - Listagem de cobranças

É possível listar as cobranças conforme abaixo:

📌 Requisição

🛠 Método: GET
🔗 URL: 

https://api-hml.gsurfnet.com/gs-charge/charge/{charge_id}

Request

Path Parameters

Parâmetro Tipo Obrigatório Descrição
charge_id string ❌ Identificador da cobrança (UUID)

Query Parameters

Query parameters utilizados caso não seja utilizado o path parameter charge_id. Caso não informado nenhum query parameter, retorna todas as cobranças de todos os estabelecimentos comerciais, de forma paginada.
| Parâmetro | Tipo | Obrigatório | Descrição |
|-------------|--------|-------------|-----------|
| init_date | string | ❌ | Data inicial de busca das cobranças pela data de cobrança YYYY-MM-DD |
| fin_date | string | ❌ | Data final de busca das cobranças pela data de cobrança YYYY-MM-DD |
| profile_id | string | ❌ | Identificador do perfil (UUID) |
| merchant | string | ❌ | CPF/CNPJ do estabelecimento comercial |
| charge_type | string | ❌ | Tipo de cobrança |
| status | string | ❌ | Status da cobrança |
| limit | string | ❌ | Limite de cobranças por paginação |
| with_terminal | boolean | ❌ | Flag de cobranças com ou sem terminais) |
| c | string | ❌ | Token de paginação |

Responses

Código Descrição
200 OK (Sucesso)
404 Not Found (Não encontrado)
500 Internal Server Error (Erro interno no servidor)

1.3 - Edição de cobrança

É possível editar cobranças criadas conforme abaixo:

📌 Requisição

🛠 Método: PUT
🔗 URL: 

https://api-hml.gsurfnet.com/gs-charge/charge/{charge_id}

Request

Path Parameters

Parâmetro Tipo Obrigatório Descrição
charge_id string ✅ Identificador da cobrança (UUID)

Body

application/json

Dados para atualizar uma cobrança.

{
  "discount": { // Dados do desconto.
    "type": "string", // Tipo de desconto.
    "value": "integer", // Valor do desconto.
  }
  "amount": "integer", // Valor da cobrança.
  "description": "string", // Descrição da cobrança.
  "habituality_amount" // Meta de vendas do terminal para isenção.
  "status": "string", // Status da cobrança.
  "profile_id": "string", // Identificador único de um perfil.
}

Valores Permitidos para type(discount)

Valores Permitidos para status

Nota: Em valores expressando grandezas monetárias, faz-se necessário o envio do campo no formato RealCentavo. Exemplo de 10(dez) reais, os centavos devem vir juntos, sem pontuação sendo 1000. Já no caso de 10(dez) reais e 50(cinquenta) centavos espera-se 1050 e no caso de 10(dez) centavos basta 10.

Responses

Código Descrição
200 OK (Atualizado com sucesso)
404 Not Found (perfil não encontrado)
500 Internal Server Error (Erro interno no servidor)

1.4 - Cobranças em lote

Este endpoint possibilita o cadastro e edição de múltiplas cobranças a partir do envio de um arquivo de extensão .csv. A disposição dos dados no arquivo, suas obrigatoriedades e exemplos segue conforme tópico 7 - arquivo de cobranças em lote.

Para a utilização do cadastro em lote, deve-se primeiro requisitar a URL de upload, conforme requisição abaixo, e em seguida enviar o arquivo na URL recebida com método PUT. Para a visualização dos arquivos enviados e seus respectivos status, consultar tópico 8 - Listar arquivos csv de cadastro em lote.

📌 Requisição

🛠 Método: GET
🔗 URL: 

https://api-hml.gsurfnet.com/gs-charge/charge/batch

Responses

Código Descrição
201 Created

2 - Perfil de cobranças

O perfil de cobranças é utilizado para facilitar a criação de múltiplas cobranças, utilizando os valores já pré cadastrados no perfil.

2.1 - Cadastro de Perfil

É possível realizar o cadastro do perfil conforme abaixo

📌 Requisição

🛠 Método: POST
🔗 URL: 

https://api-hml.gsurfnet.com/gs-charge/charge-profile

Request

Body

application/json

Dados para cadastro de um perfil de cobrança.

{
  "amount": "integer", // Valor da cobrança.
  "description": "string", // Descrição da cobrança.
  "waiting_period": "integer", // Tempo de carência da cobrança.
  "habituality_amount": "integer" // Meta de vendas do terminal para isenção
  "recurrence": "string", // Tipo de recorrência de cobrança.
}

Valores Permitidos para recurrence

Nota: Em valores expressando grandezas monetárias, faz-se necessário o envio do campo no formato RealCentavo. Exemplo de 10(dez) reais, os centavos devem vir juntos, sem pontuação sendo 1000. Já no caso de 10(dez) reais e 50(cinquenta) centavos espera-se 1050 e no caso de 10(dez) centavos basta 10.

Responses

Código Descrição
201 Created (Cadastro realizado com sucesso)
400 Bad Request (Erro nos parâmetros da requisição)
500 Internal Server Error (Erro interno no servidor)

2.2 - Listagem de Perfil

É possível realizar a listagem dos perfis criados conforme abaixo:

📌 Requisição

🛠 Método: GET
🔗 URL: 

https://api-hml.gsurfnet.com/gs-charge/charge-profile/{profile_id}

Request

Path Parameters

Parâmetro Tipo Obrigatório Descrição
profile_id string ❌ Identificador do perfil (UUID)

Responses

Código Descrição
200 OK (Encontrado com sucesso)
404 Not Found (Não encontrado)
500 Internal Server Error (Erro interno no servidor)

2.3 - Edição de Perfil

É possível editar perfis criados conforme abaixo:

📌 Requisição

🛠 Método: PUT
🔗 URL: 

https://api-hml.gsurfnet.com/gs-charge/charge-profile/{profîle_id}

Request

Path Parameters

Parâmetro Tipo Obrigatório Descrição
profile_id string ✅ Identificador do perfil (UUID)

Body

application/json

Dados para atualizar um perfil de cobrança.

{
  "amount": "integer", // Valor da cobrança.
  "description": "string", // Descrição da cobrança.
  "waiting_period": "integer", // Tempo de carência da cobrança.
  "habituality_amount": "integer", // Meta de vendas do terminal para isenção
  "recurrence": "UNIQUE", // Tipo de recorrência de cobrança.
}

Valores Permitidos para recurrence

Nota: Em valores expressando grandezas monetárias, faz-se necessário o envio do campo no formato RealCentavo. Exemplo de 10(dez) reais, os centavos devem vir juntos, sem pontuação sendo 1000. Já no caso de 10(dez) reais e 50(cinquenta) centavos espera-se 1050 e no caso de 10(dez) centavos basta 10.

Responses

Código Descrição
200 OK (Atualizado com sucesso)
404 Not Found (perfil não encontrado)
500 Internal Server Error (Erro interno no servidor)

3 - Isenção de Estabelecimento Comercial

A isenção de estabelecimento comercial (IEC) refere-se ao modo de isenção das cobranças cadastradas, independe do tipo da cobrança e vinculo com terminal. A isenção por estabelecimento comercial sobrepõe a meta individual de cada terminal.

Caso a meta de uma IEC for alcançada, serão isentas o total de cobranças estipuladas no cadastro a seguir, de forma aleatória. Por exemplo, se um estabelecimento comercial possui 5 terminais com cobranças cadastras e uma IEC cadastrada com o total de 2 cobranças de terminal, caso atinja a meta configurada na IEC serão escolhidas 2 das quaisquer 5 totais.

Podemos também utilizar o método de cadastro em massa utilizando o Grupo de Isenção de Estabelecimento Comercial.

3.1 - Cadastro de Isenção de Estabelecimento Comercial

É possível realizar o cadastro de uma IEC, conforme abaixo:

📌 Requisição

🛠 Método: POST
🔗 URL: 

https://api-hml.gsurfnet.com/gs-charge/merchant-exemption

Request

Body

application/json

Dados para cadastro de um IEC.

{
  "sales_target": "integer", // Valor da meta.
  "terminal_exemption": "string", // Total de cobranças de terminais a serem isentas.
  "other_exemption": "integer", // Total de outros tipos de cobranças a serem isentas.
  "document": "string" // CPF/CNPJ do estabelecimento comercial.
}

Nota 1: Em valores expressando grandezas monetárias, faz-se necessário o envio do campo no formato RealCentavo. Exemplo de 10(dez) reais, os centavos devem vir juntos, sem pontuação sendo 1000. Já no caso de 10(dez) reais e 50(cinquenta) centavos espera-se 1050 e no caso de 10(dez) centavos basta 10.

Nota 2: Todo estabelecimento comercial ao começar a utilizar uma IEC terá um registro totalizador de vendas daquele mês para sabermos se foi alcançada a meta, que será abordado mais adiante deste documento.

Responses

Código Descrição
201 Created (Cadastro realizado com sucesso)
400 Bad Request (Erro nos parâmetros da requisição)
500 Internal Server Error (Erro interno no servidor)

3.2 - Listagem de Isenção de Estabelecimento Comercial

É possível realizar a listagem de isenção de estabelecimento comercial, conforme abaixo:

📌 Requisição

🛠 Método: GET
🔗 URL: 

https://api-hml.gsurfnet.com/gs-charge/merchant-exemption

Request

Query Parameters

Query parameters utilizados. Deve ser encaminhado o parâmetro de documento da loja na primeira requisição a ser realizada, para assim encontrar as isenções cadastradas de uma loja.
| Parâmetro | Tipo | Obrigatório | Descrição |
|-------------|--------|-------------|-----------|
| order | string | ❌ | Ordenação do retorno da paginação|
| merchant_document | string | ⚠️ | CPF/CNPJ do estabelecimento comercial. Obrigatório apenas na primeira chamada |
| limit | string | ❌ | Limite de IEC por paginação |
| c | string | ❌ | Token de paginação |

Valores Permitidos para order

Responses

Código Descrição
200 OK (Encontrado com sucesso)
404 Not Found (Não encontrado)
500 Internal Server Error (Erro interno no servidor)

3.3 - Edição de Isenção de Estabelecimento Comercial:

⚠️⚠️⚠️ ATENÇÃO! Esta etapa tornou-se obsoleta a partir da data de 24/11/2025 ⚠️⚠️⚠️

É possível editar IECs criados conforme abaixo:

📌 Requisição

🛠 Método: PUT
🔗 URL: 

https://api-hml.gsurfnet.com/gs-charge/merchant-exemption/{id}

Request

Path Parameters

Parâmetro Tipo Obrigatório Descrição
id string ✅ Identificador do IEC (UUID)

Body

application/json

Dados para atualizar um IEC.

{
  "sales_target": "integer", // Valor da meta.
  "terminal_exemption": "string", // Total de cobranças de terminais a serem isentas.
  "other_exemption": "integer", // Total de outros tipos de cobranças a serem isentas.
}

Nota 1: Só é permitido alterar IECs que ainda não entraram em vigor. Após uma IEC ter entrado em vigor, caso queira alterar algum valor, deve ser criada uma NOVA IEC.

Nota 2: Em valores expressando grandezas monetárias, faz-se necessário o envio do campo no formato RealCentavo. Exemplo de 10(dez) reais, os centavos devem vir juntos, sem pontuação sendo 1000. Já no caso de 10(dez) reais e 50(cinquenta) centavos espera-se 1050 e no caso de 10(dez) centavos basta 10.

Responses

Código Descrição
200 OK (Atualizado com sucesso)
404 Not Found (perfil não encontrado)
500 Internal Server Error (Erro interno no servidor)

3.4 - Cancelamento de Isenção de Estabelecimento Comercial:

É possível cancelar IEC, quando solicitado, a configuração individual desse estabelecimento comercial será cancelada, entretanto o totalizador de vendas do mês continuará existindo caso volte a ser utilizado. Ao cancelar com sucesso, o estabelecimento comercial continuará no modo de isenção mais adequado ao momento conforme configurações do mesmo.

📌 Requisição

🛠 Método: DELETE
🔗 URL: 

https://api-hml.gsurfnet.com/gs-charge/merchant-exemption/{document}

Request

Path Parameters

Parâmetro Tipo Obrigatório Descrição
document string ✅ Documento do estabelecimento comercial

Responses

Código Descrição
200 OK (Atualizado com sucesso)
404 Not Found (Não encontrado)
500 Internal Server Error (Erro interno no servidor)

4 - Grupo de Isenção de Estabelecimento Comercial

O grupo isenção de estabelecimento comercial (GIEC) funciona da mesma forma que uma IEC, porém cadastrando um mesmo valor para vários estabelecimentos comerciais.

4.1 - Cadastro de Grupo de Isenção de Estabelecimento Comercial

É possível realizar o cadastro de um GIEC, conforme abaixo:

📌 Requisição

🛠 Método: POST
🔗 URL: 

https://api-hml.gsurfnet.com/gs-charge/merchant-exemption-group

Request

Body

application/json

Dados para cadastro de um GIEC.

{
  "description": "string" // Descrição do grupo.
  "sales_target": "integer", // Valor da meta.
  "terminal_exemption": "string", // Total de cobranças de terminais a serem isentas.
  "other_exemption": "integer", // Total de outros tipos de cobranças a serem isentas.
  "merchant_list": "List"["string"] // Lista de CPF/CNPJ dos estabelecimentos comerciais.
}

Nota 1: Em valores expressando grandezas monetárias, faz-se necessário o envio do campo no formato RealCentavo. Exemplo de 10(dez) reais, os centavos devem vir juntos, sem pontuação sendo 1000. Já no caso de 10(dez) reais e 50(cinquenta) centavos espera-se 1050 e no caso de 10(dez) centavos basta 10.

Nota 2: Assim como em uma IEC, ao cadastrar estabelecimentos comerciais em um grupo, entrará em vigor no mesmo momento de cadastro. Estabelecimentos comerciais que estiverem utilizando um GIEC e estiver na lista de estabelecimentos comerciais a serem inseridos no grupo que está sendo criado, retornará erro e não serão inseridos no grupo! Para isso, devem ser removidos préviamento do grupo atual.

Responses

Código Descrição
201 Created (Cadastro realizado com sucesso)
400 Bad Request (Erro nos parâmetros da requisição)
500 Internal Server Error (Erro interno no servidor)

4.2 - Listagem de Grupo Isenção de Estabelecimento Comercial

É possível realizar a listagem de grupo isenção de estabelecimento comercial, conforme abaixo:

📌 Requisição

🛠 Método: GET
🔗 URL: 

https://api-hml.gsurfnet.com/gs-charge/merchant-exemption-group/{id}

Request

Path Parameters

Parâmetro Tipo Obrigatório Descrição
id string ❌ Identificador do GIEC (UUID)
#### Query Parameters
Query parameters utilizados caso não seja utilizado o path parameter id. Caso não informado nenhum query parameter, retorna todas GIECs de todos os estabelecimentos comerciais, de forma paginada.
Parâmetro Tipo Obrigatório Descrição
------------- -------- ------------- -----------
order string ❌ Ordenação do retorno da paginação
merchant_document string ❌ CPF/CNPJ do estabelecimento comercial
limit string ❌ Limite de IEC por paginação
c string ❌ Token de paginação

Valores Permitidos para order

Responses

Código Descrição
200 OK (Encontrado com sucesso)
404 Not Found (Não encontrado)
500 Internal Server Error (Erro interno no servidor)

4.3 - Edição de Grupo Isenção de Estabelecimento Comercial:

É possível editar GIECs criados conforme abaixo:

📌 Requisição

🛠 Método: PUT
🔗 URL: 

https://api-hml.gsurfnet.com/gs-charge/merchant-exemption-group/{id}

Request

Path Parameters

Parâmetro Tipo Obrigatório Descrição
id string ✅ Identificador do IEC (UUID)

Body

application/json

Dados para atualizar um GIEC.

{
  "description": "string", // Descrição do grupo.
  "sales_target": "integer", // Valor da meta.
  "terminal_exemption": "string", // Total de cobranças de terminais a serem isentas.
  "other_exemption": "integer", // Total de outros tipos de cobranças a serem isentas.
  "to_include": "List"["string"], // Lista de estabelecimentos comerciais a serem inclusos.
  "to_exclude": "List"["string"], // Lista de estabelecimentos comerciais a serem exclusos.
  "remove_all_merchants": "boolean" // remover todos estabelecimentos comerciais.
}

Nota 1: O campo remove_all_merchants deve ser utilizado sozinho para o caso de remover todos os estabelecimentos comerciais de dentro do grupo. Caso sejam lojas que já utilizavam o GIEC, será realizado a remoção no mesmo instante. O totalizador de meta alcançada no modo de GIEC de uma EC será preservado!

Nota 2: para transferência de um estabelecimento comercial do grupo A para o grupo B, basta primeiro cadastrar o documento em to_exclude no grupo A e na sequência, em to_include no grupo B. Para tranferência de um estabelecimento comercial de um grupo para uma IEC, basta primeiro cadastrar o documento em to_exclude do grupo e na sequência cadastrar a IEC.

Responses

Código Descrição
200 OK (Atualizado com sucesso)
404 Not Found (perfil não encontrado)
500 Internal Server Error (Erro interno no servidor)

4.4 - Cadastro em massa de Grupo de Isenção de Estabelecimento Comercial:

É possível cadastrar estabelecimentos comerciais em massa em GIECs criados. Para isso, deve ser passado de forma obrigatória o path parameter {id} contendo o identificador único do grupo. Se o grupo for encontrado, a API retornará uma URL para enviar um arquivo .csv para ser consumido e realizar o agendamento de cadastro dos estabelecimento comerciais no grupo informado.

📌 Requisição

🛠 Método: GET
🔗 URL: 

https://api-hml.gsurfnet.com/gs-charge/merchant-exemption-group-file/{id}

Request

Path Parameters

Parâmetro Tipo Obrigatório Descrição
id string ✅ Identificador do GIEC (UUID)

📌 Requisição

🛠 Método: PUT
🔗 URL: Utilizar URL do retorno da API GET.

Request

Body

binary

Encaminhar o arquivo .csv com o conteudo estruturado da seguinte forma:
Utilizar apenas a primeira coluna, contendo em cada linha apenas um documento. Conforme imagem abaixo:

giec-file-sample.jpg

Para listar os arquivos encaminhados e seus status de processamento, ver tópico 8 Listar arquivos csv de cadastro em lote

Responses

Código Descrição
200 OK (Atualizado com sucesso)
404 Not Found (Não encontrado)
500 Internal Server Error (Erro interno no servidor)

4.5 - Cancelamento de Grupo de Isenção de Estabelecimento Comercial:

É possível cancelar GIECs criados conforme abaixo:

📌 Requisição

🛠 Método: DELETE
🔗 URL: 

https://api-hml.gsurfnet.com/gs-charge/merchant-exemption-group/{id}

Request

Path Parameters

Parâmetro Tipo Obrigatório Descrição
id string ✅ Identificador do GIEC (UUID)

Nota 1: Ao cancelar o grupo, o mesmo deixará de funcionar no mesmo momento! Caso um estabelecimento comercial pertencente ao grupo tenha uma IEC cadastrada, voltará com prioridade a mesma, do contrário retornará aos valores de metas cadastrados nas cobranças.

Responses

Código Descrição
200 OK (Atualizado com sucesso)
404 Not Found (Não encontrado)
500 Internal Server Error (Erro interno no servidor)

5 - Registro Totalizador

O registro totalizador sempre é criado de forma automática quando um estabelecimento comercial utiliza IEC ou um GIEC. No primeiro mês de utilização será criado a partir da primeira venda, os demais meses é criado no primeiro dia do mês, independente se houve alguma venda, porém com valor zerado. Este registro é necessário para validar se a meta das IEC ou GIEC foram alcançadas pelos estabelecimentos comerciais.

5.1 - Listagem de Registro Totalizador

É possível realizar a listagem dos registros totalizadores, conforme abaixo:

📌 Requisição

🛠 Método: GET
🔗 URL: 

https://api-hml.gsurfnet.com/gs-charge/merchant-totalizer

Request

Query Parameters

Caso não seja fornecido nenhum parâmetro, retorna todos de forna paginada.
| Parâmetro | Tipo | Obrigatório | Descrição |
|-------------|--------|-------------|-----------|
| totalizer_date | string | ❌ | Data do totalizador YYYY-MM|
| initial_date | string | ❌ | Data inicial da busca pela data do totalizador YYYY-MM |
| final_date | string | ❌ | Data final da busca pela data do totalizador YYYY-MM |
| merchant_document | string | ❌ | Documento do estabelecimento comercial |
| limit | string | ❌ | limite de retorno por paginação |
| c | string | ❌ | Token de paginação |

Responses

Código Descrição
200 OK (Encontrado com sucesso)
404 Not Found (Não encontrado)
500 Internal Server Error (Erro interno no servidor)

6 - Relatório de Cobranças

O relatório de cobranças permite listar dados das cobranças em um arquivo .csv Deve ser feito a requisição e quando pronto, ficará disponível para download.

6.1 - Criação do arquivo

É possível solicitar a criação do arquivo de relatório, conforme abaixo:

📌 Requisição

🛠 Método: POST
🔗 URL: 

https://api-hml.gsurfnet.com/gs-charge/charge-csv

Request

Body

application/json

Dados para solicitar um relatório, caso nenhum fornecido, vai gerar um arquivo geral, contendo todas as cobranças dos estabelecimentos comerciais.

{
  "merchant_document": "string" // Documento do estabelecimento comercial.
  "with_terminal": "boolean", // Seletor de cobranças com ou sem terminais associados.
  "profile_id": "string", // Identificador único de um perfil.
}

Responses

Código Descrição
201 Created (Cadastro realizado com sucesso)
400 Bad Request (Erro nos parâmetros da requisição)
500 Internal Server Error (Erro interno no servidor)

6.2 - Listagem de Relatórios de cobranças

É possível realizar a listagem dos arquivos solicitados de relatórios de cobranças, conforme abaixo:

📌 Requisição

🛠 Método: GET
🔗 URL: 

https://api-hml.gsurfnet.com/gs-charge/my-export-files

Request

Query Parameters

Query parameters utilizados. Caso não informado nenhum query parameter, retorna todos os arquivos de relatórios, de forma paginada.
| Parâmetro | Tipo | Obrigatório | Descrição |
|-------------|--------|-------------|-----------|
| initial_creation_date | string | ❌ | Data inicial do período de busca por data de criação, formato DATETIME|
| final_creation_date | string | ❌ | Data final do período de busca por data de criação, formato DATETIME|
| limit | string | ❌ | Limite de arquivos por paginação |
| c | string | ❌ | Token de paginação |

Responses

Código Descrição
200 OK (Encontrado com sucesso)
404 Not Found (Não encontrado)
500 Internal Server Error (Erro interno no servidor)

6.3 - Download de relatório de cobranças:

É possível baixar os arquivos conforme abaixo:

📌 Requisição

🛠 Método: GET
🔗 URL: 

https://api-hml.gsurfnet.com/gs-charge/download-file/{id}

Request

Path Parameters

Parâmetro Tipo Obrigatório Descrição
id string ✅ Identificador do arquivo (UUID)

Caso encontre o arquivo, a API retornará uma URL para download do arquivo em formato .csv.

Responses

Código Descrição
200 OK (Atualizado com sucesso)
404 Not Found (perfil não encontrado)
500 Internal Server Error (Erro interno no servidor)

7 - Arquivo de cobranças em lote

Este tópico descreve a estrutura do arquivo de cadastro de cobranças em lote.

7.1 - Nomenclatura e Convenções

O arquivo possui formato .CSV, não deve conter espaçamento entre campos, o seprador entre cada campo será 'ponto e vírgula' e caso o campo seja múltiplos valores, utiliza como separador interno 'vírgula'.
O arquivo não conterá header ou trailer e o seu processamento deve ser considerado linha a linha até o final do arquivo. Cada linha contém exclusivamente dados de uma cobrança.
O arquivo pode ser composto de linhas de cadastro de cobranças e de edição de cobranças.
Os retornos de erros de processamento de arquivo e status do processamento estão listados nas tabelas nº 4 e 5.

7.2 - Modelo de cadastro de cobranças

O modelo descrito nos itens abaixo é referente ao cadastro de cobranças.

7.2.1 - Descrição dos Campos Contidos no Arquivo

Para todas as cobranças a serem criadas via arquivo, devem seguir o seguinte formato abaixo. Em caso de campos não obrigatórios, deve ser enviado o campo vazio ou escrito 'nulo', visando sempre ter 12(doze) campos por cobrança.

⚠️⚠️ATENÇÃO⚠️⚠️: Os campos abaixo expressados como não obrigatórios é devido os seguintes cenários:

ID NOME DO CAMPO Obrigatório DESCRIÇÃO
01 Tipo de cobrança ✅ Conforme tabela nº1
02 Descrição ✅ Descrição da cobrança, máximo 50 caracteres
03 Dados da loja ✅ Documento e Descrição da loja
04 Dados do Desconto ✅ tipo do desconto(Conforme tabela nº2) e valor do desconto
05 ID do perfil ❌ Identificador único do perfil de cobrança
06 Meta de vendas do terminal ❌ Meta de vendas do terminal para isenção
07 Tipo de recorrêcia ❌ Conforme tabela nº3
08 Dados do terminal ❌ código do terminal, gsurf terminal id, número de série e modelo (consultar documentação MTM)
09 Tempo de carência ❌ Número de dias de carência onde não será cobrado o uso do terminal
10 Valor da cobrança ❌ Valor da cobrança em centavos
11 ID da cobrança ❌ Identificador único da cobrança a ser editada
12 Status da cobrança ❌ Status da cobrança

Nota: Em valores expressando grandezas monetárias ou percentuais, faz-se necessário o envio do campo no formato RealCentavo. Exemplo de 10(dez) reais, os centavos devem vir juntos, sem pontuação sendo 1000.
Já no caso de 10(dez) reais e 50(cinquenta) centavos espera-se 1050 e no caso de 10(dez) centavos basta 10. No caso das porcentagens, 10% (dez porcento) deve vir 1000, se fossem 10,5% seriam 1050 e meio porcento apenas 50.

Nota 2: Quaisquer campo descritivo, não deve utilizar acentuação e 'Ç' (cedilha);

7.2.2 - Exemplo de arquivo:

Dados para exemplo arquivo csv.

Exemplo cobrança de terminal com todos os campos:

csv

csv 006;descricao da cobranca;01234567891,descricao da loja;NOMINAL,1000;0a22e7b0-2601-4d0a-a381-3eddbefcc485;10099;RECURRENCE;123,456,789,modelo terminal;10;20000;;
Nota: Neste caso os dados dos campos 06, 07, 09 e 10 serão prioritários ao encontrar o perfil(campo 05) e os campos 11 e 12 não são utilizados pois são para edição de cobranças.

Exemplo cobrança de terminal apenas com perfil:

csv

csv 006;descricao da cobranca;01234567891,descricao da loja;NOMINAL,1000;0a22e7b0-2601-4d0a-a381-3eddbefcc485;;;123,456,789,modelo terminal;;;;
Nota: Neste caso foram passados apenas os valores obrigatórios, tendo como premissa que os demais dados estão corretamente cadastrados dentro do perfil informado. Os campos que não foram preenchidos ainda são enviados, porém vazios e separados por 'ponto e vírgula'.

Exemplo cobrança sem terminal:

csv

csv 007;descricao da cobranca;01234567891,descricao da loja;NOMINAL,1000;0a22e7b0-2601-4d0a-a381-3eddbefcc485;10099;RECURRENCE;;10;20000;;
Nota: Neste caso os dados do campo 08 (dados do terminal) não são enviados pois a cobrança foi do tipo 007(Pinpad).

Exemplo arquivo

charge_batch_sample.jpg

7.3 - Modelo de atualização de cobranças

O modelo descrito nos itens abaixo é referente ao cadastro de cobranças.

Nota: Não é possível atualizar o cadastro de cobranças já com o status CANCELED!

7.3.1 - Descrição dos Campos Contidos no Arquivo

Para todas as cobranças a serem atualizadas via arquivo, devem seguir o seguinte formato abaixo. Em caso de campos não obrigatórios, deve ser enviado o campo vazio ou escrito 'nulo', visando sempre ter 12(doze) campos por cobrança. Como é utilizado a mesma estrutura de arquivo assim, como a de cadastro, alguns campos não devem ser enviados, conforme abaixo.

⚠️⚠️ATENÇÃO⚠️⚠️: Alguns campos abaixo expressados como não obrigatórios ou não enviar é devido os seguintes cenários:

ID NOME DO CAMPO Obrigatório DESCRIÇÃO
01 Tipo de cobrança ⚠️ Não enviar
02 Descrição ❌ Descrição da cobrança, máximo 50 caracteres
03 Dados da loja ⚠️ Não enviar
04 Dados do Desconto ❌ tipo do desconto(Conforme tabela nº2) e valor do desconto
05 ID do perfil ❌ Identificador único do perfil de cobrança
06 Meta de vendas do terminal ❌ Meta de vendas do terminal para isenção
07 Tipo de recorrêcia ⚠️ Não enviar
08 Dados do terminal ⚠️ Não enviar
09 Tempo de carência ❌ Número de dias de carência onde não será cobrado o uso do terminal
10 Valor da cobrança ❌ Valor da cobrança em centavos
11 ID da cobrança ✅ Identificador único da cobrança a ser editada
12 Status da cobrança ❌ Status da cobrança

Nota: Em valores expressando grandezas monetárias ou percentuais, faz-se necessário o envio do campo no formato RealCentavo. Exemplo de 10(dez) reais, os centavos devem vir juntos, sem pontuação sendo 1000.
Já no caso de 10(dez) reais e 50(cinquenta) centavos espera-se 1050 e no caso de 10(dez) centavos basta 10. No caso das porcentagens, 10% (dez porcento) deve vir 1000, se fossem 10,5% seriam 1050 e meio porcento apenas 50.

Nota 2: Quaisquer campo descritivo, não deve utilizar acentuação e 'Ç' (cedilha);

7.3.2 - Exemplo de arquivo:

Dados para exemplo arquivo csv.

Exemplo cobrança de terminal com todos os campos:

csv

csv ;descricao da cobranca;;NOMINAL,1000;0a22e7b0-2601-4d0a-a381-3eddbefcc485;10099;;;10;20000;0a22e7b0-2601-4d0a-a381-3eddbefcc654;ACTIVE
Nota: Neste caso os dados dos campos 06, 09 e 10 serão prioritários ao encontrar o perfil(campo 05) e os campos 11 e 12 são utilizados para edição de cobranças.

Exemplo cobrança de terminal apenas com perfil:

csv

csv ;;;;0a22e7b0-2601-4d0a-a381-3eddbefcc485;;;;;;0a22e7b0-2601-4d0a-a381-3eddbefcc654;
Nota: Neste caso foram passados apenas os identificadores únicos, do perfil e da cobrança, tendo como premissa que os dados desejáveis a serem atualizados estão contidos dentro do perfil, já préviamente cadastrado de forma correta. Os campos que não foram preenchidos ainda são enviados, porém vazios e separados por 'ponto e vírgula'.

Exemplo arquivo

charge_batch_udpate_sample.jpg

8 - Listar arquivos csv de cadastro em lote

Para listar arquivos já encaminhados deve ser consumida a API abaixo.

📌 Requisição

🛠 Método: GET
🔗 URL: 

https://api-hml.gsurfnet.com/gs-charge/upload-file/{id}

Request

Path Parameters

Parâmetro Tipo Obrigatório Descrição
id string ❌ Identificador do arquivo (UUID)

Query Parameters

Query parameters utilizados caso não seja utilizado o path parameter id. Caso não informado nenhum query parameter, retorna todos os arquivos enviados, de forma paginada.

Parâmetro Tipo Obrigatório Descrição
initial_date string ❌ Data inicial de busca YYYY-MM-DDTHH:MM:SS
final_date string ❌ Data final de busca YYYY-MM-DDTHH:MM:SS
order string ❌ Ordenação do retorno da paginação
limit string ❌ Limite de IEC por paginação
c string ❌ Token de paginação

Valores Permitidos para order

Responses

Código Descrição
200 OK (Encontrado com sucesso)
404 Not Found (Não encontrado)
500 Internal Server Error (Erro interno no servidor)

9 - Tabelas

Abaixo seguem tabelas referidas acima na documentação, contendo valores variantes de cada campo

Tabela 1 – Tipos de cobrança

Identificador Descrição do tipo de cobrança
006 Charge: Cobrança normal, vinculada a um terminal.
007 Pinpad: Cobrança sem vínculo de terminal.
008 Smart POS: Cobrança sem vínculo de terminal.
009 Property Insurance: Cobrança sem vínculo de terminal.
010 Health Care: Cobrança sem vínculo de temrinal.

Tabela 2 – Tipos de Desconto

Identificador Descrição do tipo de desconto
NOMINAL Nominal, o valor real do desconto.
PERCENT Percentual, o valor percentual do desconto.

Tabela 3 – Tipos de recorrência

Identificador Descrição do tipo de recorrência
RECURRENCE Recorrente, será recriada todo mês.
UNIQUE Única, não será recriada.

Tabela 4 – Tipos de status de processamento

Identificador Descrição do tipo de status
NEW Novo, ainda não processado.
INVALID_TYPE Tipo inválido.
INVALID_SIZE Tamanho inválido.
INVALID_HASH Hash inválido.
INTERNAL_ERROR Erro interno do servidor.
INFECTED_FILE Arquivo infectado.
INVALID_LAYOUT Layout inválido.
PROCESSED Processado.

Tabela 5 – Tipos de erros de processamento

Identificador Descrição do tipo de erro de processamento
Failed to parse the row, expected 12 columns but received X. linha com nº de colunas incorreto.
Failed to parse row, cannot receive charge_type with charge_id or status. Recebido campos tipo de cobrança com identificador único da cobrança e/ou status da cobrança.
Discount value cannot be negative. Valor do disconto negativo.
Merchant description is required. Descrição de loja requerida.
The following fields are required when profile is not provided: waiting_period, amount, recurrence or habituality_amount Campos período de carência, valor, recorrência ou valor de meta não foram providenciadas sem perfil.
Provided profile not found. Perfil providenciado não encontrado.
X is required Perfil encontrado, porém período de carência, valor, recorrência e/ou meta não encontrados.
Terminal data provided to charge type X Dado de terminal provido para tipo de cobrança diferente de "006"(cobrança de terminal).
Terminal already in use by other merchant. Terminal já cadastrado com cobrança ativa.
Discount Data cannot be null. Dado de desconto não providenciado.
Invalid length for discount data. Total de campos de dado de disconto diferente de dois.
Merchant Data cannot be null Dados da loja nulo.
Invalid length for merchant data. Total de cmapos de dado de loja diferente de dois.
Invalid merchant document Documento de loja inválido.
Invalid length for terminal data. Total de campos de dado de terminal diferente de quatro.
Failed to parse habituality_amount Falha ao tratar valor fornecido de meta.
Habituality amount value cannot be negative. Valor de meta negativo.
Failed to parse amount Falha ao tratar valor fornecido de valor da cobrança.
Amount value cannot be negative. Valor de cobrança negativo.
Failed to parse waiting_period Falha ao tratar valor de período de carência.
Waiting period value cannot be negative. Valor de período de carência negativo.
Provided charge not found. Cobrança fornecida não encontrada.
Cannot edit CANCELED charge. Não é possível editar cobrança CANCELADA.
The following provided field is invalid to update charge, field: charge_type. Tipo de cobrança fornecido ao tentar atualizar cobrança.
The following provided field is invalid to update charge, field: terminal_data. Dado de terminal fornecido ao tentar atualizar cobrança.
The following provided field is invalid to update charge, field: recurrence. Recorrência fornecida ao tentar atualizar cobrança.
The following provided field is invalid to update charge, field: merchant_data. Dado de loja fornecido ao tentar atualizar cobrança.