开发者参考

异步 API 批处理

将多个受支持的 API 请求加入队列，无需保持客户端连接即可收集结果。

异步 API 批处理

将多个受支持的 API 请求加入队列，无需保持客户端连接即可收集结果。

POST /v1/batches

批处理的工作方式

每个批次最多接受 100 个受支持的公开 GET 请求。
每个项目仍按其端点的正常价格计费，最终失败的项目将分别退款。
账户中的所有成员均可在 24 小时内查看任务状态和结果。
您可以选择使用 HTTPS Webhook，在处理进入最终状态时通知您的系统。

请求示例

curl -X POST "https://domscan.net/v1/batches" \
  -H "X-API-Key: $DOMSCAN_API_KEY" \
  -H "Idempotency-Key: customer-import-42" \
  -H "Content-Type: application/json" \
  -d '{
    "requests": [
      {"path": "/v1/status", "query": {"domain": "example.com"}},
      {"path": "/v1/dns", "query": {"domain": "example.org", "type": "MX"}}
    ]
  }'

响应字段

字段	类型
`job`	object
`job.id`	string
`job.status`	string
`job.total`	integer
`job.counts`	object
`job.counts.pending`	integer
`job.counts.processing`	integer
`job.counts.succeeded`	integer
`job.counts.failed`	integer
`job.counts.cancelled`	integer
`job.billing`	object
`job.billing.credits_charged`	integer
`job.billing.credits_refunded`	integer
`job.billing.credits_net`	integer
`job.webhook`	object
`job.webhook.configured`	boolean
`job.webhook.status`	string
`job.webhook.attempts`	integer
`job.status_url`	string
`job.results_url`	string
`job.poll_after_ms`	integer \| null
`job.created_at`	string
`job.started_at`	string \| null
`job.completed_at`	string \| null
`job.cancelled_at`	string \| null
`job.updated_at`	string
`job.processing_deadline_at`	string
`job.results_expires_at`	string

响应示例

{
  "job": {
    "id": "string",
    "status": "queued",
    "total": 1,
    "counts": {
      "pending": 1,
      "processing": 1,
      "succeeded": 1,
      "failed": 1,
      "cancelled": 1
    },
    "billing": {
      "credits_charged": 1,
      "credits_refunded": 1,
      "credits_net": 1
    },
    "webhook": {
      "configured": true,
      "status": "not_configured",
      "attempts": 1
    },
    "status_url": "https://example.com",
    "results_url": "https://example.com",
    "poll_after_ms": 1,
    "created_at": "2026-04-15T12:00:00Z",
    "started_at": "2026-04-15T12:00:00Z",
    "completed_at": "2026-04-15T12:00:00Z",
    "cancelled_at": "2026-04-15T12:00:00Z",
    "updated_at": "2026-04-15T12:00:00Z",
    "processing_deadline_at": "2026-04-15T12:00:00Z",
    "results_expires_at": "2026-04-15T12:00:00Z"
  }
}

轮询与取消

轮询状态端点、按顺序获取结果，或取消尚未开始的任务。

GET /v1/batches/{job_id}
GET /v1/batches/{job_id}/results
DELETE /v1/batches/{job_id}

带签名的完成 Webhook

Webhook 签名使用 HMAC-SHA256 计算，签名内容依次为时间戳、一个英文句点和未经修改的请求正文。接受通知前请先验证时间戳。

X-DomScan-Event: batch.completed
X-DomScan-Timestamp: 1785231000
X-DomScan-Signature: sha256=...

GET /v1/batches

查询参数

参数	类型	必需
limit	integer	可选

响应字段

字段	类型
`jobs[]`	object[]
`jobs[]`	object
`jobs[].id`	string
`jobs[].status`	string
`jobs[].total`	integer
`jobs[].counts`	object
`jobs[].counts.pending`	integer
`jobs[].counts.processing`	integer
`jobs[].counts.succeeded`	integer
`jobs[].counts.failed`	integer
`jobs[].counts.cancelled`	integer
`jobs[].billing`	object
`jobs[].billing.credits_charged`	integer
`jobs[].billing.credits_refunded`	integer
`jobs[].billing.credits_net`	integer
`jobs[].webhook`	object
`jobs[].webhook.configured`	boolean
`jobs[].webhook.status`	string
`jobs[].webhook.attempts`	integer
`jobs[].status_url`	string
`jobs[].results_url`	string
`jobs[].poll_after_ms`	integer \| null
`jobs[].created_at`	string
`jobs[].started_at`	string \| null
`jobs[].completed_at`	string \| null
`jobs[].cancelled_at`	string \| null
`jobs[].updated_at`	string
`jobs[].processing_deadline_at`	string
`jobs[].results_expires_at`	string
`retention_hours`	integer

