OniiOniiChan/LogisticsDataExtractionValidationSystem

1# API Documentation - Logistics Data Extraction2 3## Tổng Quan4 5API này cung cấp các endpoint để trích xuất và xác thực dữ liệu Logistics từ các chứng từ (Invoice, Packing List, Bill of Lading, Customs Declaration).6 7---8 9## Endpoint: /api/extract-all10 11### Mô Tả12Trích xuất dữ liệu từ nhiều file chứng từ đồng thời và thực hiện đối chiếu dữ liệu.13 14### HTTP Method15**POST**16 17### URL18```19POST /api/extract-all20```21 22### Request23 24#### Header25```26Content-Type: multipart/form-data27```28 29#### Parameters30- **Files**: Danh sách các file (PDF, JPG, PNG, GIF, WEBP)31  - Hỗ trợ tối thiểu 2 file, tối đa không giới hạn32  - Tên file: `file`, `file0`, `file1`, ... hoặc `file[0]`, `file[1]`, ...33 34#### Ví dụ cURL35```bash36curl -X POST http://localhost:5000/api/extract-all \37  -F "file=@invoice.pdf" \38  -F "file=@packing_list.pdf" \39  -F "file=@bill_of_lading.pdf"40```41 42#### Ví dụ Python43```python44import requests45 46files = [47    ('file', open('invoice.pdf', 'rb')),48    ('file', open('packing_list.pdf', 'rb')),49    ('file', open('bill_of_lading.pdf', 'rb'))50]51 52response = requests.post(53    'http://localhost:5000/api/extract-all',54    files=files55)56 57print(response.json())58```59 60#### Ví dụ JavaScript (Fetch API)61```javascript62const formData = new FormData();63formData.append('file', document.getElementById('invoice').files[0]);64formData.append('file', document.getElementById('packing_list').files[0]);65formData.append('file', document.getElementById('bill_of_lading').files[0]);66 67fetch('/api/extract-all', {68    method: 'POST',69    body: formData70})71.then(res => res.json())72.then(data => console.log(data));73```74 75### Response76 77#### Success (200 OK)78```json79{80  "success": true,81  "extracted_documents": [82    {83      "doc_type": "Invoice",84      "bl_no": "BL123456789",85      "invoice_no": "INV-2024-001",86      "shipper": "Công ty ABC",87      "consignee": "Công ty XYZ",88      "vessel": "EVER GIVEN",89      "containers": [90        {91          "container_no": "CONTAINER001",92          "seal_no": "SEAL001"93        },94        {95          "container_no": "CONTAINER002",96          "seal_no": "SEAL002"97        }98      ],99      "total_weight": 5000.5,100      "total_packages": 100,101      "hs_code_suggestions": ["6204.62", "6204.63"]102    },103    {104      "doc_type": "Packing List",105      "bl_no": "BL123456789",106      "invoice_no": null,107      "shipper": "Công ty ABC",108      "consignee": "Công ty XYZ",109      "vessel": "EVER GIVEN",110      "containers": [111        {112          "container_no": "CONTAINER001",113          "seal_no": "SEAL001"114        },115        {116          "container_no": "CONTAINER002",117          "seal_no": "SEAL002"118        }119      ],120      "total_weight": 5000.5,121      "total_packages": 100,122      "hs_code_suggestions": ["6204.62", "6204.63"]123    }124  ],125  "validation": {126    "flags": [127      {128        "field": "total_weight",129        "status": "warning",130        "message": "Trọng lượng lệch nhau 2.50KG (> 5.00KG)",131        "details": {132          "weights": {133            "invoice": 5000.5,134            "packing_list": 4998.0135          },136          "difference": 2.5,137          "tolerance": 5.0138        }139      }140    ],141    "summary": {142      "total_issues": 1,143      "errors": 0,144      "warnings": 1,145      "error_details": [],146      "warning_details": [147        {148          "field": "total_weight",149          "status": "warning",150          "message": "Trọng lượng lệch nhau 2.50KG (> 5.00KG)",151          "details": {...}152        }153      ],154      "status": "WARNING"155    }156  }157}158```159 160#### Error (400/500)161```json162{163  "error": "No files provided"164}165```166 167---168 169## Schema LogisticsData170 171### Định Nghĩa172```python173class LogisticsData(BaseModel):174    doc_type: str                          # Loại chứng từ: Invoice/PL/BL/Customs175    bl_no: Optional[str]                   # Số vận đơn176    invoice_no: Optional[str]              # Số hóa đơn177    shipper: Optional[str]                 # Tên người xuất khẩu178    consignee: Optional[str]               # Tên người nhập khẩu179    vessel: Optional[str]                  # Tên tàu180    containers: List[Container]            # Danh sách container181    total_weight: float                    # Trọng lượng tổng cộng (KG)182    total_packages: int                    # Số kiện183    hs_code_suggestions: List[str]         # Mã HS gợi ý184```185 186### Container187```python188class Container(BaseModel):189    container_no: str                      # Số container190    seal_no: Optional[str]                 # Số seal191```192 193---194 195## Validation Rules196 197### Error (Cảnh báo Đỏ)198- **bl_no không khớp**: BL number khác nhau giữa các file199- **containers không khớp**: Container numbers thiếu hoặc khác nhau200 201### Warning (Cảnh báo Vàng)202- **total_weight lệch**: Trọng lượng lệch nhau > 5kg203- **total_packages không khớp**: Số kiện khác nhau204- **shipper không khớp**: Tên người xuất khác nhau205- **consignee không khớp**: Tên người nhập khác nhau206- **invoice_no thiếu**: Không tìm thấy số hóa đơn207 208---209 210## Unit Conversion211 212AI Extractor tự động chuyển đổi các đơn vị trọng lượng:213- **LBS → KG**: 1 LBS = 0.453592 KG214- **Tấn (Ton) → KG**: 1 Tấn = 1000 KG215- **KG**: Giữ nguyên216 217---218 219## Error Handling220 221| HTTP Code | Description |222|-----------|-------------|223| 200 | Thành công |224| 400 | Bad Request - File không hợp lệ hoặc thiếu |225| 500 | Internal Server Error - Lỗi xử lý server |226 227---228 229## Status Response230 231Trường `status` trong `validation.summary` có các giá trị:232- **PASSED**: Không có lỗi hoặc cảnh báo233- **WARNING**: Có cảnh báo nhưng không có lỗi234- **FAILED**: Có lỗi235 236---237 238## Lưu Ý239 2401. **Yêu cầu Environment**: Cần có `GEMINI_API_KEY` trong file `.env`2412. **File Size**: Không có giới hạn size cụ thể (phụ thuộc Google Generative AI)2423. **Processing Time**: Tùy thuộc vào độ phức tạp của tài liệu (5-30 giây)2434. **Ngôn Ngữ**: Hỗ trợ tài liệu tiếng Anh và tiếng Việt244