Declarações

Endpoints para gerenciamento de declarações alfandegárias.

GET /declarations

Lista paginada de declarações.

Request

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

Query Parameters

Parâmetro	Tipo	Padrão	Descrição
page	int	1	Número da página
size	int	20	Itens por página
search	string	-	Buscar por referência
risk_level	string	-	Filtrar por nível (low/medium/high/critical)

Exemplo

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/

Detalhes de uma declaração específica.

Request

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

Path Parameters

Parâmetro	Tipo	Descrição
id	int	ID da declaração

Exemplo

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": "Sous-évaluation détectée",
      "severity": "high"
    }
  ],
  "created_at": "2026-01-12T10:00:00Z",
  "updated_at": "2026-01-12T10:00:00Z"
}

Response 404

{
  "detail": "Declaration not found"
}

POST /declarations

Cria uma nova declaração.

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"
}

Campos

Campo	Tipo	Obrigatório	Descrição
reference	string	Sim	Referência única
hs_code	string	Sim	Código SH
description	string	Sim	Descrição da mercadoria
origin_country	string	Sim	Código do país ISO
declared_value	number	Sim	Valor em USD
declared_weight	number	Não	Peso em kg
quantity	int	Não	Quantidade
importer_tax_id	string	Não	NIF do importador

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"
    }
  ]
}

Esquema Declaration

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;
}