Declarations

Endpoints for managing customs declarations.

GET /declarations

Paginated list of declarations.

Request

GET /api/v1/declarations
Authorization: Bearer <token>

Query Parameters

Parameter	Type	Default	Description
page	int	1	Page number
size	int	20	Items per page
search	string	-	Search by reference
risk_level	string	-	Filter by level (low/medium/high/critical)

Example

curl "https://api.gbfiscalai.srv1164291.hstgr.cloud/api/v1/declarations?page=1&size=10&risk_level=high" \
  -H "Authorization: Bearer <token>"

Response 200

{
  "items": [
    {
      "id": 1,
      "reference": "DEC-2026-00001",
      "hs_code": "8703.23",
      "description": "Toyota Hilux 2023",
      "origin_country": "JP",
      "declared_value": 45000.00,
      "declared_weight": 2100.00,
      "quantity": 1,
      "risk_score": 72.5,
      "risk_level": "high",
      "status": "pending",
      "importer_id": 1,
      "created_at": "2026-01-12T10:00:00Z"
    }
  ],
  "total": 150,
  "page": 1,
  "size": 10,
  "pages": 15
}

GET /declarations/

Details of a specific declaration.

Request

GET /api/v1/declarations/{id}
Authorization: Bearer <token>

Path Parameters

Parameter	Type	Description
id	int	Declaration ID

Example

curl https://api.gbfiscalai.srv1164291.hstgr.cloud/api/v1/declarations/1 \
  -H "Authorization: Bearer <token>"

Response 200

{
  "id": 1,
  "reference": "DEC-2026-00001",
  "hs_code": "8703.23",
  "description": "Toyota Hilux 2023",
  "origin_country": "JP",
  "declared_value": 45000.00,
  "declared_weight": 2100.00,
  "quantity": 1,
  "risk_score": 72.5,
  "risk_level": "high",
  "status": "pending",
  "importer": {
    "id": 1,
    "name": "Import Auto GW",
    "tax_id": "GW-IMP-001"
  },
  "alerts": [
    {
      "id": 5,
      "title": "Undervaluation detected",
      "severity": "high"
    }
  ],
  "created_at": "2026-01-12T10:00:00Z",
  "updated_at": "2026-01-12T10:00:00Z"
}

Response 404

{
  "detail": "Declaration not found"
}

POST /declarations

Creates a new declaration.

Request

POST /api/v1/declarations
Authorization: Bearer <token>
Content-Type: application/json

Body

{
  "reference": "DEC-2026-00100",
  "hs_code": "8703.23",
  "description": "Toyota Hilux 2023",
  "origin_country": "JP",
  "declared_value": 45000.00,
  "declared_weight": 2100.00,
  "quantity": 1,
  "importer_tax_id": "GW-IMP-001"
}

Fields

Field	Type	Required	Description
reference	string	Yes	Unique reference
hs_code	string	Yes	HS code
description	string	Yes	Goods description
origin_country	string	Yes	ISO country code
declared_value	number	Yes	Value in USD
declared_weight	number	No	Weight in kg
quantity	int	No	Quantity
importer_tax_id	string	No	Importer tax ID

Response 201

{
  "id": 100,
  "reference": "DEC-2026-00100",
  "risk_score": 65.0,
  "risk_level": "high",
  "status": "pending",
  "created_at": "2026-01-12T12:00:00Z"
}

Response 422

{
  "detail": [
    {
      "loc": ["body", "hs_code"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}

Declaration Schema

interface Declaration {
  id: number;
  reference: string;
  hs_code: string;
  description: string;
  origin_country: string;
  declared_value: number;
  declared_weight?: number;
  quantity?: number;
  risk_score: number;
  risk_level: 'low' | 'medium' | 'high' | 'critical';
  status: 'pending' | 'processing' | 'cleared' | 'flagged' | 'rejected';
  importer_id?: number;
  created_at: string;
  updated_at: string;
}