Importadores

Endpoints para consulta de importadores.

GET /importers

Lista paginada de importadores.

Request

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

Query Parameters

Parâmetro	Tipo	Padrão	Descrição
page	int	1	Número da página
size	int	20	Elementos por página
search	string	-	Pesquisa por nome ou NIF

Exemplo

curl "https://api.gbfiscalai.srv1164291.hstgr.cloud/api/v1/importers?search=Auto" \
  -H "Authorization: Bearer <token>"

Response 200

{
  "items": [
    {
      "id": 1,
      "name": "Import Auto GW",
      "tax_id": "GW-IMP-001",
      "address": "Av. Amilcar Cabral, Bissau",
      "city": "Bissau",
      "country": "GW",
      "contact_email": "contact@importauto.gw",
      "contact_phone": "+245 955 123 456",
      "risk_score": 45.5,
      "risk_level": "medium",
      "total_declarations": 127,
      "flagged_count": 8,
      "total_value": 2500000.00,
      "created_at": "2025-06-15T00:00:00Z"
    }
  ],
  "total": 50,
  "page": 1,
  "size": 20,
  "pages": 3
}

GET /importers/

Detalhes de um importador específico.

Request

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

Response 200

{
  "id": 1,
  "name": "Import Auto GW",
  "tax_id": "GW-IMP-001",
  "address": "Av. Amilcar Cabral, Bissau",
  "city": "Bissau",
  "country": "GW",
  "contact_email": "contact@importauto.gw",
  "contact_phone": "+245 955 123 456",
  "risk_score": 45.5,
  "risk_level": "medium",
  "total_declarations": 127,
  "flagged_count": 8,
  "total_value": 2500000.00,
  "recent_declarations": [
    {
      "id": 150,
      "reference": "DEC-2026-00150",
      "declared_value": 45000,
      "risk_score": 35.0,
      "created_at": "2026-01-10T00:00:00Z"
    }
  ],
  "alerts_history": [
    {
      "id": 25,
      "title": "Subavaliação detectada",
      "status": "resolved",
      "created_at": "2025-12-01T00:00:00Z"
    }
  ],
  "created_at": "2025-06-15T00:00:00Z",
  "updated_at": "2026-01-10T00:00:00Z"
}

Response 404

{
  "detail": "Importer not found"
}

GET /importers/{id}/declarations

Declarações de um importador.

Request

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

Query Parameters

Parâmetro	Tipo	Padrão	Descrição
page	int	1	Número da página
size	int	20	Elementos por página

Response 200

{
  "items": [
    {
      "id": 150,
      "reference": "DEC-2026-00150",
      "hs_code": "8703.23",
      "declared_value": 45000,
      "risk_score": 35.0,
      "status": "cleared",
      "created_at": "2026-01-10T00:00:00Z"
    }
  ],
  "total": 127,
  "page": 1,
  "size": 20,
  "pages": 7
}

Esquema Importer

interface Importer {
  id: number;
  name: string;
  tax_id: string;
  address?: string;
  city?: string;
  country: string;
  contact_email?: string;
  contact_phone?: string;
  risk_score: number;
  risk_level: 'low' | 'medium' | 'high' | 'critical';
  total_declarations: number;
  flagged_count: number;
  total_value: number;
  created_at: string;
  updated_at: string;
}

Cálculo do Risk Score

O escore de risco do importador é calculado segundo:

risk_score = (
  media_scores_declaracoes * 0.5
  + taxa_declaracoes_sinalizadas * 0.3
  + fator_antiguidade * 0.2
)

Fatores

Fator	Peso	Descrição
Média de scores	50%	Escore médio das 50 últimas declarações
Taxa de sinalização	30%	Razão declarações sinalizadas / total
Antiguidade	20%	Bônus para histórico positivo longo