bn-paper-rolls-adp

Adapter (ADP) responsible for intermediating paper rolls operations between Getnet's internal systems and backend services (BFF/GetConfig), exposing a standardized RESTful API for consumption by internal channels.

📋 Overview

bn-paper-rolls-adp is an adapter/BFF microservice, built with Spring Boot 3, acting as an abstraction and orchestration layer between internal consumers and the order management, stock, and manual order APIs for paper rolls.

The application centralizes responsibilities such as:

Automatic authentication with token renewal via Feign interceptor
Resilience protection with Circuit Breaker (Resilience4j)
Contract mapping and normalization between internal and external APIs
Standardized error handling via GlobalExceptionHandler

🏗️ Architecture

text

Internal Consumer
       │
       ▼
┌─────────────────────────────────┐
│         bn-paper-rolls-adp      │
│                                 │
│  Controller → Service → Client  │
│       ↕              ↕          │
│   Mapper         FeignAuthInterceptor
│       ↕              ↕          │
│   DTO            Circuit Breaker│
└─────────────────────────────────┘
       │
       ▼
BFF GetConfig (bn-bff-getconfig)

text

Internal Consumer
       │
       ▼
┌─────────────────────────────────┐
│         bn-paper-rolls-adp      │
│                                 │
│  Controller → Service → Client  │
│       ↕              ↕          │
│   Mapper         FeignAuthInterceptor
│       ↕              ↕          │
│   DTO            Circuit Breaker│
└─────────────────────────────────┘
       │
       ▼
BFF GetConfig (bn-bff-getconfig)

Layers

Layer	Responsibility
Controller	Receives HTTP requests, validates input and delegates to the Service
Service	Orchestrates calls to the Client, applies retry on 401, handles exceptions
Client (Feign)	Declarative interface for communication with external APIs
Mapper (MapStruct)	Converts internal DTOs (getnet) into public DTOs (openapi)
FeignAuthInterceptor	Manages and injects Bearer Token into all Feign requests
GlobalExceptionHandler	Captures and standardizes all application errors

🔌 Features

1. Stock Query — `GET /v1/stocks/{merchant_id}`

Retrieves the current paper rolls stock for a specific merchant (EC).

Flow:

Receives merchant_id as a path parameter
Calls StockClient (Feign) with automatic Bearer Token authentication
On 401, invalidates the cached token and performs an automatic retry
On 404, throws NotFoundException (not counted by the circuit breaker)
Maps the internal response (BobStockResponseDTO) to the public contract (StockDTO)

Responses: 200 OK, 401 Unauthorized, 403 Forbidden, 404 Not Found, 500 Internal Server Error, 504 Gateway Timeout

2. Order Query — `GET /v1/orders`

Retrieves paper rolls orders with support for multiple optional filters.

Filter parameters:

Parameter	Type	Description
ec	List<String>	Merchant establishment code(s)
cpf_cnpj	List<String>	Holder's CPF/CNPJ
order	List<Integer>	Order number(s)
tracking_number	List<String>	Tracking code(s)
os	List<String>	Service order number(s)
type	List<String>	Order type (I=Internal, R=Reactive, A=Automatic)
status	List<String>	Order status (see enum AvailableOrderStatus)
page	Integer	Pagination page number
limit	Integer	Number of records per page
immediate_delivery	Boolean	Filter by immediate delivery

Flow:

Validates and forwards filters to OrderManagementClient
On 401, invalidates token and performs an automatic retry
On 404, throws NotFoundException
Maps the PedidoDTO list (internal contract) to OrderDTO (public contract)

Responses: 200 OK (list, may be empty), 400 Bad Request, 401, 403, 404, 500, 504

3. Manual Order — `POST /v1/manual-orders`

Creates a manual paper rolls replenishment order for a specific merchant.

Flow:

Receives the OpenApiManualOrderRequestDTO payload (validated via Bean Validation)
Queries the permission API (ManualOrderClient) to check whether the merchant is authorized for the given channel
If granted (status = "Permitido"):
- Retrieves the authorized quantity from the permission response
- Creates the order via ManualOrderClient.create()
- Returns 200 OK with the details of the created order
If denied:
- Returns 404 with denial: true and the denial reason (denial_reason)
- The word "EC" in the denial message is replaced by "merchant_id" for standardization
On 401 during any call, invalidates token and performs an automatic retry
On 404 from the external API, throws NotFoundException

Responses: 200 OK, 400 Bad Request, 401, 403 Forbidden, 500, 504

🔐 Authentication

All communication with external APIs uses Bearer JWT Token managed by FeignAuthInterceptor:

Token obtained via AuthenticationClient on the first request
Token cached in memory (AtomicReference) for reuse
Token automatically invalidated when any service returns 401, followed by a retry of the operation with a new token

🛡️ Resilience — Circuit Breaker

All services are protected by Resilience4j Circuit Breaker:

Configuration	Value
Sliding window size	10 calls
Minimum number of calls to activate	5
Failure rate to open the circuit	50%
Wait duration in open state	30 seconds
Permitted calls in half-open state	3
Call timeout	30 seconds

Monitored exceptions: FeignException, ConnectException, TimeoutException

Ignored exceptions (not counted): NotFoundException, BadRequestException, FeignException.NotFound, FeignException.BadRequest, FeignException.Unauthorized

