Integração Backoffice

Introdução

Este documento tem como objetivo guiar terceiros na integração com o Backoffice, explicando o processo de obtenção de credenciais, autenticação e consumo das APIs disponíveis.

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

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 - 🏢 Cadastrar Estabelecimento

Este endpoint cria o cadastro de um estabelecimento comercial com seus dados de liquidação.

📌 Requisição

🛠 Método: POST
🔗 URL:

https://api-hml.gsurfnet.com/receivable-units-schedule-v2/merchants

Request

Body

`application/json`

Dados para cadastro de um estabelecimento comercial.

{
  "id": "string", // O identificador do estabelecimento (CPF ou CNPJ)
  "name": "string", // Nome do estabelecimento comercial
  "company_name": "string or null", // Razão social do estabelecimento comercial (nulo para PF)
  "email": "string", // Endereço de email do estabelecimento comercial
  "mcc": "string", // Código MCC do estabelecimento comercial
  "phone": "string", // Número do telefone do estabelecimento comercial
  "status": "string", // Status do cadastro do estabelecimento
  "address": {
    "city": "string", // Nome da cidade
    "state": "string", // Sigla do estado
    "district": "string", // Nome do bairro
    "street": "string", // Nome da rua (logradouro)
    "number": "string", // Número do prédio na rua
    "zip_code": "string", // Código postal do endereço
    "complement": "string" // Dados complementares do endereço
  }
}

Valores Permitidos para `status`

ACTIVE
INACTIVE
SUSPENDED

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 - 🏦 Cadastrar Dado Bancário no Provedor

Este endpoint cadastra os dados bancários de uma loja de acordo com o provedor selecionado.

📌 Requisição

🛠 Método: POST
🔗 URL:

https://api-hml.gsurfnet.com/receivable-units-schedule-v2/merchant/{merchant_id}/bank-data/{provider}

Request

Path Parameters

Parâmetro	Tipo	Obrigatório	Descrição
`merchant_id`	`string`	✅	Identificador da loja (CPF/CNPJ)
`provider`	`string`	✅	Identificador do provedor

Valores Permitidos para `provider`

DOCK
RTM
MERCADO_PAGO
ITAU

Body

`application/json`

Entidade que contém os dados bancários.

{
  "bank_code": "string", // Código do banco
  "ispb_code": "string", // Código ISPB do banco
  "branch_code": "string", // Código da agência
  "account_code": "string", // Código da conta
  "account_type": "string", // Tipo da conta
  "holder_id": "string", // CPF ou CNPJ do titular da conta
  "holder_name": "string", // Nome do titular da conta
  "external_id": "string" // Identificador da conta no sistema do banco
}

Valores Permitidos para `account_type`

CC → Conta Corrente
PG → Conta Pagamento
CD → Conta Depósito
PP → Poupança

Responses

Código	Descrição
`200`	OK (Dado bancário cadastrado com sucesso)
`400`	Bad Request (Erro nos parâmetros da requisição)
`500`	Internal Server Error (Erro interno no servidor)

3 - 🔄 Cadastrar Roteamento de Liquidação

É feita pela GSURF a nível de sub, mas existe a possibilidade ser feita por EC, conforme abaixo:

Este endpoint cadastra uma configuração de roteamento na loja.

📌 Requisição

🛠 Método: POST
🔗 URL:

https://api-hml.gsurfnet.com/receivable-units-schedule-v2/merchant/{merchant_id}/routing

Request

Path Parameters

Parâmetro	Tipo	Obrigatório	Descrição
`merchant_id`	`string`	✅	Identificador da loja

Body

`application/json`

Configuração de roteamento de liquidação.

{
  "ANTECIPATION": "string", // Provedor de antecipação
  "CREDIT": "string", // Provedor de crédito
  "DEBIT": "string", // Provedor de débito
  "GENERIC": "string", // Provedor genérico
  "PIX": "string", // Provedor de PIX
  "REFUND": "string", // Provedor de estorno
  "SLIP": "string" // Provedor de boleto
}

Valores Permitidos para cada tipo de roteamento

ITAU
DOCK
RTM
MERCADO_PAGO

Responses

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

Cadastro via Portal

