1. Introduction

Bank API is a simple API for managing customers, their accounts and making transactions between them, its supports some operations like withdrawals, deposits and transferations.

1.1. Usage of HTTP Verbs

The following table describes how the Bank API interprets the HTTP verbs.

Table 1. HTTP Verbs
HTTP Verb Usage

GET

GET is used to retrieve information.

POST

POST is used to create resources.

PUT

PUT is used to update resources.

DELETE

DELETE is used to delete resources.

1.2. Error Handling

1.2.1. Successful Requests

Successful requests return a response with HTTP status 200 (OK) or 201 (CREATED) or 204 (NO CONTENT) and contain a JSON structure in the response body (except for 204 status responses).

1.2.2. Validation Errors

POST and PUT requests against the Bank API expect a JSON structure in the request body, GET, PUT and DELETE requests also expect to have a valid path variable. If the JSON structure contains values that are invalid, the API returns a response with HTTP status 422 (UNPROCESSABLE ENTITY) that contains an error JSON structure object that looks like this:

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json
Content-Length: 135

{
  "message" : "validation errors on your request",
  "errors" : [ {
    "field" : "name",
    "message" : "must not be blank"
  } ]
}

1.2.3. General Errors

If some unexpected error occurs during the processing of a request, the Bank API returns a response with HTTP status 500 (internal server error).

2. Resources

2.1. Customer

2.1.1. Structure

Path Type Description Constraints

name

String

Customer’s name

Must match the regular expression [A-Za-z\s]*. Must not be blank

email

String

Customer’s email

Must be a well-formed email address. Must not be blank

cpf

String

Customer’s CPF

Must be a valid CPF. Must not be blank

birthDate

String

Customer’s date of birth

Must be in the past. Must not be null

CPF

The Individual Taxpayer Registration (CPF) is the registry maintained by the Federal Revenue of Brazil, where any natural person must register once, regardless of age or nationality. Each registered person is identified in the country by a unique 11-digit number. Learn more here: https://www.gov.br/mre/pt-br/embaixada-helsinque/consular-services/cpf-taxpayer-registry-for-individuals.

2.1.2. Creating customer

Example request

POST /api/v1/customers HTTP/1.1
Content-Type: application/json
Content-Length: 119
Host: example.com

{
  "name" : "customer",
  "email" : "customer@example.com",
  "cpf" : "xxx.xxx.xxx-xx",
  "birthDate" : "1990-09-09"
}

Example response

HTTP/1.1 201 Created
Location: http://example.com/api/v1/customers/1
Content-Type: application/json
Content-Length: 131

{
  "id" : 1,
  "name" : "customer",
  "email" : "customer@example.com",
  "cpf" : "xxx.xxx.xxx-xx",
  "birthDate" : "1990-09-09"
}

2.1.3. Finding customer

Example request

GET /api/v1/customers/xxx.xxx.xxx-xx HTTP/1.1
Host: example.com

Example response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 131

{
  "id" : 1,
  "name" : "customer",
  "email" : "customer@example.com",
  "cpf" : "xxx.xxx.xxx-xx",
  "birthDate" : "1990-09-09"
}

2.1.4. Editing customer

Example request

PUT /api/v1/customers/xxx.xxx.xxx-xx HTTP/1.1
Content-Type: application/json
Content-Length: 91
Host: example.com

{
  "name" : "customer",
  "email" : "customer@example.com",
  "birthDate" : "1990-09-09"
}

Example response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 131

{
  "id" : 1,
  "name" : "customer",
  "email" : "customer@example.com",
  "cpf" : "xxx.xxx.xxx-xx",
  "birthDate" : "1990-09-09"
}

2.1.5. Removing customer

Example request

DELETE /api/v1/customers/xxx.xxx.xxx-xx HTTP/1.1
Host: example.com

Example response

HTTP/1.1 204 No Content

2.2. Account

2.2.1. Structure

Path Type Description Constraints

bankCode

Number

Account’s bank code

Must not be null

Bank code

Bank code should be a valid brazilian bank code, you can check all valid bank codes here: https://bank.codes/numero-do-banco/bank/.

2.2.2. Creating account

Example request

POST /api/v1/customers/xxx.xxx.xxx-xx/accounts HTTP/1.1
Content-Type: application/json
Content-Length: 20
Host: example.com