请求示例

curl -H "X-API-Key: $DOMSCAN_API_KEY" "https://domscan.net/v1/batches?limit=25"

响应示例

{
  "jobs": [
    {
      "id": "string",
      "status": "queued",
      "total": 1,
      "counts": {
        "pending": 1,
        "processing": 1,
        "succeeded": 1,
        "failed": 1,
        "cancelled": 1
      },
      "billing": {
        "credits_charged": 1,
        "credits_refunded": 1,
        "credits_net": 1
      },
      "webhook": {
        "configured": true,
        "status": "not_configured",
        "attempts": 1
      },
      "status_url": "https://example.com",
      "results_url": "https://example.com",
      "poll_after_ms": 1,
      "created_at": "2026-04-15T12:00:00Z",
      "started_at": "2026-04-15T12:00:00Z",
      "completed_at": "2026-04-15T12:00:00Z",
      "cancelled_at": "2026-04-15T12:00:00Z",
      "updated_at": "2026-04-15T12:00:00Z",
      "processing_deadline_at": "2026-04-15T12:00:00Z",
      "results_expires_at": "2026-04-15T12:00:00Z"
    }
  ],
  "retention_hours": 24
}

GET /v1/batches/:job_id

响应字段

字段	类型
`job`	object
`job.id`	string
`job.status`	string
`job.total`	integer
`job.counts`	object
`job.counts.pending`	integer
`job.counts.processing`	integer
`job.counts.succeeded`	integer
`job.counts.failed`	integer
`job.counts.cancelled`	integer
`job.billing`	object
`job.billing.credits_charged`	integer
`job.billing.credits_refunded`	integer
`job.billing.credits_net`	integer
`job.webhook`	object
`job.webhook.configured`	boolean
`job.webhook.status`	string
`job.webhook.attempts`	integer
`job.status_url`	string
`job.results_url`	string
`job.poll_after_ms`	integer \| null
`job.created_at`	string
`job.started_at`	string \| null
`job.completed_at`	string \| null
`job.cancelled_at`	string \| null
`job.updated_at`	string
`job.processing_deadline_at`	string
`job.results_expires_at`	string

请求示例

curl -H "X-API-Key: $DOMSCAN_API_KEY" "https://domscan.net/v1/batches/example.com"

响应示例

{
  "job": {
    "id": "string",
    "status": "queued",
    "total": 1,
    "counts": {
      "pending": 1,
      "processing": 1,
      "succeeded": 1,
      "failed": 1,
      "cancelled": 1
    },
    "billing": {
      "credits_charged": 1,
      "credits_refunded": 1,
      "credits_net": 1
    },
    "webhook": {
      "configured": true,
      "status": "not_configured",
      "attempts": 1
    },
    "status_url": "https://example.com",
    "results_url": "https://example.com",
    "poll_after_ms": 1,
    "created_at": "2026-04-15T12:00:00Z",
    "started_at": "2026-04-15T12:00:00Z",
    "completed_at": "2026-04-15T12:00:00Z",
    "cancelled_at": "2026-04-15T12:00:00Z",
    "updated_at": "2026-04-15T12:00:00Z",
    "processing_deadline_at": "2026-04-15T12:00:00Z",
    "results_expires_at": "2026-04-15T12:00:00Z"
  }
}

GET /v1/batches/:job_id/results

查询参数

参数	类型	必需
job_id	string	必需
after	integer	可选
limit	integer	可选

响应字段

