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.
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 |
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 |
---|---|
|
The id of the account associated with this transaction |
|
The page to retrieve |
|
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
} ]