🗂️ Module Structure

text

src/main/java/br/com/getnet/paper/rolls/
├── client/
│   ├── authentication/   # Feign client for authentication
│   ├── manualorder/      # Feign client for manual orders
│   ├── ordermanagement/  # Feign client for order management
│   └── stock/            # Feign client for stock
├── config/
│   ├── FeignAuthInterceptor.java   # JWT token management
│   └── OpenApiConfiguration.java  # Swagger/OpenAPI configuration
├── controller/
│   ├── manualorder/      # Endpoint 600;">POST /v1/manual-orders
│   ├── ordermanagement/  # Endpoint 600;">GET /v1/orders
│   └── stock/            # Endpoint 600;">GET /v1/stocks/{merchant_id}
├── dto/
│   ├── authentication/   # Authentication DTOs
│   ├── manualorder/      # Manual order DTOs (getnet + openapi)
│   ├── ordermanagement/  # Order DTOs (getnet + openapi)
│   └── stock/            # Stock DTOs (getnet + openapi)
├── exception/
│   ├── BadRequestException.java
│   ├── NotFoundException.java
│   ├── dto/              # ErrorDTO for standardized responses
│   └── handler/          # GlobalExceptionHandler
├── mapper/
│   ├── manualorder/      # MapStruct mappers for manual orders
│   ├── ordermanagement/  # MapStruct mapper for orders
│   └── stock/            # MapStruct mapper for stock
└── service/
    ├── manualorder/      # Manual order orchestration
    ├── ordermanagement/  # Order query orchestration
    └── stock/            # Stock query orchestration

text

src/main/java/br/com/getnet/paper/rolls/
├── client/
│   ├── authentication/   # Feign client for authentication
│   ├── manualorder/      # Feign client for manual orders
│   ├── ordermanagement/  # Feign client for order management
│   └── stock/            # Feign client for stock
├── config/
│   ├── FeignAuthInterceptor.java   # JWT token management
│   └── OpenApiConfiguration.java  # Swagger/OpenAPI configuration
├── controller/
│   ├── manualorder/      # Endpoint 600;">POST /v1/manual-orders
│   ├── ordermanagement/  # Endpoint 600;">GET /v1/orders
│   └── stock/            # Endpoint 600;">GET /v1/stocks/{merchant_id}
├── dto/
│   ├── authentication/   # Authentication DTOs
│   ├── manualorder/      # Manual order DTOs (getnet + openapi)
│   ├── ordermanagement/  # Order DTOs (getnet + openapi)
│   └── stock/            # Stock DTOs (getnet + openapi)
├── exception/
│   ├── BadRequestException.java
│   ├── NotFoundException.java
│   ├── dto/              # ErrorDTO for standardized responses
│   └── handler/          # GlobalExceptionHandler
├── mapper/
│   ├── manualorder/      # MapStruct mappers for manual orders
│   ├── ordermanagement/  # MapStruct mapper for orders
│   └── stock/            # MapStruct mapper for stock
└── service/
    ├── manualorder/      # Manual order orchestration
    ├── ordermanagement/  # Order query orchestration
    └── stock/            # Stock query orchestration

⚙️ Environments

Profile	Purpose
local	Local development
dev	Development environment
hti	Integration testing (homologation)
hg	General homologation
prod	Production
test	Automated tests

📦 Tech Stack

Technology	Version	Usage
Java	17	Language
Spring Boot	3.5.x	Core framework
Spring Cloud OpenFeign	4.x	Declarative HTTP clients
Resilience4j	—	Circuit Breaker
MapStruct	1.5.5	DTO mapping
Lombok	1.18.x	Boilerplate reduction
SpringDoc / Swagger UI	2.3.x	API documentation
JaCoCo	0.8.11	Test coverage
JUnit 5 + Mockito	—	Unit and integration tests

🚀 Running Locally

text

# With Maven Wrapper
./mvnw spring-boot:run -Dspring-boot.run.profiles=local

# Swagger UI available at:
# http://localhost:8080/swagger-ui/index.html

# Health check:
# http://localhost:8080/healthcheck

text

# With Maven Wrapper
./mvnw spring-boot:run -Dspring-boot.run.profiles=local

# Swagger UI available at:
# http://localhost:8080/swagger-ui/index.html

# Health check:
# http://localhost:8080/healthcheck

📊 Test Coverage

Coverage is generated via JaCoCo during the test phase:

text

./mvnw clean test
# Report generated at: target/site/jacoco/index.html

text

./mvnw clean test
# Report generated at: target/site/jacoco/index.html

En esta página

bn-paper-rolls-adp

bn-paper-rolls-adp

📋 Overview

🏗️ Architecture

Layers

🔌 Features

1. Stock Query — GET /v1/stocks/{merchant_id}

2. Order Query — GET /v1/orders

3. Manual Order — POST /v1/manual-orders

🔐 Authentication

🛡️ Resilience — Circuit Breaker

🗂️ Module Structure

⚙️ Environments

📦 Tech Stack

🚀 Running Locally

📊 Test Coverage

1. Stock Query — `GET /v1/stocks/{merchant_id}`

2. Order Query — `GET /v1/orders`

3. Manual Order — `POST /v1/manual-orders`