Via portal, é possível efetuar o cadastro acessando conforme imagem abaixo:

dadosDeLiquidação.jpg

4 - 🎌 Cadastrar Feriado

Este endpoint adiciona um feriado ao sistema.

📌 Requisição

🛠 Método: POST
🔗 URL:

https://api-hml.gsurfnet.com/settlement-v2/holidays

Request

Body

`application/json`

Entidade que representa um feriado.

{
  "month": 1, // Número do mês (1 a 12)
  "day": 25   // Número do dia (1 a 31)
}

Responses

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

Cadastro via Portal

Via portal, é possível efetuar o cadastro acessando conforme imagem abaixo:

5 - 💰 Cadastrar Produto Financeiro

Este endpoint permite o cadastro de um produto financeiro.

📌 Requisição

🛠 Método: POST
🔗 URL:

https://api-hml.gsurfnet.com/settlement-v2/product

Request

Body

`application/json`

Entidade que representa um produto financeiro.

{
  "transaction_type_id": "string", // Tipo de transação (Obrigatório)
  "card_brand": "string", // Tipo do cartão
  "channel": "string", // Canal da transação
  "settlement_term": 30, // Prazo de liquidação (Obrigatório)
  "working_days_only": true, // Considera apenas dias úteis no calculo de dias até a liquidação. O padrão é não habilitar. 
  "must_antecipate": false, // Indica se deve antecipar automaticamente os recebíveis
  "antecipation_term": 15, // Prazo de antecipação
  "subsidy_term": 10, // Dias sem cobrança de taxa de antecipação.
  "acquirer": 1, // Adquirente da transação
  "transaction_fee": 3, // Taxa da transação (Obrigatório)
  "mcc_code": "string", // Código MCC do estabelecimento
  "description": "string", // Descrição do produto financeiro (Obrigatório)
  "antecipation_rate": 2, // Taxa mensal de antecipação
  "split": "SPLIT", // Configuração de split aplicada ao produto
  "product_type": "GENERAL", // Tipo de produto
  "settlement_schedule_type": "WEEKLY", // Tipo de liquidação
  "settlement_schedule_day": 2, // Dia da semana para liquidação (0 a 4)
  "mdr_tax": 10 // Taxa aplicada sobre o já calculado MDR (1% a 100%)
}

Valores Permitidos

split: SPLIT, NO_SPLIT, BOTH
product_type: GENERAL, RESTRICTED
settlement_schedule_type: DEFAULT, WEEKLY, BIWEEKLY, MONTHLY
settlement_schedule_day: 0 (Segunda-feira) a 4 (Sexta-feira)
mdr_tax: Valores entre 1 e 100 (representando percentual)

Responses

Código	Descrição
`200`	OK (Produto cadastrado com sucesso)
`400`	Bad Request (Erro nos parâmetros da requisição)
`500`	Internal Server Error (Erro interno no servidor)

Exemplo de Resposta (`200 OK`)

{
  "statusCode": 200,
  "body": {
    "transaction_type": "CREDIT",
    "id": "123456",
    "card_brand": null,
    "settlement_term": null,
    "channel": null,
    "working_days_only": true,
    "must_antecipate": false,
    "antecipation_term": 15,
    "subsidy_term": 10,
    "acquirer": null,
    "transaction_fee": 3,
    "mcc_code": null,
    "description": null,
    "antecipation_rate": 2,
    "split": "SPLIT",
    "created_at": "2024-03-11T12:00:00Z",
    "product_type": "GENERAL",
    "ranges": []
  }
}

Cadastro via Portal

Via portal, é possível efetuar o cadastro acessando conforme imagem abaixo:

📌 Seleção do produto financeiro pela transação

Os produtos financeiros definem taxas de MDR, antecipação e são essenciais para a geração de recebíveis no sistema de liquidação (settlement). Para que uma transação gere recebíveis, é obrigatório que pelo menos um produto esteja cadastrado para o tipo de pagamento correspondente.

Processo de Seleção

Quando uma transação confirmada chega ao settlement, o sistema aplica um modelo de prioridade para determinar qual produto financeiro será usado. A priorização ocorre na seguinte ordem:

