Juca API

A monolith service referencing Caju, to put in practice "credit transaction" management.

---

Getting Started

Dependencies

• Docker 🐳

Running

• Run docker compose (8080 port should be available):

docker compose up -d --build

• That's it! Your application is available on localhost:8080/api.

Development

1. Run docker docker compose -f docker-compose-dev.yml up -d to up all service dependencies
2. Run ./gradlew build to build the project
3. Run gradlew bootRun --args='--spring.profiles.active=dev' to start the API

API Docs

• OpenAPI
• Swagger UI

Use Cases

• Create account
• Add Credit
• Find Wallets by Account ID
• Transact
• Get Statement

Create Account

Endpoint to create an account and wallets.

• Host: localhost:8080/api
• Method: POST
• URL: /v1/accounts
• Request Body: N/A
• Response Body:

  {
    "id": 1,
    "wallet": {
      "foodBalance": 0.00,
      "mealBalance": 0.00,
      "cashBalance": 0.00
    }
  }

Response Properties

name	description
id	Int New account identifier.
wallets.foodBalance	String New wallet food balance. Usually it will be zero.
wallets.mealBalance	String New wallet meal balance. Usually it will be zero.
wallets.cashBalance	String New wallet cash balance. Usually it will be zero.

Add Credit

If you want to add money to an account wallet, that's your endpoint.

• Host: localhost:8080/api
• Method: POST
• URL: /v1/credits
• Request Body:

  {
    "accountId": 1,
    "amount": 200.00,
    "merchantCategory": "FOOD"
  }

• Response Body:

  {
    "id": 1,
    "wallet": {
      "foodBalance": 200.00,
      "mealBalance": 0.00,
      "cashBalance": 0.00
    }
  }

Request Properties

name	description
accountId*	Int Account identifier, it'll be used to search the wallet to be updated. It should be a positive integer value.
amount*	Float Value to be credited on wallet. It should be a positive float value, with at most 14 integer digits and 2 fraction digits.
merchantCategory*	String Category to identify the benefit to receive the credit.

Response Properties

name	description
wallet.foodBalance	Float Updated wallet food balance.
wallet.mealBalance	Float Updated wallet meal balance.
wallet.cashBalance	Float Updated wallet cash balance.

Find Wallets by Account ID

Endpoint to check the values of each benefit available on an account.

• Host: localhost:8080/api
• Method: GET
• URL: /v1/accounts/{id}
• Request Body: N/A
• Response Body:

  {
    "id": 1,
    "wallet": {
      "foodBalance": 200.00,
      "mealBalance": 0.00,
      "cashBalance": 0.00
    }
  }

Request Parameters

name	description
id*	Int (Query) Account identifier, it'll be used to search the wallets.

Response Properties

name	description
id	Int Account identifier.
wallets.foodBalance	String Wallet food balance.
wallets.mealBalance	String Wallet meal balance.
wallets.cashBalance	String Wallet cash balance.

Transact

Endpoint to handle the card transaction.

• Host: localhost:8080/api
• Method: POST
• URL: /v1/transactions
• Request Body:

  {
    "externalId": "964df205-d29d-42a1-8cf0-f684afae6ffe",
    "accountId": 1,
    "amount": 50.00,
    "mcc": "5411",
    "merchant": "PADARIA DO ZE               SAO PAULO BR"
  }

• Response Body:

  {
    "code": "00"
  }

Request Parameters

name	description
externalId*	UUID Unique identifier of the transaction, it'll be used to check uniqueness.
accountId*	Int Account identifier.
amount*	Float Value to be debited.
mcc*	String Merchant category code, basically it's a string with exactly 4 digits (0000). It'll be used to find the right benefit. Known values: - FOOD: 5411 and 5412 - MEAL: 5811 and 5812 - CASH: Any other code.
merchant*	String Merchant name with address, it's a string with exactly 40 chars, the first 25 chars should have the merchant name and the rest the address.

Response Properties

name	description
code	String Code to represent the result of the request. Available codes: - 00: Approved - 07: Error - 51: Insufficient balance

Get Statement

Endpoint to visualize the statement of an account.

• Method: GET
• URL: /v1/accounts/{id}/statement
• Request Body: N/A
• Response Body:

  {
    "transactions": [
      {
        "externalId": "964df205-d29d-42a1-8cf0-f684afae6ffe",
        "origin": "PADARIA DO ZE - SAO PAULO BR",
        "accountId": 1,
        "amount": 50.00,
        "type": "DEBIT",
        "merchantCategory": "FOOD",
        "result": "APPROVED",
        "createdAt": "2024-08-31T13:25:39.474374"
      }
    ]
  }

Request Parameters

name	description
id*	Int (Query) Account identifier, it'll be used to search the transactions.