엔드포인트를 큐로 호출 (async)

카탈로그 조회는 결과를 기다리거나(sync) 즉시 응답할 수 있습니다(queue / Async). 큐 모드는 한 행 Smart Batch를 만듭니다. 워커가 나중에 같은 엔드포인트를 호출하고 시도를 기록합니다. 크레딧은 그 워커 호출에서 차감되며, 큐에 넣을 때는 차감되지 않습니다.

이 페이지는 백엔드에서 엔드포인트를 큐로 호출하는 A–Z 가이드입니다. 제품, 마법사, 대시보드는 SmartBatch부터 보세요.

async를 쓰는 시점

HTTP 클라이언트가 느린 조회를 기다리지 않게 하려면 type=queue를 사용합니다.

웹훅이나 이메일로 나중에 결과를 처리합니다.
ai.verifik.co에서 배치를 열고 대시보드를 봅니다.
api.verifik.co에서 GET /v2/smart-batches/:id를 폴링합니다.

같은 응답에서 신원 페이로드가 필요하면 sync를 사용합니다(type 생략 또는 type=sync).

인증

이미 api.verifik.co에 보내는 동일한 클라이언트 JWT를 사용합니다.

Authorization: Bearer <client JWT>

async.verifik.co는 해당 헤더를 전달합니다. Node가 토큰을 검증하고 배치를 저장한 뒤, 워커가 당신 클라이언트로 기능을 호출할 수 있도록 짧은 수명의 JWT를 발급합니다. 큐를 위한 두 번째 키를 저장하지 않습니다.

기본 URL

https://async.verifik.co

기능에 문서화된 같은 카탈로그 경로를 붙입니다. 예:

기능	경로
콜롬비아 신분증	`/v2/co/cedula`
콜롬비아 가입(SISPRO)	`/v2/co/afiliaciones`
페루 DNI	`/v2/pe/cedula`

카탈로그 URL이 없는 passwordless 및 PDF 기능은 큐에 넣을 수 없습니다.

queue 파라미터

이미 보내는 같은 쿼리(GET) 또는 본문(POST)에 type=queue를 추가합니다.

`type`	동작	응답
생략 또는 `sync`	기능을 기다리고 그 본문을 반환	`200` / `401` / `404` / `409` / `504`
`queue`	한 행 Smart Batch를 만듭니다. 이 요청에서는 기능을 호출하지 않습니다	`202`

type은 생략, sync, 또는 queue여야 합니다. 다른 값은 검증 오류입니다.

Request

콜롬비아 신분증

curl
Node.js
Python

curl -sS -H "Authorization: Bearer $JWT" \
  "https://async.verifik.co/v2/co/cedula?documentType=CC&documentNumber=1032386359&type=queue"

import axios from 'axios';

const { data, status } = await axios.get(
  'https://async.verifik.co/v2/co/cedula',
  {
    params: {
      documentType: 'CC',
      documentNumber: '1032386359',
      type: 'queue',
    },
    headers: {
      Authorization: `Bearer ${process.env.JWT}`,
    },
  },
);

console.log(status, data);

import os
import requests

response = requests.get(
    "https://async.verifik.co/v2/co/cedula",
    params={
        "documentType": "CC",
        "documentNumber": "1032386359",
        "type": "queue",
    },
    headers={"Authorization": f"Bearer {os.environ['JWT']}"},
)
print(response.status_code, response.json())

콜롬비아 가입 (SISPRO)

curl
Node.js
Python

curl -sS -H "Authorization: Bearer $JWT" \
  "https://async.verifik.co/v2/co/afiliaciones?documentType=CC&documentNumber=1007463534&date=09/05/2008&type=queue"

import axios from 'axios';

const { data, status } = await axios.get(
  'https://async.verifik.co/v2/co/afiliaciones',
  {
    params: {
      documentType: 'CC',
      documentNumber: '1007463534',
      date: '09/05/2008',
      type: 'queue',
    },
    headers: {
      Authorization: `Bearer ${process.env.JWT}`,
    },
  },
);

console.log(status, data);

import os
import requests

response = requests.get(
    "https://async.verifik.co/v2/co/afiliaciones",
    params={
        "documentType": "CC",
        "documentNumber": "1007463534",
        "date": "09/05/2008",
        "type": "queue",
    },
    headers={"Authorization": f"Bearer {os.environ['JWT']}"},
)
print(response.status_code, response.json())

페루 DNI

curl
Node.js
Python

curl -sS -H "Authorization: Bearer $JWT" \
  "https://async.verifik.co/v2/pe/cedula?documentType=DNI&documentNumber=12345678&type=queue"

import axios from 'axios';