Produtos do grupo financeiro: Se a loja pertencer a um grupo, os produtos desse grupo terão prioridade.
Produtos da loja: Caso não exista um produto adequado no grupo financeiro, o sistema busca os produtos cadastrados diretamente para a loja.
Produtos gerais: Se nenhuma das opções anteriores atender à transação, o sistema verifica os produtos gerais, que não estão vinculados a uma loja ou grupo específico.

Critérios para Seleção

Dentro de cada categoria, a escolha do produto segue os critérios abaixo:

Critério	Descrição
Tipo de pagamento	Pix, crédito, débito, entre outros.
Canal da transação	E-commerce, POS, presencial, etc.
Bandeira do cartão	Mastercard, Visa, Elo, etc.
Adquirente	REDE, Cielo, Stone, etc.
Presença de split	Se a transação envolve divisão de valores.
Número de parcelas	Parcelamento permitido para a transação.

Caso existam múltiplos produtos dentro da mesma categoria, o sistema utiliza um critério de prioridade para selecionar aquele que melhor corresponde às características da transação. Se nenhum produto atender, a transação não gera recebíveis.

Garantia de Controle

O sistema assegura que cada transação seja corretamente associada a um produto financeiro, garantindo um controle eficiente da liquidação e respeitando todas as regras configuradas.

Cálculo da taxa de antecipação

Utilizando os valores abaixo como exemplo de cálculo:

Bruto: R$1.000,00
MDR: 3.84%
Parcelas: 2
Taxa de Antecipação: 1.5%
Subsídio: 29 dias
Prazo de Liquidação da Primeira Parcela: 31 dias

Cálculo do Valor Líquido com Antecipação para 2 Parcelas

Valor Bruto Total: R$ 1000,00.
Taxa MDR (3,84%):
MDR = 1000 * 0.0384 = R$ 38,40
Valor Líquido após MDR:
Valor Líquido = 1000 - 38,40 = R$ 961,60
Valor por Parcela (dividido em 2 parcelas):
Valor por Parcela = 961,60 / 2 = R$ 480,80

Taxa de Antecipação:
- Taxa de Antecipação: 1,5% dividida por 30 dias:
Taxa Diária = 0,015 / 30 = 0,0005

Prazo de Liquidação da Primeira Parcela: A primeira parcela não possui taxa de antecipação, devido ao subsídio de 29 dias.
Prazo de Liquidação da Segunda Parcela: Valor Líquido da Segunda Parcela = Valor da Parcela / (1 + Taxa Diária)^Dias

Substituindo os valores:

Valor Líquido da Segunda Parcela = 480,80 / (1 + 0,0005)^{30}

Valor Líquido da Segunda Parcela = 480,80 / (1,0005)^30

Resultado:

Valor Líquido da Segunda Parcela = R$ 473,64

Planilha de cálculo (para fazer simulações):

https://docs.google.com/spreadsheets/d/1CpA19HCSWsaXlpQ7L236x4sf2aMM8ICh/edit?usp=sharing&ouid=118108620189834621465&rtpof=true&sd=true

6 - 🏦 Cadastrar Configuração de Parcela

Este endpoint cadastra um range de parcelas para um determinado produto financeiro.

📌 Requisição

🛠 Método: POST
🔗 URL:

https://api-hml.gsurfnet.com/settlement-v2/product/{id}/range-config

Request

Path Parameters

Parâmetro	Tipo	Obrigatório	Descrição
`id`	`string`	✅	UUID do produto

Body

`application/json`

Entidade que representa a configuração de range de parcelas.

{
  "range_begin": 1, // Parcela inicial do range (Obrigatório)
  "range_end": 12, // Parcela final do range (Obrigatório)
  "transaction_rate": 2.5, // Taxa fixa aplicada à transação (Obrigatório)
  "installment_rate": 1.2, // Taxa aplicada por parcela (Obrigatório)
  "brands_config": [ 
    {
      "brand_id": 1, // Identificador da bandeira do cartão (Obrigatório)
      "transaction_rate": 2.0, // Taxa percentual fixa (Obrigatório)
      "installment_rate": 1.0 // Taxa por parcela (Obrigatório)
    }
  ]
}

Restrições e Valores Permitidos

