#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.

#Criação de App Client

Acesse o portal SC3 (HML ou PROD):

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

https://portal.gsurfnet.com/

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

Selecione os endpoints conforme imagem abaixo:

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).

#📌 Requisição Token

🛠 Método: POST
🔗 URL:

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

#Autenticação: Basic Auth

Username = clientId
Password = clientSecret

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

UNIQUE
RECURRENCE

Valores Permitidos para type (discount)

NOMINAL
PERCENT

Valores Permitidos para charge_type

"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.

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)

NOMINAL
PERCENT

Valores Permitidos para status

ACTIVE
BLOCKED
CANCELED
DONE

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

UNIQUE
RECURRENCE

#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

UNIQUE
RECURRENCE

#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

"ASC" Retorna a paginação em ordem ascendente de acordo com o tipo de data informado.
"DESC" Retorna a paginação em ordem decrescente de acordo com o tipo de data informado.

#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 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

"ASC" Retorna a paginação em ordem ascendente de acordo com o tipo de data informado.
"DESC" Retorna a paginação em ordem decrescente de acordo com o tipo de data informado.

#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:

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:

O campo 05 é opcional, não é necessário o vínculo de um perfil a uma cobrança;
O campo 08 somente deve ser preenchido caso cobrança seja do tipo Charge;
Os campos 06, 07, 09 e 10 somente são opcionais caso esses valores já se encontrem cadastrados dentro do perfil encontrado pelo Identificador único no campo 05;
O dado do campo 06 faz-se necessário o envio mesmo em cobranças 007, 008, 009 e 010, nesses casos deve ser enviado zerado.
Caso os campos 05, 06, 07, 09 e 10 forem passados juntos, ao criar a cobrança será dado prioridade aos valores fora do perfil.
Os campos 11 e 12 somente devem ser utilizados no caso de edição de cobranças!

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 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

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

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

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

#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:

O campo 05 é opcional, não é necessário o vínculo de um perfil a uma cobrança;
Os campos 01, 03, 07 e 08 não devem ser enviado para o cenário de atualização de cobranças;
Os campos 06, 09 e 10 somente são opcionais caso esses valores já se encontrem cadastrados dentro do perfil encontrado pelo Identificador único no campo 05;
Caso os campos 05, 06, 09 e 10 forem passados juntos, ao atualizar a cobrança será dado prioridade aos valores fora do perfil.

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 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

;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

;;;;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

#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

"ASC" Retorna a paginação em ordem ascendente de acordo com o tipo de data informado.
"DESC" Retorna a paginação em ordem decrescente de acordo com o tipo de data informado

#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.

Integração Módulo de cobranças

#Introdução

#Acesso às APIs

#Criação de App Client

#📌 Requisição Token

#Autenticação: Basic Auth

#1 - Cobranças

#1.1 - Cadastro de cobranças

#📌 Requisição

#Responses

#1.2 - Listagem de cobranças

#📌 Requisição

#Responses

#1.3 - Edição de cobrança

#📌 Requisição

#Responses

#1.4 - Cobranças em lote

#📌 Requisição

#Responses

#2 - Perfil de cobranças

#2.1 - Cadastro de Perfil

#📌 Requisição

#Responses

#2.2 - Listagem de Perfil

#📌 Requisição

#2.3 - Edição de Perfil

#📌 Requisição

#Responses

#3 - Isenção de Estabelecimento Comercial

#3.1 - Cadastro de Isenção de Estabelecimento Comercial

#📌 Requisição

#Responses

#3.2 - Listagem de Isenção de Estabelecimento Comercial

#📌 Requisição

#Responses

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

#📌 Requisição

#Responses

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

#📌 Requisição

#Responses

#4 - Grupo de Isenção de Estabelecimento Comercial

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

#📌 Requisição

#Responses

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

#📌 Requisição

#Responses

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

#📌 Requisição

#Responses

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

#📌 Requisição

#📌 Requisição

#Responses

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

#📌 Requisição

#Responses

#5 - Registro Totalizador

#5.1 - Listagem de Registro Totalizador

#📌 Requisição

#Responses

#6 - Relatório de Cobranças

#6.1 - Criação do arquivo

#📌 Requisição

#Responses

#6.2 - Listagem de Relatórios de cobranças

#📌 Requisição

#Responses

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

#📌 Requisição

#Responses

#7 - Arquivo de cobranças em lote

#7.1 - Nomenclatura e Convenções

#7.2 - Modelo de cadastro de cobranças

#7.2.1 - Descrição dos Campos Contidos no Arquivo

#7.2.2 - Exemplo de arquivo:

#Exemplo arquivo

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

#7.3.1 - Descrição dos Campos Contidos no Arquivo