Import

Endpoints for importing declarations from CSV/Excel files.

POST /imports/csv

Imports declarations from a CSV file.

Request

POST /api/v1/imports/csv
Authorization: Bearer <token>
Content-Type: multipart/form-data

Body

Field	Type	Description
file	File	CSV file to import

Example with curl

curl -X POST https://api.gbfiscalai.srv1164291.hstgr.cloud/api/v1/imports/csv \
  -H "Authorization: Bearer <token>" \
  -F "file=@declarations.csv"

Response 200

{
  "total_rows": 100,
  "imported": 95,
  "errors": 5,
  "high_risk_count": 12,
  "alerts_created": 8,
  "error_details": [
    {
      "row": 15,
      "error": "Missing required field: hs_code"
    },
    {
      "row": 42,
      "error": "Invalid country code: XYZ"
    }
  ]
}

POST /imports/excel

Imports declarations from an Excel file.

Request

POST /api/v1/imports/excel
Authorization: Bearer <token>
Content-Type: multipart/form-data

Body

Field	Type	Description
file	File	Excel file (.xlsx, .xls)

Example

curl -X POST https://api.gbfiscalai.srv1164291.hstgr.cloud/api/v1/imports/excel \
  -H "Authorization: Bearer <token>" \
  -F "file=@declarations.xlsx"

Response 200

Same format as CSV import.

File Format

Required Columns

Column	Type	Example
reference	string	DEC-2026-00100
hs_code	string	8703.23
description	string	Toyota Hilux
origin_country	string	JP
declared_value	number	45000

Optional Columns

Column	Type	Example
importer_tax_id	string	GW-IMP-001
declared_weight	number	2100
quantity	number	1

CSV Example

reference,importer_tax_id,hs_code,description,origin_country,declared_value,declared_weight,quantity
DEC-2026-00100,GW-IMP-001,8703.23,Toyota Hilux 2023,JP,45000,2100,1
DEC-2026-00101,GW-IMP-002,8517.12,iPhone 15 Pro Max,CN,150,0.2,500
DEC-2026-00102,GW-IMP-003,2204.21,Vin rouge Bordeaux AOC,FR,8500,750,500

ISO Country Codes

Use ISO 3166-1 alpha-2 codes:

Code	Country
GW	Guinea-Bissau
CN	China
JP	Japan
FR	France
PT	Portugal
US	United States
DE	Germany
SN	Senegal

Limits

Limit	Value
Max file size	10 MB
Max rows	10,000
Simultaneous imports	1 per user

Error Handling

Validation Errors

{
  "error_details": [
    {
      "row": 5,
      "error": "Missing required field: reference"
    }
  ]
}

Common Error Codes

Error	Cause
Missing required field	Required field is missing
Invalid value type	Data type is incorrect
Invalid country code	Country code not recognized
Duplicate reference	Reference already exists
Value out of range	Value is out of limits

Import Process

1. File upload
   ↓
2. Format validation
   ↓
3. Line parsing
   ↓
4. Data validation
   ↓
5. Risk score calculation
   ↓
6. Declaration creation
   ↓
7. Alert generation (if risk > 75%)
   ↓
8. Update importer scores
   ↓
9. Return import report

ImportResult Schema

interface ImportResult {
  total_rows: number;
  imported: number;
  errors: number;
  high_risk_count: number;
  alerts_created: number;
  error_details: Array<{
    row: number;
    error: string;
  }>;
}