begin e end: Valores entre 1 e 99 (define o intervalo de parcelas permitido).
transaction_rate e installment_rate: Valores entre 0 e 100 (representando percentual de taxa).
brand_id: Deve ser um número maior que 0.

Consultar ids dos arranjos: https://gsurf.stoplight.io/docs/povig/9a25a9ada4265-arquivo-de-agenda-e-liquidacao-sc-3#tabela-5---arranjos-de-pagamento

Responses

Código	Descrição
`200`	OK (Configuração de parcela cadastrada com sucesso)
`400`	Bad Request (Erro nos parâmetros da requisição)
`500`	Internal Server Error (Erro interno no servidor)

Exemplo de Resposta (`200 OK`)

{
  "statusCode": 200,
  "body": {
    "id": "abcd1234-ef56-7890-gh12-ijkl34567890",
    "range_begin": 1,
    "range_end": 12,
    "transaction_rate": 2.5,
    "installment_rate": 1.2,
    "brands_config": [
      {
        "brand_id": 1,
        "transaction_rate": 2.0,
        "installment_rate": 1.0
      }
    ]
  }
}

Atrelar produto financeiro a um EC

Este endpoint atrela um ou mais ECs a um ou mais produtos financeiros:

📌 Requisição

🛠 Método: POST
🔗 URL:

https://api-hml.gsurfnet.com/settlement-v2/merchants/products

Body (Exemplo JSON):

{
    "merchants": [
        "{{id_ec}}" // CPF ou CNPJ do EC
    ],
    "products": [
        "{{id_product}}" // ID do produto criado
    ]
}

Cadastro via Portal

Via portal, é possível efetuar o cadastro acessando conforme imagem abaixo:

7 - 💰 Criar Recebível

Este endpoint permite o recebimento de dados para criação de um recebível manualmente.

📌 Requisição

🛠 Método: POST
🔗 URL:

https://api-hml.gsurfnet.com/settlement-v2/create-receivable

7.1 Estrutura da Requisição

Headers:

Content-Type: application/json
Authorization: Bearer {access_token}

Body (Exemplo JSON):

{
  "transactions": [
    {
      "model": "TEF",
      "payment_data": {
        "amount": 1000
      },
      "split_data": [],
      "channel": "ECOMMERCE",
      "merchant_id": "12345678901234",
      "transaction_id": "txn_001",
      "order_id": "order_001",
      "merchant_usn": "1234",
      "tef_data": {
        "acquirer_id": 1,
        "transaction_type": "CREDIT",
        "authorization_time": "2024-08-26T08:00:00",
        "card_brand_id": 55,
        "installments_number": 3,
        "nsu_host_authorization": "56789",
        "nsu_host_confirmation": "67890",
        "confirmation_time": "2024-08-26T08:10:00",
        "masked_card": "520626******9101",
        "capture_mode": "ECOMMERCE",
        "auth_code": "123456",
        "merchant_code": "M12345",
        "nsu_provider": "45678",
        "tid": "TID123",
        "source": "GS_PAYMENT"
      }
    }
  ]
}

7.2 Parâmetros Importantes

Parâmetro	Tipo	Obrigatório	Descrição
`transactions`	array	✅	Lista de transações (1 a 20 itens).
`model`	string	✅	Modelo da transação (TEF).
`amount`	integer	✅	Valor total da transação (ex: 1000 = R$ 10,00).
`merchant_id`	string	✅	CPF ou CNPJ do lojista (11 a 14 caracteres).
`transaction_id`	string	❌	Identificador único da transação.
`order_id`	string	✅	Identificador único do pedido.
`merchant_usn`	string	✅	NSU do lojista (4 a 20 caracteres).
`acquirer_id`	integer	✅	Identificador da adquirente.
`transaction_type`	string	✅	Tipo da transação (CREDIT, DEBIT).
`authorization_time`	string	✅	Data e hora da transação.
`card_brand_id`	integer	✅	Identificador da bandeira do cartão.
`installments_number`	integer	✅	Quantidade de parcelas.
`masked_card`	string	✅	Número do cartão mascarado (ex: 5206269101).
`capture_mode`	string	✅	Modo de captura (ECOMMERCE, POS, MANUAL, PDV, URA, UNDEFINED).
`auth_code`	string	✅	Código de autorização (6 caracteres).
`source`	string	✅	Sistema que originou a transação (GS_PAYMENT, SITEF, EXTERNAL).

