mng-fee-merchant-adp
Gerencial API — Fee Merchant Adapter Version2.0.3· Java 17 · Spring Boot 3.5.14
Overview
mng-fee-merchant-adp is a RESTful adapter microservice responsible for exposing acquisition fee data associated with merchants registered in the Getnet platform. It acts as an intermediary layer between internal consumers (front-end portals, BFFs, or other microservices) and the upstream Getnet fee management system, translating the internal domain model into a standardised, OpenAPI-compliant response format.The service empowers partners and merchants to consult their active acquisition fees independently, increasing autonomy in negotiations and improving operational efficiency.
Functional Responsibilities
| Responsibility | Description |
|---|---|
| Fee retrieval | Fetches acquisition fee data for a given merchant from the upstream Getnet API |
| Data transformation | Maps the internal Getnet DTO model to an OpenAPI-compliant DTO model using MapStruct |
| Error handling | Returns structured error responses (timestamp, status, error, message, path) for 404, 500, and other HTTP error scenarios |
| Observability | Exposes health, info, metrics, env, loggers, thread dump, mappings, and beans via Spring Boot Actuator |
| API documentation | Provides interactive API documentation via Swagger UI (SpringDoc OpenAPI) |
API Endpoint
GET /fee-merchant/v1/merchants/{id}
Retrieves the acquisition fee data for a specific merchant, with optional filters.
Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| id | Long | ✅ | Unique merchant identifier |
Query Parameters (Filters)
| Parameter | Type | Required | Allowed Values |
|---|---|---|---|
| commercial_mode_id | List<Long> | ❌ | 1 = RENT, 2 = SALE |
| operator_id | List<Long> | ❌ | 141 = MASTERCARD, 154 = VISA, 229 = AMEX, 230 = ELO, 231 = HIPERCARD |
| capture_method_fee_id | List<Long> | ❌ | 63 = IATA, 45 = E-COMMERCE, 13 = VERMELHINHA, 99 = CONVENCIONAL, 74 = SUPERGET, 77 = QRCODE |
Request Headers
| Header | Type | Required | Description |
|---|---|---|---|
| app-user | Long | ✅ | Application user identifier (authorization & audit) |
| system-user | Long | ❌ | System user identifier (audit & traceability) |
Response Codes
| Code | Description |
|---|---|
| 200 OK | Fee data retrieved successfully |
| 400 Bad Request | Invalid request parameters |
| 401 Unauthorized | Missing or invalid authentication credentials |
| 403 Forbidden | Insufficient permissions to access the resource |
| 404 Not Found | Merchant not found for the given ID |
| 409 Conflict | Conflict with the current state of the resource |
| 500 Internal Server Error | Unexpected server-side error |
| 504 Gateway Timeout | Upstream service did not respond in time |
Response Model
EstablishmentDTO
text
{
"merchant_id": 123456,
"pre_registration_id": 654321,
"document": "12345678000199",
"payment_plan": "Standard Plan",
"operators": [
{
"operator_id": 154,
"operator_description": "VISA",
"fees": [
{
"commercial_mode_id": 1,
"commercial_mode_description": "RENT",
"capture_method_fees": [
{
"capture_method_fee_id": 99,
"capture_method_fee_description": "CONVENCIONAL",
"sales_plans": [
{
"installments": 1,
"fee_percentage": 2.35
}
]
}
]
}
]
}
]
}
text
{
"merchant_id": 123456,
"pre_registration_id": 654321,
"document": "12345678000199",
"payment_plan": "Standard Plan",
"operators": [
{
"operator_id": 154,
"operator_description": "VISA",
"fees": [
{
"commercial_mode_id": 1,
"commercial_mode_description": "RENT",
"capture_method_fees": [
{
"capture_method_fee_id": 99,
"capture_method_fee_description": "CONVENCIONAL",
"sales_plans": [
{
"installments": 1,
"fee_percentage": 2.35
}
]
}
]
}
]
}
]
}
Error Response Model
text
{
"timestamp": "2026-05-15T18:07:45.425707849",
"status": 404,
"error": "NOT_FOUND",
"message": "Merchant 645541 not found.",
"path": "/fee-merchant/v1/merchants/645541"
}
text
{
"timestamp": "2026-05-15T18:07:45.425707849",
"status": 404,
"error": "NOT_FOUND",
"message": "Merchant 645541 not found.",
"path": "/fee-merchant/v1/merchants/645541"
}
Architecture
text
Consumer (BFF / Portal)
│
▼
┌─────────────────────────────┐
│ FeeMerchantController │ REST layer — receives and validates HTTP requests
└────────────┬────────────────┘
│
▼
┌─────────────────────────────┐
│ FeeMerchantService │ Business layer — orchestrates the upstream call,
│ │ handles errors, and triggers mapping
└────────────┬────────────────┘
│ RestTemplate (HTTP 600;">GET)
▼
┌─────────────────────────────┐
│ Getnet Upstream API │ Internal fee management system (EstabelecimentoDTO)
└────────────┬────────────────��
│
▼
┌─────────────────────────────┐
│ EstablishmentMapper │ MapStruct — converts EstabelecimentoDTO → EstablishmentDTO
└────────────┬────────────────┘
│
▼
HTTP 200 Response (EstablishmentDTO)
text
Consumer (BFF / Portal)
│
▼
┌─────────────────────────────┐
│ FeeMerchantController │ REST layer — receives and validates HTTP requests
└────────────┬────────────────┘
│
▼
┌─────────────────────────────┐
│ FeeMerchantService │ Business layer — orchestrates the upstream call,
│ │ handles errors, and triggers mapping
└────────────┬────────────────┘
│ RestTemplate (HTTP 600;">GET)
▼
┌─────────────────────────────┐
│ Getnet Upstream API │ Internal fee management system (EstabelecimentoDTO)
└────────────┬────────────────��
│
▼
┌─────────────────────────────┐
│ EstablishmentMapper │ MapStruct — converts EstabelecimentoDTO → EstablishmentDTO
└────────────┬────────────────┘
│
▼
HTTP 200 Response (EstablishmentDTO)
Technology Stack
| Technology | Version | Purpose |
|---|---|---|
| Java | 17 | Runtime language |
| Spring Boot | 3.5.14 | Application framework |
| Spring Boot Actuator | — | Health, info, and metrics endpoints |
| Spring Boot Validation | — | Bean Validation (Jakarta) |
| SpringDoc OpenAPI (Swagger) | 2.7.0 | API documentation & Swagger UI |
| MapStruct | 1.5.5.Final | DTO mapping |
| Lombok | — | Boilerplate reduction |
| Apache Tomcat Embed | 11.0.21 | Embedded web server |
| Logback | 1.5.19 | Structured logging |
| JUnit Jupiter | — | Unit testing |
Observability (Spring Boot Actuator)
The following actuator endpoints are exposed at the application base path (
/):| Endpoint | Description |
|---|---|
| /health | Liveness and readiness probes, disk space, and upstream checks |
| /info | Build metadata (groupId, artifactId, version, build date, Java & OS info) |
| /metrics | Application metrics |
| /env | Environment properties (values shown when authorized) |
| /loggers | Runtime log level management |
| /threaddump | Active thread dump |
| /mappings | All registered request mappings |
| /beans | All Spring beans loaded in the application context |
Health groups:
- Liveness:
livenessState,diskSpace - Readiness:
readinessState,feeMerchantUpstream
Environments
Swagger UI:
{base-url}/swagger-ui.html
OpenAPI JSON: {base-url}/api-docsRunning Locally
text
# Build the project
mvn clean package -DskipTests
# Run the application
java -jar target/mng-fee-merchant-adp-2.0.3.jar --spring.profiles.active=dev
text
# Build the project
mvn clean package -DskipTests
# Run the application
java -jar target/mng-fee-merchant-adp-2.0.3.jar --spring.profiles.active=dev
The application starts on port 8080 by default. Make sure the upstream Getnet API URL is configured inapplication-dev.ymlunder theapp.hostproperty.
Configuration
Key properties in
application.yml:| Property | Description |
|---|---|
| server.port | HTTP port (default: 8080) |
| server.servlet.context-path | API context path (/fee-merchant/v1) |
| app.host | Upstream Getnet API base URL |
| management.endpoints.web.base-path | Actuator base path (default: /) |
Contact
| Organization | Getnet |
| Website | www.getnet.com.br |
| Support e-mail | teste@getnet.com.br |
On this page
mng-fee-merchant-adp