Importação

Endpoints para importação de declarações de arquivos CSV/Excel.

POST /imports/csv

Importa declarações de um arquivo CSV.

Request

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

Body

Campo	Tipo	Descrição
file	File	Arquivo CSV a importar

Exemplo com 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

Importa declarações de um arquivo Excel.

Request

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

Body

Campo	Tipo	Descrição
file	File	Arquivo Excel (.xlsx, .xls)

Exemplo

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

Response 200

Mesmo formato que a importação CSV.

Formato do Arquivo

Colunas Obrigatórias

Coluna	Tipo	Exemplo
reference	string	DEC-2026-00100
hs_code	string	8703.23
description	string	Toyota Hilux
origin_country	string	JP
declared_value	number	45000

Colunas Opcionais

Coluna	Tipo	Exemplo
importer_tax_id	string	GW-IMP-001
declared_weight	number	2100
quantity	number	1

Exemplo CSV

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

Códigos de País ISO

Use os códigos ISO 3166-1 alpha-2:

Código	País
GW	Guiné-Bissau
CN	China
JP	Japão
FR	França
PT	Portugal
US	Estados Unidos
DE	Alemanha
SN	Senegal

Limites

Limite	Valor
Tamanho máximo do arquivo	10 MB
Linhas máximas	10.000
Importações simultâneas	1 por usuário

Tratamento de Erros

Erros de Validação

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

Códigos de Erro Comuns

Erro	Causa
Missing required field	Campo obrigatório ausente
Invalid value type	Tipo de dados incorreto
Invalid country code	Código de país não reconhecido
Duplicate reference	Referência já existente
Value out of range	Valor fora dos limites

Processo de Importação

1. Upload do arquivo
   ↓
2. Validação do formato
   ↓
3. Parse das linhas
   ↓
4. Validação dos dados
   ↓
5. Cálculo dos escores de risco
   ↓
6. Criação das declarações
   ↓
7. Geração de alertas (se risco > 75%)
   ↓
8. Atualização dos escores de importadores
   ↓
9. Retorno do relatório de importação

Esquema ImportResult

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