7.3 Respostas Possíveis

🟢 200 - Sucesso

{
  "statusCode": 200,
  "body": "Recebível criado com sucesso."
}

🔴 Erros Comuns

Código	Motivo
400	Requisição inválida (parâmetros ausentes ou incorretos).
401	Token de autenticação inválido ou expirado.
403	Permissão negada para a ação solicitada.
404	Recurso não encontrado.
500	Erro interno no servidor.

🧭 Navegação e Interpretação dos Relatórios de Liquidação

A tela abaixo é acessada para visualizar os recebimentos de um determinado cliente (CPF/CNPJ).
Seu acesso se dá pelo menu: Relatório > Liquidação > Detalhes EC

🔒 Situação da Liquidação

No painel de situação da liquidação, é possível bloquear o recebimento de valores para o cliente clicando no ícone de cadeado.
As informações da conta bancária do cliente também estão disponíveis nessa seção.

📄 Relatório 1 – Pagamentos

Exibe as remessas já pagas ao cliente.
Funciona como um extrato bancário consolidado das liquidações realizadas.

📊 Relatório 2 – Recebíveis

Apresenta o detalhamento das transações que compõem os pagamentos.
Os valores ainda não estão agrupados por arranjo (bandeira).
Não representa exatamente como o cliente vê os pagamentos na conta bancária.
Útil para análise detalhada da origem dos valores.

📄 Relatório 3 – Ajustes na Liquidação

Similar ao primeiro relatório, mas com destaque para ajustes.
Inclui:
Estornos de transações.
Débitos manuais aplicados pela UR.
Exibe os valores ajustados que impactaram o valor final pago ao cliente.

Integração Backoffice

Integração Backoffice

Introdução

Acesso às APIs

Passos para criar um App Client:

📌 Requisição Token

Autenticação: Basic Auth

1 - 🏢 Cadastrar Estabelecimento

📌 Requisição

Request

Body

application/json

Valores Permitidos para status

Responses

2 - 🏦 Cadastrar Dado Bancário no Provedor

📌 Requisição

Request

Path Parameters

Valores Permitidos para provider

Body

application/json

Valores Permitidos para account_type

Responses

3 - 🔄 Cadastrar Roteamento de Liquidação

📌 Requisição

Request

Path Parameters

Body

application/json

Valores Permitidos para cada tipo de roteamento

Responses

Cadastro via Portal

4 - 🎌 Cadastrar Feriado

📌 Requisição

Request

Body

application/json

Responses

Cadastro via Portal

5 - 💰 Cadastrar Produto Financeiro

📌 Requisição

Request

Body

application/json

Valores Permitidos

Responses

Exemplo de Resposta (200 OK)

Cadastro via Portal

📌 Seleção do produto financeiro pela transação

Processo de Seleção

Critérios para Seleção

Garantia de Controle

Cálculo da taxa de antecipação

6 - 🏦 Cadastrar Configuração de Parcela

📌 Requisição

Request

Path Parameters

Body

application/json

Restrições e Valores Permitidos

Responses

Exemplo de Resposta (200 OK)

Atrelar produto financeiro a um EC

📌 Requisição

Body (Exemplo JSON):

Cadastro via Portal

7 - 💰 Criar Recebível

📌 Requisição

7.1 Estrutura da Requisição

Headers:

Body (Exemplo JSON):

7.2 Parâmetros Importantes

7.3 Respostas Possíveis

🟢 200 - Sucesso

🔴 Erros Comuns

🧭 Navegação e Interpretação dos Relatórios de Liquidação

🔒 Situação da Liquidação

📄 Relatório 1 – Pagamentos

📊 Relatório 2 – Recebíveis

📄 Relatório 3 – Ajustes na Liquidação

`application/json`

Valores Permitidos para `status`

Valores Permitidos para `provider`

`application/json`

Valores Permitidos para `account_type`

`application/json`

`application/json`

`application/json`

Exemplo de Resposta (`200 OK`)

`application/json`

Exemplo de Resposta (`200 OK`)