본문으로 건너뛰기
가이드

전자서명에 앱 데이터 제공하기

인가된 노트 데이터 소스를 만들고 문서 준비와 서명 요청 흐름을 연결합니다.

전자서명에 앱 데이터 제공하기

Resource 만들기의 법인 소유 Workshop Note를 준비합니다. 이 가이드는 Note 자신을 문서 대상으로 삼아 이름 한 필드를 제공하는 소스를 구현합니다. 등록만으로 서명 권한이 생기거나 초대가 발송되지는 않습니다.

소스 생성과 구현

앱 폴더에서 실행합니다:

코드 예시
Shell
nexia make signature-data-source NoteFieldsV1 . \
  --source-key workshop.note_fields_v1 \
  --subject-resource-key workshop.note \
  --source-resource-key workshop.note \
  --lookup-mode direct_subject --cardinality one --min-items 1 --max-items 1 \
  --field-key name --field-type string --field-classification internal --field-formatter plain

생성기는 src/Descriptors/에 선언을, src/Signature/에 provider를 만듭니다. 출력된 파일명을 확인하세요. 초기 provider는 의도적으로 unavailable을 반환하므로 생성만으로 인가 구현이 끝난 것은 아닙니다. 생성된 provider의 resolve()만 교체하고 아래 import를 추가합니다:

코드 예시
PHP
use Illuminate\Support\Facades\Gate;
use Nexia\Apps\Acme\Workshop\Models\Note;
use Nexia\ResourceReference\ResourceRef;
use Nexia\Signature\SignatureDocumentDataResolvedItem;
use Nexia\Support\CanonicalPayloadFingerprint;

// Replace resolve() in the generated provider. Keep its existing SDK imports,
// appKey(), sourceKey(), sourceVersion(), matchesContract() and unavailable().
public function resolve(SignatureDocumentDataQuery $query): SignatureDocumentDataResult
{
    $subject = $query->subjectResourceRef;
    $same = static fn (ResourceRef $ref): bool => $ref->appKey === 'workshop'
        && $ref->resourceKey === 'workshop.note'
        && $ref->resourceId === $subject->resourceId;
    if (! $this->matchesContract($query) || ! $same($subject)
        || $query->requestedFieldKeys !== ['name']
        || ($query->explicitSourceRef !== null && ! $same($query->explicitSourceRef))
        || count($query->selectedResourceRefs) > 1) {
        return self::unavailable(SignatureDocumentDataDiagnosticCode::Forbidden);
    }
    foreach ($query->selectedResourceRefs as $selected) {
        if (! $same($selected)) {
            return self::unavailable(SignatureDocumentDataDiagnosticCode::Forbidden);
        }
    }
    $note = Note::query()->where('public_id', $subject->resourceId)
        ->where('legal_entity_id', $query->legalEntity->key())->first();
    if ($note === null || ! Gate::forUser($query->actor)->allows('view', $note)) {
        return self::unavailable(SignatureDocumentDataDiagnosticCode::Forbidden);
    }
    // This source has current state only. Do not invent an older revision.
    if ($note->updated_at === null || $note->updated_at->greaterThan($query->asOf)) {
        return new SignatureDocumentDataResult(SignatureDocumentDataStatus::Stale);
    }
    $values = ['name' => (string) $note->name];
    return new SignatureDocumentDataResult(
        SignatureDocumentDataStatus::Resolved,
        resolvedItems: [new SignatureDocumentDataResolvedItem(
            resourceRef: new ResourceRef('workshop', 'workshop.note', (string) $note->public_id, $note->name),
            sourceRevision: $note->updated_at->format('Y-m-d\TH:i:s.uP'),
            contentHash: CanonicalPayloadFingerprint::sha256($values),
            effectiveAt: $query->asOf,
            values: $values,
        )],
    );
}

생성된 단건 cardinality·소스 식별자·버전·대상·필드 계약은 유지하세요. 이 예제는 이미 조회할 수 있는 Note 이름만 반환하며 별도 필드 권한이 없다는 전제입니다. 필드별 권한이 있으면 반환 전에 추가 검사합니다. 테넌트 연결은 런타임이 제공하므로 요청 데이터로 테넌트를 선택하지 않습니다. 인덱스 기반 정확한 대상 조회와 런타임의 쿼리·요청 시간 제한을 유지하고 무제한 연관 조회를 추가하지 마세요.

현재 레코드가 기준 시점 이후 수정됐으면 과거 값을 만들어내지 않고 거절합니다. 과거 결과가 필요하면 실제 revision 저장을 구현해야 하며 effectiveAt만 바꾸면 안 됩니다. 보호된 값은 로그에 남기지 않습니다. 생성된 라벨 키를 두 언어에 추가하고 프로젝트 nexia dev로 동기화하세요.

문서·요청 연결

