개발자 참고자료

비동기 API 배치

클라이언트 연결을 계속 열어 두지 않고도 지원되는 여러 API 요청을 대기열에 넣고 결과를 수집할 수 있습니다.

비동기 API 배치

클라이언트 연결을 계속 열어 두지 않고도 지원되는 여러 API 요청을 대기열에 넣고 결과를 수집할 수 있습니다.

POST /v1/batches

배치 처리 방식

각 배치에는 지원되는 공개 GET 요청을 최대 100개까지 넣을 수 있습니다.
각 항목에는 해당 엔드포인트의 일반 요금이 적용되며 최종 실패 항목은 개별적으로 환불됩니다.
계정의 모든 멤버가 24시간 동안 작업 상태와 결과를 확인할 수 있습니다.
선택 사항인 HTTPS 웹훅을 사용하면 처리가 최종 상태에 도달했을 때 시스템에 알릴 수 있습니다.

예제 요청

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}

서명된 완료 웹훅

웹훅 서명은 타임스탬프, 마침표, 수정되지 않은 요청 본문을 차례로 연결한 값에 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"
  }
}