ABC V2 API

A complete integration interface for the ABC App to interact with the Soffa parking platform. Built for developers, designed for scale.

API Status: Operational

v2.0 Latest Version

🔐 Authentication

All API requests must include a valid API key in the header. The API uses header-based authentication with X-API-Key.

Header Format

X-API-Key: abc_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Generate API Key

Use the Artisan command to generate a new API key with specific scopes:

php artisan api-key:generate "ABC App Production" --scopes=users:read --scopes=users:write

Base URL

/api All endpoints are relative to this base URL

POST

Create User

/create-user

201 Created

Create a new user account in the system with full profile details.

Request Body

{
  "name": "John",
  "surname": "Doe",
  "email": "john.doe@example.com",
  "username": "johndoe",
  "password": "securePassword123",
  "phone_number": "+1234567890",
  "gender": 1,
  "date_of_birth": "1990-01-15",
  "nationality_id": 1,
  "tenant_id": 1,
  "is_email_confirmed": true,
  "is_phone_confirmed": false
}

Response Example

{
  "success": true,
  "message": "User created successfully",
  "data": {
    "id": 123,
    "first_name": "John",
    "last_name": "Doe",
    "full_name": "John Doe",
    "username": "johndoe",
    "email": "john.doe@example.com",
    "phone_number": "+1234567890",
    "is_active": true,
    "email_verified": true,
    "phone_verified": false,
    "date_of_birth": "1990-01-15",
    "gender": "male",
    "created_at": "2024-01-15T10:30:00.000000Z"
  }
}

GET

Get User by Email or Phone

/user-by-email

200 OK

Retrieve user information using email address or phone number as lookup keys.

Query Parameters:

email string (optional)

phone_number string (optional)

Example Request:

GET /user-by-email?email=john.doe@example.com&phone_number=+1234567890

PUT

Update User Profile

/user-profile

200 OK

Update user profile information by email or phone number. Supports partial updates.

{
  "email": "john.doe@example.com",
  "name": "Johnny",
  "surname": "Doe",
  "new_email": "johnny.doe@example.com",
  "new_phone_number": "+0987654321",
  "profile_picture_url": "https://example.com/photo.jpg"
}

DELETE

Delete User Profile

/user-profile

Soft Delete

Performs a soft delete. The user is marked as deleted and inactive, and all their plates are deactivated.

{
  "email": "john.doe@example.com",
  "reason": "User requested account deletion"
}

🚗 Plate Management

POST

Attach Plate to User

/attach-plate

201 Created

Attach a new car plate to a user. Returns 409 Conflict if plate already attached.

{
  "user_id": 123,
  "plate_number": "ABC123",
  "plate_name": "My BMW",
  "origin_country_id": 1,
  "usage_country_id": 1,
  "is_favorite": true
}

GET

Get User Plates

/user-plates

Retrieve all plates for a user by email or phone number.

PUT

Update Car Plate

/car-plates/{phoneNumber}/{carPlateId}

Note: Final plate number is concatenated: symbol + plate_number

Example: "Z" + "171696" = "Z171696"

DELETE

Remove Car Plates

/car-plates/{phoneNumber}

Remove multiple car plates by phone number. Returns detailed breakdown of removed, not found, and not owned plates.

{
  "car_plate_ids": [1, 2, 3]
}

POST

Initiate Payment Method

/initiate-payment-method

Initiate Cybersource Secure Acceptance for credit card tokenization. Returns iframe URL and signed fields.

Request

{
  "phone_number": "+1234567890"
}

Response Fields

{
  "iframe_url": "https://testsecureacceptance...",
  "fields": { ... },
  "signature": "base64signature...",
  "reference_number": "ABC_123_1705765800"
}

GET

Get All Countries

/countries

Retrieve a list of all countries with ISO codes and deployment status.

GET

Search Countries

/countries/search?q={query}

Search countries by name. Minimum 2 characters required.

⚠️ Error Responses

400

Bad Request

Validation failed - check request parameters

validation_failed

401

Unauthorized

API key is missing or invalid

missing_api_key

403

Forbidden

User does not own this resource

plate_not_owned

404

Not Found

User or resource not found

user_not_found

409

Conflict

Resource already exists (e.g., plate already attached)

plate_already_attached

500

Internal Server Error

Server error - contact support

creation_failed

Data Types Reference

Gender Values

1 Male

2 Female

User Status Fields

IsActive - Account active status

IsDeleted - Soft delete status

IsEmailConfirmed - Email verification

API Key Management

Generate API Key

php artisan api-key:generate "ABC App Production" --scopes=users:read --scopes=users:write

List API Keys

php artisan api-key:list
php artisan api-key:list --active
php artisan api-key:list --revoked

Revoke Key

php artisan api-key:revoke 1

Rotate Key

php artisan api-key:rotate 1