문서 내 텍스트로 필드 자동 배치하기

개요

POST /documents API로 서명을 요청할 때, 참여자 필드(서명란, 텍스트 입력란 등)의 위치를 지정하는 방법은 두 가지입니다.

기존 좌표 기반 방식(position)에서는 페이지 내 정확한 위치를 직접 계산해야 합니다. 참여 인원이나 항목 수에 따라 페이지 구조가 달라지는 비정형 문서에서는 매번 좌표를 다시 계산해야 하므로, 최종 문서를 확인할 수 없는 상태에서 서명 위치를 "감으로 잡아야" 하는 문제가 있었습니다.

Anchor 기반 배치(position.anchor)를 사용하면 문서 내 텍스트(예: "서명란", "근로자 이름")를 기준점으로 지정하여 필드가 해당 위치에 자동으로 배치됩니다. 문서 레이아웃이 변경되더라도 기준 텍스트의 위치만 유지되면 필드가 올바르게 배치됩니다.

📘

기존 연동에 영향 없음

Anchor 기능은 기존 position + size 기반 필드 배치를 대체하지 않습니다. 기존 연동 코드는 변경 없이 그대로 동작합니다.

적용 API

Anchor 기반 배치는 서명 요청 API의 participants[].fields 배열 내 각 필드 객체에서 사용할 수 있습니다.

동작 방식

Anchor 기반 배치는 다음과 같은 순서로 동작합니다.

1. 문서 업로드 — 서명 요청 시 PDF, DOCX, HWP 등 텍스트 정보가 포함된 문서 파일을 업로드합니다.
2. 텍스트 검색 — 서버에서 업로드된 문서를 파싱하여 anchor.text에 지정된 텍스트의 위치를 검색합니다. 동일한 텍스트가 여러 번 등장하면 매칭된 개수만큼 필드가 자동 생성됩니다.
3. 필드 배치 — 검색된 텍스트 위치를 기준으로, anchor.offset만큼 이동한 좌표에 anchor.size 크기의 필드를 자동 생성합니다.

📘

페이지 자동 감지

좌표 기반 방식에서는 position.page로 페이지를 직접 지정해야 하지만, Anchor 기반 방식에서는 기준 텍스트가 위치한 페이지를 자동으로 감지합니다. 문서의 내용이 늘어나 텍스트가 다음 페이지로 밀리더라도 필드가 따라갑니다.

사용 방법

필드 생성 시 기존 position의 x, y, page 대신 position.anchor 속성을 사용하여 텍스트 기반 위치를 지정합니다.

    {
      "type": "TEXT",
      "position": {
        "anchor": {
          "text": "근로자 이름",
          "offset": {
            "x": 0.01,
            "y": 0.005
          }
        }
      },
      "size": {
        "width": 0.2,
        "height": 0.05
      }
    }

지원 필드 타입

현재 Anchor 기반 배치를 지원하는 필드 타입은 다음과 같습니다.

📘

CHECKBOX, SIGNING_DATE, IMAGE 등 기타 필드 타입은 기존 좌표 기반(position) 방식으로 배치합니다.

Anchor 파라미터

position.anchor 객체의 구조는 다음과 같습니다.

📘

크기 지정

필드 크기(size)는 기존 좌표 기반 방식과 동일하게 position과 같은 레벨의 size 객체로 지정합니다. Anchor 사용 시에도 size.width, size.height는 필수입니다.

전체 요청 예시

아래는 하나의 서명 요청에서 Anchor 기반 필드와 기존 좌표 기반 필드를 함께 사용하는 예시입니다.

{
  "title": "근로계약서",
  "file": {
    "base64": "JVBERi0xLjQK...",
    "extension": "pdf"
  },
  "participants": [
    {
      "name": "김모두",
      "signingOrder": 1,
      "signingMethod": {
        "type": "EMAIL",
        "value": "[email protected]"
      },
      "fields": [
        {
          "type": "SIGNATURE",
          "required": true,
          "signatureTypes": ["SIGN"],
          "position": {
            "anchor": {
              "text": "근로자 서명",
              "offset": {
                "x": 0.01,
                "y": 0.005
              }
            }
          },
          "size": {
            "width": 0.15,
            "height": 0.05
          }
        },
        {
          "type": "TEXT",
          "required": true,
          "position": {
            "anchor": {
              "text": "근로자 이름",
              "offset": {
                "x": 0.08,
                "y": 0.0
              }
            }
          },
          "size": {
            "width": 0.2,
            "height": 0.04
          },
          "textStyle": {
            "size": 12,
            "font": "NOTO_SANS",
            "align": "LEFT"
          }
        },
        {
          "type": "CHECKBOX",
          "position": {
            "x": 0.05,
            "y": 0.8,
            "page": 1
          },
          "size": {
            "width": 0.03
          }
        }
      ]
    }
  ]
}

📘

한 문서 내 혼용 가능

위 예시처럼 서로 다른 필드에 대해 Anchor 기반과 좌표 기반을 혼용할 수 있습니다. Anchor를 지원하지 않는 필드 타입(CHECKBOX 등)은 기존 좌표 기반 방식을 사용하면 됩니다.

활용 시나리오

주의사항

⚠️

좌표와 Anchor는 상호 배타적입니다

하나의 필드에서 position에 좌표(x, y, page)와 anchor를 동시에 지정하거나, 둘 다 지정하지 않으면 400 오류가 발생합니다.

응답 예시:

JSON

{
  "statusCode": 400,
  "message": "Position must have either (x, y, page) or anchor, not both or neither"
}

JSON

// ❌ 잘못된 예시 — 좌표와 anchor 동시 지정
"position": {
  "x": 0.5,
  "y": 0.4,
  "page": 1,
  "anchor": {
    "text": "(인)"
  }
}

FAQ

  {
    "statusCode": 400,
    "message": "Position must have either (x, y, page) or anchor, not both or neither"
  }

  {
    "statusCode": 404,
    "error": "AnchorTextNotFoundException",
    "message": "Anchor text not found in PDF"
  }