API Contract - Frontend Integration Guide¶

This document explains how the frontend should integrate with the backend API.

Quick Start for Frontend Devs¶

1. Authentication Flow¶

1. User opens app → Login page
2. POST /api/v1/auth/login {email, password}
3. Response: {access_token, refresh_token, expires_in}
4. Store tokens securely
5. Use access_token for all subsequent requests
6. When access_token expires → POST /api/v1/auth/refresh

2. API Client Setup¶

# In core/network/api_client.py
class ApiClient:
    def __init__(self, base_url: str):
        self.base_url = base_url
        self._access_token = None

    async def set_token(self, token: str):
        self._access_token = token

    async def get(self, path: str, **kwargs):
        headers = kwargs.pop("headers", {})
        if self._access_token:
            headers["Authorization"] = f"Bearer {self._access_token}"
        # ... make request

3. Error Handling¶

HTTP Status	Meaning	Frontend Action
400	Bad request	Show validation error
401	Unauthorized	Refresh token or re-login
403	Forbidden	Show permission error
404	Not found	Show not found message
429	Rate limited	Retry after delay
500	Server error	Show generic error

4. Common Endpoints¶

Feature	Endpoint	Auth
Login	POST /api/v1/auth/login	No
Refresh	POST /api/v1/auth/refresh	No
Logout	POST /api/v1/auth/logout	Yes
Get shipments	GET /api/v1/shipments	Yes
Get shipments board	GET /api/v1/shipments/board	Yes
Create shipment	POST /api/v1/shipments	Yes
Get packages	GET /api/v1/shipments/{id}/packages	Yes
Create scan	POST /api/v1/scans	Yes
Get flights	GET /api/v1/flights	Yes
Get bags	GET /api/v1/bags	Yes
Track public	GET /api/v1/track/{tracking_id}	No

Response Formats¶

Success¶

{
  "data": {...},
  "message": "Optional message"
}

Error¶

{
  "error": "error_code",
  "message": "Human readable message",
  "details": {...}
}

Request/Response Examples¶

See endpoints.md for detailed API documentation.

Páginas de referencia¶

Página	Contenido
Auth	Endpoints de autenticación, test credentials
Endpoints	CRUD completo de shipments, bags, flights, tracking
WebSockets	Conexión, eventos, frontend implementation

Ver también: Backend Modules · Frontend Architecture