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

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ções de API

Observação: Remover o -hml das URLs caso seja produção

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

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

#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

#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

#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

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

#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

#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

#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

#Introdução

#Acesso às APIs

#Passos para criar um App Client

#📌 Requisições de API

#📌 Requisição Token

#Autenticação: Basic Auth

#1 - 🏢 Cadastrar Estabelecimento

#📌 Requisição

#Body

#Valores Permitidos para status

#Responses

#2 - 🏦 Cadastrar Dado Bancário no Provedor

#📌 Requisição

#Path Parameters

#Valores Permitidos para provider

#Body

#Valores Permitidos para account_type

#Responses

#3 - 🔄 Cadastrar Roteamento de Liquidação

#📌 Requisição

#Path Parameters

#Body

#Valores Permitidos para cada tipo de roteamento

#Responses

#Cadastro via Portal

#4 - 🎌 Cadastrar Feriado

#📌 Requisição

#Body

#Responses

#Cadastro via Portal

#5 - 💰 Cadastrar Produto Financeiro

#📌 Requisição

#Body

#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

#Path Parameters

#Body

#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

#Valores Permitidos para `status`

#Valores Permitidos para `provider`

#Valores Permitidos para `account_type`

#Exemplo de Resposta (`200 OK`)

#Exemplo de Resposta (`200 OK`)