Ingest API

The Ingest API receives batched data pushes from the FinancialDataset platform. It uses FD-API-KEY header authentication.

Authentication

All ingest endpoints require a valid API key passed in the FD-API-KEY header.

POST /api/v1/financialdataset/ingest/batches
Content-Type: application/json
FD-API-KEY: your-api-key-here

Endpoints

POST /api/v1/financialdataset/ingest/batches

Batch data ingestion endpoint. Supports both incremental updates and full snapshots.

Request Body:

{
  "meta": {
    "schema_version": "3.0",
    "batch_id": "fdp_20260530_100000_etf_daily_0001",
    "source_system": "financialdataset",
    "source_run_id": "run_20260530_001",
    "dataset": "etf_daily",
    "table": "etf_daily",
    "operation": "upsert",
    "snapshot_type": "incremental",
    "business_date": "2026-05-30",
    "source": "eastmoney.etf_spot_em",
    "record_count": 1485,
    "send_time": "2026-05-30T10:00:00Z"
  },
  "records": [{
    "idempotency_key": "etf_daily:symbol=510300.SH:date=2026-05-30:source=eastmoney.etf_spot_em",
    "unique_key": {"symbol": "510300.SH", "date": "2026-05-30", "source": "eastmoney.etf_spot_em"},
    "data": {
      "symbol": "510300.SH",
      "date": "2026-05-30",
      "close": 4.923,
      "volume": 6566854,
      "source": "eastmoney.etf_spot_em",
      "updated_at": "2026-05-30T10:00:00Z"
    }
  }],
  "checksum": {
    "sha256": "abc123..."
  }
}

Meta Fields:

Field	Type	Required	Description
schema_version	string	✅	Fixed "3.0"
batch_id	string	✅	Unique batch identifier
source_system	string	✅	Fixed "financialdataset"
source_run_id	string	✅	Collection run ID
dataset	string	✅	Dataset name (see supported datasets below)
table	string	✅	Target table name
operation	string	✅	Fixed "upsert"
snapshot_type	string	✅	"incremental" or "full_snapshot"
business_date	string	✅	Business date YYYY-MM-DD
source	string	✅	Data source identifier
record_count	number	✅	Number of records
send_time	string	✅	ISO 8601 UTC timestamp

Responses:

Status	Body	Description
200	{status: "accepted"}	All records processed successfully
200	{status: "duplicate"}	Batch already processed (idempotent)
207	{status: "partial"}	Some records failed validation
400	{code: 4001}	Invalid request (missing meta/records/unknown dataset)
422	{code: 4220}	Checksum mismatch

GET /api/v1/financialdataset/ingest/batches/:batch_id

Query batch processing status.

Response:

{
  "code": 0,
  "message": "ok",
  "batch_id": "fdp_20260530_100000_etf_daily_0001",
  "dataset": "etf_daily",
  "source": "eastmoney.etf_spot_em",
  "operation": "upsert",
  "snapshot_type": "incremental",
  "business_date": "2026-05-30",
  "source_system": "financialdataset",
  "source_run_id": "run_20260530_001",
  "record_count": 1485,
  "checksum": "abc123...",
  "status": "accepted",
  "accepted": 1485,
  "rejected": 0,
  "duplicate": 0,
  "errors": [],
  "created_at": "2026-05-30T10:00:05Z",
  "processed_at": "2026-05-30T10:00:06Z"
}

Supported Datasets

Silver Layer — Standardized Market Data

Dataset	Table	Description
etf_daily	etf_daily	ETF daily quotes (~1,500 ETFs)
index_daily	index_daily	Index daily quotes (A-share & US)
fx	fx	Foreign exchange rates
qdii_nav	qdii_nav	QDII fund NAV
industry_sw	industry_sw	Shenwan industry classification
stock_daily	stock_daily	A-share individual stock daily quotes

Gold Layer — Feature Factors

Dataset	Table	Description
etf_daily_features	etf_daily_features	ETF daily technical indicators
etf_risk_features	etf_risk_features	ETF risk metrics (multi-window)
etf_cross_border_features	etf_cross_border_features	QDII cross-border ETF factors
index_daily_features	index_daily_features	Index daily factor indicators

Error Codes

Code	Status	Meaning
4010	401	Missing FD-API-KEY header
4012	401	Invalid API key
4001	400	Invalid request format or missing required fields
4220	422	Checksum mismatch
4040	404	Batch not found
2070	207	Partial success (some records rejected)