Consulta de Transações (API)

🔹 Visão Geral

Este documento descreve os endpoints disponíveis para consulta de transações no gateway Gsurf, incluindo transações de cartão, pagamentos (cartão e boleto), pagamentos via Pix e boletos registrados. Todos os endpoints seguem o padrão REST e requerem autenticação via token.

Base URL: https://api-hml.gsurfnet.com/transactions-v2/

---

🔸 GET /transactions

Consulta de transações realizadas.

📥 Parâmetros de Query (principais)

Parâmetro	Tipo	Obrigatório	Descrição
acquirer_id	string	❌	ID do adquirente
authorization_code	string	❌	Código de autorização
customer_id	string	❌	CPF ou CNPJ do cliente
final_date	string	✅	Data final no formato YYYY-MM-DDTHH:mm:ss
initial_date	string	✅	Data inicial no formato YYYY-MM-DDTHH:mm:ss
return_count	string	❌	0 ou 1. Define se o total de registros deve ser retornado
status_id	string	❌	Status da transação
limit	string	❌	Máximo de registros por página (até 2000)
page	string	❌	Página desejada
...	...	...	Diversos outros parâmetros estão disponíveis para filtros avançados.

✅ Resposta 200 OK

{
  "statusCode": 200,
  "body": {
    "total": 10,
    "page": 1,
    "limit": 100,
    "records": [ /* lista de transações */ ]
  }
}

---

🔸 GET /payments

Consulta de pagamentos com cartão e boleto (sem reembolsos).

📥 Parâmetros de Query

Parâmetro	Tipo	Obrigatório	Descrição
customer_id	string	❌	CPF/CNPJ do recebedor
limit	integer	❌	Registros por página (até 2000)
page	integer	❌	Página
order_by	string	❌	Campos para ordenação (ex: creation_date:desc)
initial_date	string	✅	Data inicial do período
final_date	string	✅	Data final do período

✅ Resposta 200 OK

{
  "statusCode": 200,
  "body": {
    "total": 2,
    "page": 1,
    "limit": 50,
    "records": [ /* lista de pagamentos */ ]
  }
}

---

🔸 GET /pix

Consulta de pagamentos via Pix (sem reembolsos).

📥 Parâmetros de Query

Mesmo formato do endpoint /payments, com possibilidade de filtro adicional por sub_order_id.

✅ Resposta 200 OK

{
  "statusCode": 200,
  "body": {
    "total": 3,
    "page": 1,
    "limit": 50,
    "records": [ /* lista de pagamentos via Pix */ ]
  }
}

---

🔸 GET /slips

Consulta de boletos registrados.

📥 Parâmetros de Query

Mesmo formato do endpoint /payments, com possibilidade de filtro adicional por due_date, import_date, reconciliation_status e sub_order_id.

✅ Resposta 200 OK

{
  "statusCode": 200,
  "body": {
    "total": 5,
    "page": 1,
    "limit": 50,
    "records": [ /* lista de boletos */ ]
  }
}

---

🔐 Autenticação

Todos os endpoints requerem um token válido no cabeçalho da requisição:

Authorization: Bearer {access_token}

Tokens são obtidos via endpoint POST /gmac-v1/oauth2/token com clientId e clientSecret.

---

🧾 Observações

• A resposta pode ser paginada. Use os parâmetros page e limit para navegação.
• Para grandes volumes, ative return_count=1 para receber o total de registros (pode impactar performance).
• Todos os endpoints aceitam response_utc_offset para ajustar fuso horário das datas retornadas.

---