字段	类型
`job`	object
`job.id`	string
`job.status`	string
`job.total`	integer
`job.counts`	object
`job.counts.pending`	integer
`job.counts.processing`	integer
`job.counts.succeeded`	integer
`job.counts.failed`	integer
`job.counts.cancelled`	integer
`job.billing`	object
`job.billing.credits_charged`	integer
`job.billing.credits_refunded`	integer
`job.billing.credits_net`	integer
`job.webhook`	object
`job.webhook.configured`	boolean
`job.webhook.status`	string
`job.webhook.attempts`	integer
`job.status_url`	string
`job.results_url`	string
`job.poll_after_ms`	integer \| null
`job.created_at`	string
`job.started_at`	string \| null
`job.completed_at`	string \| null
`job.cancelled_at`	string \| null
`job.updated_at`	string
`job.processing_deadline_at`	string
`job.results_expires_at`	string
`results[]`	object[]
`results[]`	object
`results[].position`	integer
`results[].reference`	string \| null
`results[].request`	object
`results[].request.method`	string
`results[].request.path`	string
`results[].request.query`	object
`results[].status`	string
`results[].attempts`	integer
`results[].http_status`	integer \| null
`results[].result`	object \| null
`results[].error`	object \| null
`results[].billing`	object
`results[].started_at`	string \| null
`results[].completed_at`	string \| null
`next_after`	integer \| null

请求示例

curl -H "X-API-Key: $DOMSCAN_API_KEY" "https://domscan.net/v1/batches/example.com/results?after=example.com&limit=25"

响应示例

{
  "job": {
    "id": "string",
    "status": "queued",
    "total": 1,
    "counts": {
      "pending": 1,
      "processing": 1,
      "succeeded": 1,
      "failed": 1,
      "cancelled": 1
    },
    "billing": {
      "credits_charged": 1,
      "credits_refunded": 1,
      "credits_net": 1
    },
    "webhook": {
      "configured": true,
      "status": "not_configured",
      "attempts": 1
    },
    "status_url": "https://example.com",
    "results_url": "https://example.com",
    "poll_after_ms": 1,
    "created_at": "2026-04-15T12:00:00Z",
    "started_at": "2026-04-15T12:00:00Z",
    "completed_at": "2026-04-15T12:00:00Z",
    "cancelled_at": "2026-04-15T12:00:00Z",
    "updated_at": "2026-04-15T12:00:00Z",
    "processing_deadline_at": "2026-04-15T12:00:00Z",
    "results_expires_at": "2026-04-15T12:00:00Z"
  },
  "results": [
    {
      "position": 1,
      "reference": "string",
      "request": {
        "method": "GET",
        "path": "string",
        "query": {}
      },
      "status": "pending",
      "attempts": 1,
      "http_status": 1,
      "result": {},
      "error": {},
      "billing": {},
      "started_at": "2026-04-15T12:00:00Z",
      "completed_at": "2026-04-15T12:00:00Z"
    }
  ],
  "next_after": 1
}

DELETE /v1/batches/:job_id

响应字段

字段	类型
`job`	object
`job.id`	string
`job.status`	string
`job.total`	integer
`job.counts`	object
`job.counts.pending`	integer
`job.counts.processing`	integer
`job.counts.succeeded`	integer
`job.counts.failed`	integer
`job.counts.cancelled`	integer
`job.billing`	object
`job.billing.credits_charged`	integer
`job.billing.credits_refunded`	integer
`job.billing.credits_net`	integer
`job.webhook`	object
`job.webhook.configured`	boolean
`job.webhook.status`	string
`job.webhook.attempts`	integer
`job.status_url`	string
`job.results_url`	string
`job.poll_after_ms`	integer \| null
`job.created_at`	string
`job.started_at`	string \| null
`job.completed_at`	string \| null
`job.cancelled_at`	string \| null
`job.updated_at`	string
`job.processing_deadline_at`	string
`job.results_expires_at`	string

请求示例

curl -X DELETE "https://domscan.net/v1/batches/example.com" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $DOMSCAN_API_KEY" \
  -d '{}'

响应示例

{
  "job": {
    "id": "string",
    "status": "queued",
    "total": 1,
    "counts": {
      "pending": 1,
      "processing": 1,
      "succeeded": 1,
      "failed": 1,
      "cancelled": 1
    },
    "billing": {
      "credits_charged": 1,
      "credits_refunded": 1,
      "credits_net": 1
    },
    "webhook": {
      "configured": true,
      "status": "not_configured",
      "attempts": 1
    },
    "status_url": "https://example.com",
    "results_url": "https://example.com",
    "poll_after_ms": 1,
    "created_at": "2026-04-15T12:00:00Z",
    "started_at": "2026-04-15T12:00:00Z",
    "completed_at": "2026-04-15T12:00:00Z",
    "cancelled_at": "2026-04-15T12:00:00Z",
    "updated_at": "2026-04-15T12:00:00Z",
    "processing_deadline_at": "2026-04-15T12:00:00Z",
    "results_expires_at": "2026-04-15T12:00:00Z"
  }
}