const { data, status } = await axios.get(
  'https://async.verifik.co/v2/pe/cedula',
  {
    params: {
      documentType: 'DNI',
      documentNumber: '12345678',
      type: 'queue',
    },
    headers: {
      Authorization: `Bearer ${process.env.JWT}`,
    },
  },
);

console.log(status, data);

import os
import requests

response = requests.get(
    "https://async.verifik.co/v2/pe/cedula",
    params={
        "documentType": "DNI",
        "documentNumber": "12345678",
        "type": "queue",
    },
    headers={"Authorization": f"Bearer {os.environ['JWT']}"},
)
print(response.status_code, response.json())

POST 엔드포인트에서는 나머지 필드와 함께 JSON 본문에 type을 보냅니다. 저장된 입력 필드로 보내지 마세요. 서비스는 inputData를 저장하기 전에 type을 제거합니다.

Response

202

{
  "status": "queued",
  "batchId": "665f0c2e2c1a4a0012ab3456",
  "rowIndex": 0,
  "attemptCount": 0
}

필드	의미
`status`	성공적인 enqueue에서 항상 `queued`
`batchId`	Smart Batch id. ai.verifik.co에서 열거나 Node를 폴링
`rowIndex`	해당 배치의 행(한 행 API 호출은 `0`)
`attemptCount`	이미 기록된 시도 수(enqueue 시 `0`)

다음에 일어나는 일

요청이 클라이언트와 queue key에 대한 Async 구성을 만들거나 재사용합니다.
즉시 202를 받습니다. JWT는 행에 저장되지 않습니다.
워커가 행을 가져오고, 기능 URL을 호출하고, 시도를 추가합니다.
행 또는 배치가 종료되면 Node가 구성 웹훅으로 POST하고, 설정했다면 완료 이메일을 보냅니다.

Queue keys:

기능	Queue key	구성 이름
콜롬비아 신분증	`co.cedula.queue`	Queue Cedula
콜롬비아 가입	`co.sispro.queue`	Queue SISPRO
기타 모든 카탈로그 기능	`{featureCode}.queue`	`Queue {feature name}`

자동 생성된 Queue … 구성을 한 번 편집하세요(웹훅, 이메일). 이후 type=queue 호출이 이를 재사용합니다.

크레딧은 202가 아니라 워커 호출에서 차감됩니다.

결과를 받는 방법

웹훅 또는 이메일

ai.verifik.co의 배치 구성에서 웹훅 URL과 완료 시 이메일을 설정합니다(생성 마법사 → 검토 및 생성, 또는 구성 편집). 쿼리 파라미터가 아닙니다.

Smart Monitor의 웹훅 목록과 상세에는 연결된 배치 구성이 표시됩니다.

Smart-Agent 대시보드

https://ai.verifik.co를 열고 202의 batchId로 이동한 뒤 상태, 시도, 행당 비용, 연결된 웹훅을 확인합니다.

먼저 구성(실행 모드 Async)을 만든 다음 API에서 큐에 넣어 행이 그 레시피에 들어가게 할 수도 있습니다.

배치 폴링

GET https://api.verifik.co/v2/smart-batches/{batchId}
Authorization: Bearer <same client JWT>

행 상세에는 시도 타임라인이 있습니다. 완료된 시도에는 기능 페이로드가 들어 있습니다.

제한

passwordless 및 PDF 생성기 기능에는 카탈로그 URL이 없어 큐에 넣을 수 없습니다.
404와 검증 오류(MissingParameter 등)는 재시도하지 않습니다.
재시도 가능한 결과는 429, 5xx, timeout / upstream-unavailable 코드입니다.
type은 sync, queue, 또는 생략만 가능합니다.

선택적 명시 enqueue

카탈로그 경로의 type=queue를 우선하세요. queue key를 이미 알고 있다면 행을 직접 만들 수 있습니다.

POST https://api.verifik.co/v2/smart-batches/from-queue
Authorization: Bearer <client JWT>
Content-Type: application/json

{
  "queueKey": "peru_identity_lookup.queue",
  "name": "Queue Peru - National ID Verification",
  "featureCode": "peru_identity_lookup",
  "inputData": {
    "documentType": "DNI",
    "documentNumber": "12345678"
  }
}

이 명시 본문이 필요하지 않다면 https://async.verifik.co/{path}?type=queue를 사용하세요.

async를 쓰는 시점​

인증​

기본 URL​

queue 파라미터​

Request​

콜롬비아 신분증​

콜롬비아 가입 (SISPRO)​

페루 DNI​

Response​

다음에 일어나는 일​

결과를 받는 방법​

웹훅 또는 이메일​

Smart-Agent 대시보드​

배치 폴링​

제한​

선택적 명시 enqueue​

관련​