기업 확인(KYB) CRUD 작업: 기업 엔티티 관리

모든 기업 엔티티 관리는 /v3/businesses/ 아래의 공개 endpoint 6개를 통해 이루어집니다. 이 페이지에서는 개념적인 흐름을 설명합니다. 전체 요청 및 응답 스키마는 API 레퍼런스를 참고하세요.

기업 목록 조회

GET /v3/businesses/ 애플리케이션의 기업을 페이지 단위로 나누어 조회합니다. 상태, 검색어, 국가, 날짜 범위로 필터링할 수 있습니다.

curl -G https://verification.didit.me/v3/businesses/ \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode "status=ACTIVE" \
  --data-urlencode "country_code=GBR" \
  --data-urlencode "page_size=50"

기업 조회

GET /v3/businesses/{vendor_data}/ vendor_data로 기업 한 곳을 조회합니다.

curl https://verification.didit.me/v3/businesses/biz-acme/ \
  -H "x-api-key: YOUR_API_KEY"

기업 생성

POST /v3/businesses/create/ 기업 확인(KYB) 세션을 실행하기 전에 기업을 미리 생성합니다.

curl -X POST https://verification.didit.me/v3/businesses/create/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "vendor_data": "biz-acme",
    "display_name": "Acme Corp",
    "country_code": "GBR",
    "metadata": { "partner": "Acme Holdings" }
  }'

같은 vendor_data를 가진 기업이 이미 있으면 충돌 오류를 반환합니다. 기존 기업을 수정하려면 PATCH를 사용하세요.

기업 수정

PATCH /v3/businesses/{vendor_data}/ 수정 가능한 프로필 필드를 업데이트합니다. 레지스트리 조회로 채워지는 필드(legal_name, registration_number, country_code)는 인증 후 읽기 전용이지만 재정의할 수 있습니다. 재정의한 내역은 감사 로그에 표시됩니다. 수정 가능한 필드: display_name, metadata, tags. 인증 후 읽기 전용: 레지스트리에서 가져온 모든 필드, 집계 카운터, features 맵.

curl -X PATCH https://verification.didit.me/v3/businesses/biz-acme/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "metadata": { "tier": "enterprise" } }'

business.data.updated 이벤트가 발생합니다.

상태 변경

PATCH /v3/businesses/{vendor_data}/update-status/ 기업의 상태를 ACTIVE, FLAGGED, BLOCKED 사이에서 변경합니다.

curl -X PATCH https://verification.didit.me/v3/businesses/biz-acme/update-status/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "BLOCKED",
    "reason": "Sanctioned subsidiary detected in ownership chain"
  }'

변경	일반적인 트리거
`ACTIVE` → `FLAGGED`	기업 확인(KYB) 세션이 `In Review` 상태로 바뀜, 지속적인 AML 모니터링 적중, 거래 규칙
`ACTIVE` → `BLOCKED`	제재 대상으로 확인된 기업, 수동 차단 목록 등록
`FLAGGED` → `ACTIVE`	분석가가 검토를 완료함
`BLOCKED` → `ACTIVE`	조치 후 수동으로 차단 해제

business.status.updated 이벤트가 발생합니다.

기업 일괄 삭제

POST /v3/businesses/delete/ 하나 이상의 기업을 삭제합니다. 기업 레코드는 영구적으로 삭제됩니다. 이 endpoint는 기업의 인증 세션을 다루지 않습니다. 해당 세션은 기업과의 연결만 해제된 상태로 남아 있습니다. 세션을 삭제하려면 세션 삭제를 사용하세요. 거래도 이 endpoint의 대상이 아니므로 Console에서 삭제해야 합니다.

curl -X POST https://verification.didit.me/v3/businesses/delete/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "vendor_data": ["biz-acme", "biz-alpha", "biz-beta"] }'

멱등성이 보장됩니다. 이미 삭제된 기업을 다시 삭제해도 아무 작업도 일어나지 않습니다.

권한 모델

/v3/businesses/* endpoint는 모두 businesses 권한 리소스에 따라 범위가 제한됩니다:

역할	list	get	create	update	update-status	delete
OWNER	✅	✅	✅	✅	✅	✅
ADMIN	✅	✅	✅	✅	✅	✅
COMPLIANCE_OFFICER	✅	✅	❌	✅	✅	❌
DEVELOPER	✅	✅	✅	❌	❌	❌
READER	✅	✅	❌	❌	❌	❌

역할 및 권한을 참고하세요.

이 작업에서 발생하는 webhook

작업	Webhook
`create`	`business.data.updated`
`update`	`changed_fields` 포함 `business.data.updated`
`update-status`	`business.status.updated`
`delete`	`deleted_at` 설정 포함 `business.data.updated`

다음 단계

데이터 모델

전체 필드 참조.

목록 API

GET /v3/businesses/ 스키마.

생성 API

POST /v3/businesses/create/ 스키마.

개요

요금

워크플로 및 인증

검토 및 운영

엔터티(사용자 및 기업)

설정 및 사용자 지정

보안 및 컴플라이언스

Didit Academy

리소스

기업 확인(KYB) CRUD 작업: 기업 엔티티 관리

기업 목록 조회

기업 조회

기업 생성

기업 수정

상태 변경

기업 일괄 삭제

권한 모델

이 작업에서 발생하는 webhook

다음 단계

데이터 모델

목록 API

생성 API

​기업 목록 조회

​기업 조회

​기업 생성

​기업 수정

​상태 변경

​기업 일괄 삭제

​권한 모델

​이 작업에서 발생하는 webhook

​다음 단계

데이터 모델

목록 API

생성 API

기업 목록 조회

기업 조회

기업 생성

기업 수정

상태 변경

기업 일괄 삭제

권한 모델

이 작업에서 발생하는 webhook

다음 단계