{
  "bankCode" : 1
}

Example response

HTTP/1.1 201 Created
Location: http://example.com/api/v1/customers/xxx.xxx.xxx-xx/accounts/1
Content-Type: application/json
Content-Length: 84

{
  "id" : 1,
  "bank" : "bankname",
  "balance" : 0,
  "createdAt" : "2023-05-14"
}

2.2.3. Finding account

Example request

GET /api/v1/customers/xxx.xxx.xxx-xx/accounts/1 HTTP/1.1
Host: example.com

Example response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 84

{
  "id" : 1,
  "bank" : "bankname",
  "balance" : 0,
  "createdAt" : "2023-05-14"
}

2.2.4. Editing account

Example request

PUT /api/v1/customers/xxx.xxx.xxx-xx/accounts/1 HTTP/1.1
Content-Type: application/json
Content-Length: 20
Host: example.com

{
  "bankCode" : 1
}

Example response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 84

{
  "id" : 1,
  "bank" : "bankname",
  "balance" : 0,
  "createdAt" : "2023-05-14"
}

2.2.5. Removing account

Example request

DELETE /api/v1/customers/xxx.xxx.xxx-xx/accounts/1 HTTP/1.1
Host: example.com

Example response

HTTP/1.1 204 No Content

2.3. Transaction

2.3.1. Structure

Path Type Description Constraints

amount

Number

Transaction’s amount

Must be positive. Must not be null

originAccountId

Number

Transaction’s origin account id

Must not be null

destinationAccountId

Number

Transactions’s destination account id

Must not be null

Accounts id

When performing deposits or withdrawals transactions, the destination account id should be null, however, when performing transferations transactions, the destination account id shoud not be null and should be different from origin account id.

2.3.2. Creating transaction

Deposit

Example request

POST /api/v1/transactions/deposits HTTP/1.1
Content-Type: application/json
Content-Length: 44
Host: example.com

{
  "amount" : 10,
  "originAccountId" : 1
}

Example response

HTTP/1.1 201 Created
Location: http://example.com/api/v1/transactions/deposits/1
Content-Type: application/json
Content-Length: 103

{
  "id" : 1,
  "amount" : 10,
  "type" : "deposit",
  "date" : "2023-05-14",
  "originAccountId" : 1
}
Withdrawal

Example request

POST /api/v1/transactions/withdrawals HTTP/1.1
Content-Type: application/json
Content-Length: 44
Host: example.com

{
  "amount" : 10,
  "originAccountId" : 1
}

Example response

HTTP/1.1 201 Created
Location: http://example.com/api/v1/transactions/withdrawals/1
Content-Type: application/json
Content-Length: 106

{
  "id" : 1,
  "amount" : 10,
  "type" : "withdrawal",
  "date" : "2023-05-14",
  "originAccountId" : 1
}
Transfer

Example request

POST /api/v1/transactions/transfers HTTP/1.1
Content-Type: application/json
Content-Length: 74
Host: example.com

{
  "amount" : 10,
  "originAccountId" : 1,
  "destinationAccountId" : 2
}

Example response

HTTP/1.1 201 Created
Location: http://example.com/api/v1/transactions/transfers/1
Content-Type: application/json
Content-Length: 134

{
  "id" : 1,
  "amount" : 10,
  "type" : "transfer",
  "date" : "2023-05-14",
  "originAccountId" : 1,
  "destinationAccountId" : 2
}

2.3.3. Finding all transactions

Parameters

Parameter Description

account-id

The id of the account associated with this transaction

page

The page to retrieve

size

Entries per page

Example request

GET /api/v1/transactions?account-id=1&page=0&size=4 HTTP/1.1
Host: example.com

Example response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 351

[ {
  "id" : 1,
  "amount" : 10,
  "type" : "deposit",
  "date" : "2023-05-14",
  "originAccountId" : 1
}, {
  "id" : 2,
  "amount" : 10,
  "type" : "withdrawal",
  "date" : "2023-05-14",
  "originAccountId" : 1
}, {
  "id" : 3,
  "amount" : 10,
  "type" : "transfer",
  "date" : "2023-05-14",
  "originAccountId" : 1,
  "destinationAccountId" : 2
} ]