External API Documentation

Overview

This External API is built using FastAPI and deployed on Google Cloud Platform with API Gateway for security and traffic management. The API provides secure access to our services through a token-based authentication system.

Architecture

Backend: FastAPI application running on Google Cloud Run
Gateway: Google Cloud API Gateway for request routing and security
Authentication: JWT-based token system with Basic Auth for initial authentication
Deployment: Automated CI/CD pipeline using Google Cloud Build

Base URL

For dev : https://external-api-gateway-525b4eqm.ew.gateway.dev

For staging : https://external-api-gateway-1rbt1ki8.ew.gateway.dev

For prod : https://external-api-gateway-cg2l71y2.ew.gateway.dev

API Authentication

How to Get and Use Your Token

To access most of our API's features, you'll need to authenticate. This process involves getting a token that you'll then use for all your subsequent requests. Here's how it works:

1. Getting Your Authentication Token

You'll start by sending a GET request to the /authentication endpoint. You must include an Authorization header in every request. The header should use the Basic scheme, followed by a base64-encoded string of your email:password.

Format:

Authorization: Basic base64(email:password)

where base64(email:password) is the base64 encoded email:password.

Example:

# If your email is "user@example.com" and password is "mypassword"
# The base64 encoding of "user@example.com:mypassword" is "dXNlckBleGFtcGxlLmNvbTpteXBhc3N3b3Jk"

curl -X GET "https://external-api-gateway-525b4eqm.ew.gateway.dev/authentication" \
  -H "Authorization: Basic dXNlckBleGFtcGxlLmNvbTpteXBhc3N3b3Jk"

If your email and password are correct, the API will respond with a JSON containing:

{
    "message": "Authentication successful",
    "email": "youremail@example.com",
    "idToken": "yourtokenid",
    "expiresIn": "expiration (in seconds)"
}

yourtokenid is your unique authorization token. Your token expires in 60 minutes starting the moment you receive it.

2. Using Your Token for Subsequent Requests

Once you have your tokenid, you must include it in the header of every request you make to other protected API endpoints. The header should be named Authorization, and its value must start with Bearer followed by your tokenid.

For instance, if your tokenid is yourtokenid, your Authorization header will look like this:

Authorization: Bearer yourtokenid

Just replace yourtokenid with the actual token you received from the /authentication endpoint. This tells the API that you are authorized to access the requested resources.

Example:

curl -X GET "https://external-api-gateway-525b4eqm.ew.gateway.dev/orders" \
  -H "Authorization: Bearer yourtokenid"

API Endpoints

Authentication Endpoint

Method	Endpoint	Description	Authentication
`GET`	`/authentication`	Get authentication token	Basic Auth

Protected Endpoints

All other endpoints require Bearer token authentication as described above.

Method	Endpoint	Description	Authentication
`GET`	`/orders`	Retrieve most recent orders (limited to 100 most recent updates)	Bearer Token
`GET`	`/orders/{order_id}`	Retrieve historical process of a specific order	Bearer Token
`POST`	`/createDelivery`	Import multiple orders into the system	Bearer Token
`PUT`	`/updateDelivery`	Update address information for an existing order	Bearer Token

Detailed Endpoint Documentation

GET /orders

Retrieves the most recent updates of orders (limited to the 100 most recent updates).

Query Parameters: - order_date (optional): Filter by order date (format: YYYY-MM-DD) - order_status (optional): Filter by order status

Example Request:

curl -X GET "https://external-api-gateway-525b4eqm.ew.gateway.dev/orders?order_date=2024-06-25&order_status=pending" \
  -H "Authorization: Bearer yourtokenid"

GET /orders/{order_id}

Retrieves the historical process of a specific order.

Path Parameters: - order_id (required): The unique identifier of the order

Example Request:

curl -X GET "https://external-api-gateway-525b4eqm.ew.gateway.dev/orders/ORD001" \
  -H "Authorization: Bearer yourtokenid"

