Skip to content

Latest commit

 

History

History
341 lines (244 loc) · 9.27 KB

readme.md

File metadata and controls

341 lines (244 loc) · 9.27 KB
Raw
logo

Valex Api

API to manage benefit cards creation, recharges and transactions.

About

API for companies to manage benefit cards creation, recharges and for employees to manage their transactions.

Below are the implemented endpoints:

  • '/create' --> Methods: POST
  • '/activate' --> Methods: PUT
  • '/block' --> Methods: PUT
  • '/unblock' --> Methods: PUT
  • '/recharge' --> Method: POST
  • '/buy' --> Method: POST
  • '/statements/:cardId' --> Methods: GET

Check section Endpoint details to know how to properly use each endpoint.

Technologies

The following tools and frameworks were used in the construction of the project:

TypeScript NodeJS Postgres Express.js Heroku Ubuntu Visual Studio Code

How to run

From localhost url:

  1. Clone this repository to your local machine;
  2. Run npm i from your terminal to install dependencies;
  3. Make sure to have postgres database running on the machine sudo service postgresql start
  4. Run the create-database script running bash create-database from inside the "database" directory (this will create the 'valex' database locally for the 'postgres' role and all needed tables. It will also add some initial data into them)
  5. Configure a .env file on the project root with the following environment keys:
  DATBASE_URL=postgres://postgres:<password>@localhost:5432/valex
  SECRET_KEY=<cryptr_secret_key>
  PORT=<prefered_optional_port>
  MODE=<DEV | PROD>
  1. Run npm run dev to run the project on the PORT you chose, or 4000 if none are defined on .env
  • baseUrl: http://localhost:4000

From Valex-api url, deployed on Heroku:

You can also use all the endpoints from this project through the deployed Heroku app, using its deploy URL:

  • baseURL: https://valex-db-api.herokuapp.com/

Endpoints details

  • '/create' --> Methods: POST
  • '/activate' --> Methods: PUT
  • '/block' --> Methods: PUT
  • '/unblock' --> Methods: PUT
  • '/recharge' --> Method: POST
  • '/buy' --> Method: POST
  • '/statements/:cardId' --> Methods: GET

Method: POST, Route: '/create'

A company can create a new type of card for an employee.

  • In order to create a card, an apiKey must be provided by the company that is creating the card.
  • The apiKey is a unique identifier for the company and must be provided through a 'x-api-key' header:
  "x-api-key": "<apiKey>"
  • A body with the employeeId and the cardType must be provided:
{
  "employeeId": number,
  "cardType": "<cardType>"
}

-> CREATE VALIDATION:

  • all: required

  • apiKey: must belong to a registered company

  • employeeId: must belong to a registered employee

  • cardType: must be one of the following types: ``groceries, health`, `transport`, `education`, `restaurant`

  • This endpoint will return a 201 status code and an object with the new card data:

{
  cardId: number,
  cardNumber: string;
  securityCode: number;
  expirationDate: string;
}

Method: PUT, Route: '/activate'

An employee can activate a card.

  • In order to activate a card, the cardId, the securityCode and the card password must be provided via body:

      {
    "cardId": number,
    "securityCode": number,
    "password": string
  }

-> ACTIVATE VALIDATION:

  • all: required
  • cardId: must belong to a registered, unnactive card (with no registered password)
  • password: must be a 4 numbers long string
  • securityCode(CVV): must be a 3 numbers long integer

Method: PUT, Route: '/block'

An employee can block a card.

  • In order to block a card, the cardId and the card password must be provided via body:

      {
    "cardId": number,
    "password": string
  }

-> BLOCK VALIDATION:

  • all: required
  • cardId: must belong to a registered, active card
  • password: must be a 4 numbers long string

Method: PUT, Route: '/unblock'

An employee can unblock a card.

  • In order to unblock a card, the cardId and the card password must be provided via body:

      {
    "cardId": number,
    "password": string
  }

-> UNBLOCK VALIDATION:

  • all: required
  • cardId: must belong to a registered, blocked card
  • password: must be a 4 numbers long string

Method: POST, Route: '/recharge'

A company can recharge an employee card.

  • In order to recharge a card, an apiKey must be provided by the company.
  • The apiKey is a unique identifier for the company and must be provided through a 'x-api-key' header:
  "x-api-key": "<apiKey>"

  • A body with the cardId and the amount to be recharged must be provided:

      {
    "cardId": number,
    "amount": number
  }

-> RECHARGE VALIDATION:

  • all: required
  • cardId: must belong to a registered, active card
  • amount: must be a integer that represents the amount to be recharged, but without the cents. (For example, if the amount is $ 10.50, the amount must be 1050)

Method: POST, Route: '/buy'

An employee can buy in specific POS (Points of Sale).

  • In order to buy with a card, the cardId, the businessId, amount and password must be provided via body:

      {
    "cardId": number,
    "businessId": number,
    "amount": number,
    "password": string
  }

-> BUY VALIDATION:

  • all: required
  • cardId: must belong to a registered, active card
  • businessId: must belong to a registered, kind of business
  • amount: must be a integer that represents the amount to be recharged, but without the cents. (For example, if the amount is $ 10.50, the amount must be 1050)
  • password: must be a 4 numbers long string

Method: GET, Route: '/statements/:cardId'

An employee can get the statements of a card.:

  • In order to get the statements of a card, the cardId must be provided via url params:
"/statements/:cardId"

-> STATEMENTS VALIDATION:

  • all: required
  • cardId: must belong to a registered card

-> STATEMENTS RESPONSE:

  {
    "balance": number,
    "transactions": [
      {
        "id": number,
        "cardId": number,
        "businessId": number,
        "businessN;ame": string,
        "timestamp": timestamp without timezone,
        "amount": number
      }
    ],
    "recharges": [
      {
        "id": number,
        "cardId": number,
        "timestamp": timestamp without timezone,
        "amount": number
      }
    ]
  }

Method: POST, Route: '/buy/online'

An employee can buy from an online source.

  • In order to buy online, the businessId, amount of the purchase, card number, cardholder name, security code (CVV) and expiration date must be provided via body:

      {
    "businessId": number,
    "amount": number,
    "cardNumber": string,
    "cardholderName": string,
    "securityCode": number,
    "expirationDate": string
  }

-> BUY ONLINE VALIDATION:

  • all: required
  • businessId: must belong to a registered, kind of business
  • amount: must be a integer that represents the purchase value, but without the cents. (For example, if the amount is $ 10.50, the amount must be 1050)
  • cardNumber: must be a 16 numbers long string
  • cardholderName: must be an uppercase string, just as the name on the card
  • securityCode(CVV): must be a 3 numbers long integer
  • expirationDate: must be a string with the format 'MM/YY'

Method: POST, Route: '/create/virtual'

It is possible to create a virtual card that refers to a real card.

  • In order to create a virtual card, the original cardId and password must be provided via body:

      {
    "cardId": number,
    "password": string
  }

-> CREATE VIRTUAL VALIDATION:

  • all: required

  • cardId: must belong to a registered, active card that is not virtual

  • password: must be a 4 numbers long string

  • This endpoint will return a 201 status code and an object with the new card data:

{
  "cardId": number,
  "cardNumber": string;
  "securityCode": number;
  "expirationDate": string;
}