관리자는 대상과 호환되는 binding·필수 변수·서명 역할을 갖춘 전자서명 양식을 게시해야 합니다. 앱 소유 binding은 발견되는 descriptor contribution에서 SignatureTemplateBindingDescriptor로 선언합니다. 정확한 생성자·완전한 선언·문서 DTO·요청 예제는 전자서명 계약에 있습니다.

단계앱의 책임
양식·소스 선택사용 가능한 양식 결과를 사용하고 앱 데이터 추가에서 workshop.note_fields_v1@1의 name 연결
문서 준비정확한 대상 인가 후 고정된 변수·역할·저장한 멱등 키로 SignatureDocumentHost::createCurrentBound() 호출
렌더링 대기공개 ID·revision 저장, signature.document.outcome.v1 소비, 허용된 ready metadata 재조회
서명 요청준비된 문서의 정확한 ID·revision·checksum과 참여자·동의·만료 정책으로 SignatureHost::submit() 호출
결과 반영접수된 요청·대상을 대조한 뒤 최종 업무 효과 한 번만 반영

소스 등록이 양식 생성·수신자 선택·PDF 렌더링·서명 완료를 대신하지 않습니다. 준비된 참여자의 사용자 확인이 필요하면 SignatureRequestPreparationHost를 사용하세요. 초대 주소·PDF 원본·비밀번호 검증값을 일반 앱 로그나 queue payload에 넣지 않습니다.

준비·실패 경로 확인

  1. Note 조회와 해당 전자서명 권한을 부여하고 App 준비 완료를 기다립니다.
  2. 호환 양식의 앱 데이터 추가에서 Note 소스의 이름을 연결합니다. 허용된 Note로 문서를 준비하고 렌더링 결과를 확인하세요.
  3. 다른 법인·권한 없는 사용자·없는 Note·다른 선택 참조·수정 이전 시점을 확인합니다. 보호된 값이나 만들어낸 과거 값이 노출되면 안 됩니다.
  4. 요청은 문서가 실제 ready가 된 뒤 제출하고 최종 결과까지 확인합니다. accepted·queued는 서명 완료가 아닙니다.
  5. 저장한 같은 식별자로 재시도하고, 원본 권한 회수·문서 checksum·revision 변경도 확인합니다. 결과 불명일 때 새 요청을 자동 생성하지 않습니다.

소스 테스트 통과만으로 서버의 렌더러·초대 전송 설정을 검증한 것은 아닙니다. 플랫폼 준비가 실패하면 보호된 값을 제외한 오류와 작업 ID로 지원 요청하세요.

CLI 명령과 옵션은 공개 CLI 문서에서도 확인할 수 있습니다.

대량 서명과 업무 대상 예약

PHP SDK 0.10.3 이상과 대응 Core·App 런타임에서는 SignatureBulkBindingProvider의 대량 요청에 선택적 SignatureBulkBindingLifecycleProvider를 구현할 수 있습니다. 앱의 업무 대상 예약과 접수된 서명 요청을 연결하는 계약입니다. 단순 필드 공급자는 이 계약을 구현할 필요가 없습니다.

코드 예시
PHP
use Nexia\Signature\SignatureBulkBindingLifecycleContext;
use Nexia\Signature\SignatureBulkBindingReauthorizationResult;

// SignatureBulkBindingLifecycleProvider가 요구하는 메서드
public function reconcile(SignatureBulkBindingLifecycleContext $context): SignatureBulkBindingReauthorizationResult;
phase처리할 일
reserve현재 업무 대상·권한을 다시 확인하고, 대상별 동시 예약을 직렬화해 작업 ID로 예약
accepted접수된 requestPublicId, 문서와 참여자 정보를 예약에 연결. 새 초대를 발송하지 않음
release확정적으로 중단된 작업의 예약 해제. 해제 이력은 보존

operationId를 멱등 키로 사용하고 같은 단계의 재전달이 업무 효과를 중복 생성하지 않게 구현합니다. execution에는 실행 대상과 인가 문맥이 들어 있고, actor와 legalEntity도 해당 문맥에서 제공됩니다. authorized(), denied(reason), unavailable(reason) 결과를 실제 상태에 맞게 반환합니다. 접수 반영보다 종료 결과가 먼저 도착할 수 있으므로 저장한 요청·작업 식별자로 나중에 대조하세요. 불명확한 결과를 성공이나 새 요청으로 바꾸지 않습니다.

확인

동일 작업 재전달, 두 작업의 동일 대상 예약 경쟁, 접수 결과 반영 재시도, 예약 해제 후 재전달, 권한 회수와 종료 결과 선도착을 확인합니다. 기존 요청으로 복구하며 초대 중복 발송이 없어야 합니다. 사용자 절차는 전자서명 요청 가이드를 참고하세요.

원본 위치: docs/developers/content/ko/platform-extensions/electronic-signature.md