POST /createDelivery

Import multiple orders into the system.

Request Body: Array of order objects with the following structure:

[
  {
    "customerInfo": {
      "clientId": "C123",
      "clientName": "Pedro",
      "clientPhone": "+351912345678",
      "clientEmail": "Pedro@example.com"
    },
    "orderInfo": {
      "orderId": "ORD001",
      "addressLine": "Rua das Flores, 123",
      "country": "Portugal",
      "locality": "Lisboa",
      "postalCode": "1000-001",
      "city": "Lisboa",
      "streetNumber": "123",
      "houseNumber": "1",
      "lat": 38.7169,
      "lon": -9.1399,
      "orderDate": "2024-06-24",
      "deliveryDate": "2024-06-25",
      "totalVolume": 0.1,
      "totalWeight": 1.5,
      "orderDimensions": {
        "length": 0.5,
        "width": 0.4,
        "height": 0.5
      }
    },
    "slot": {
      "slotFrom": "10:00",
      "slotTo": "12:00"
    },
    "payment": {
      "paymentBoolean": true,
      "value": 9.99,
      "paymentType": "card"
    }
  }
]

Response:

{
  "code": "ORDERS_IMPORTED",
  "message": {
    "pt": "Encomendas importadas com sucesso.",
    "en": "Orders have been imported."
  },
  "results": {
    "successCount": 1,
    "failedOrders": []
  }
}

PUT /updateDelivery

Update address information for an existing order.

Request Body:

{
  "orderId": "ORD001",
  "addressLine": "Avenida da Liberdade 100",
  "country": "Portugal",
  "locality": "Lisboa",
  "postalCode": "1250-145",
  "city": "Lisboa",
  "streetNumber": "100",
  "houseNumber": "5"
}

Data Models

CustomerInfo

clientId (optional): Client identifier
clientName (required): Client's name
clientPhone (required): Phone number
clientEmail (optional): Email address

OrderInfo

multiDeliverId (optional): Bundle identifier for multiple orders
orderId (required): Order identifier
addressLine (optional): Full address line
country (required): Country name
locality (required): City/locality
postalCode (required): Postal code
city (required): Postal code city
streetNumber (required): Street number
houseNumber (required): House number
lat (optional): Latitude coordinate
lon (optional): Longitude coordinate
orderDate (optional): Order placement date (YYYY-MM-DD format)
deliveryDate (required): Delivery date (YYYY-MM-DD format)
totalVolume (required): Total volume in cubic meters
totalWeight (required): Total weight in kilograms
orderDimensions (optional): Package dimensions object

Dimensions

length (required): Length in meters
width (required): Width in meters
height (required): Height in meters

Slot

slotFrom (optional): Start of delivery slot (HH:MM format)
slotTo (optional): End of delivery slot (HH:MM format)

Payment

paymentBoolean (optional): Payment status (true if paid)
value (optional): Payment amount in euros
paymentType (optional): Type of payment (e.g., "card")

Development and Deployment

Local Development

# Install dependencies
poetry install

# Run the FastAPI application
uvicorn main:app --reload --host 0.0.0.0 --port 8080

Deployment

The API is automatically deployed using Google Cloud Build when changes are pushed to the main branch. The deployment process includes:

Building the Docker image
Pushing to Google Artifact Registry
Deploying to Google Cloud Run
Updating the API Gateway configuration

Configuration

The API uses the following environment variables:

PROJECT_ID: Google Cloud Project ID
FIREBASE_API_KEY: Firebase API key for authentication
MONGODB_*: MongoDB connection parameters
GOOGLE_MAPS_API_KEY: Google Maps API key for address validation
BIGQUERY_*: BigQuery configuration for order storage
OSRM_HOST: OSRM server URL for route calculations
BO_API_KEY: Backend API key for internal communications
BOURL: Backend API URL