서명 요청 API(POST /documents)에서 입력란(필드)의 위치를 좌표 대신 문서 안의 텍스트를 기준으로 지정하는 방법입니다. 문서의 내용이 길어지거나 표의 행이 늘어나 레이아웃이 바뀌어도, 기준 텍스트만 그대로 있으면 필드가 알아서 따라갑니다.

한눈에 보는 차이

Anchor는 기존 좌표 방식을 대체하지 않습니다. 기존 연동 코드는 그대로 동작하며, 한 문서 안에서 필드별로 두 방식을 섞어 쓸 수 있습니다.

전체 흐름

문서를 업로드하고 anchor를 지정해 서명 요청을 보내면, 모두싸인 서버가 문서를 파싱해 기준 텍스트의 위치를 찾고 그 자리에 필드를 생성합니다. 파란색은 서버·API 처리 단계, 민트색은 참여자 화면 단계입니다.

1. POST /files — 서명받을 문서 파일을 업로드하고 fileId·token을 받습니다.
2. POST /documents — 참여자의 각 필드에 position.anchor.text로 기준 텍스트를 지정해 서명을 요청합니다.
3. 모두싸인 서버가 업로드된 문서를 파싱해 anchor.text의 위치를 검색합니다.
4. 검색된 위치에서 anchor.offset만큼 이동한 좌표에 size 크기의 필드가 자동 생성됩니다.
5. 참여자가 서명 화면에서 자동 배치된 입력란을 채우고 서명합니다.

1. 문서 파일 업로드

먼저 서명받을 문서를 파일 업로드 API로 올립니다.

curl -X POST 'https://api.modusign.co.kr/files?type=document' \
  -H 'Authorization: Basic {인코딩된 API-KEY}' \
  -F 'file=@근로계약서.pdf'

응답으로 받은 fileId와 token을 다음 단계의 서명 요청에서 사용합니다.

2. Anchor로 필드 위치 지정

필드의 position 객체에 좌표 대신 anchor 객체를 넣습니다.

{
  "type": "TEXT",
  "required": true,
  "position": {
    "anchor": {
      "text": "근로자 이름",
      "offset": {
        "x": 0.08,
        "y": 0
      }
    }
  },
  "size": {
    "width": 0.2,
    "height": 0.04
  }
}

Anchor 파라미터

offset 객체를 넣는 경우 x와 y는 둘 다 지정해야 합니다. 한쪽만 이동시키려면 나머지를 0으로 두세요.

좌표 단위는 문서 크기 대비 비율입니다

offset과 size 값은 픽셀이 아니라 문서 너비·높이에 대한 0~1 비율입니다. 예를 들어 offset.x: 0.08은 문서 너비의 8%만큼 오른쪽으로, size.width: 0.2는 문서 너비의 20% 크기를 뜻합니다.

크기(size)는 Anchor를 써도 필수입니다

size는 position과 같은 레벨에 두며, Anchor 방식에서도 생략할 수 없습니다.

3. Anchor를 쓸 수 있는 범위

Anchor는 모든 서명 요청 상황에서 쓸 수 있는 기능이 아닙니다. 연동을 설계하기 전에 아래 세 가지를 먼저 확인하세요.

사용할 수 있는 API

사용할 수 있는 필드 타입

위치 지정 방식만 달라질 뿐, TEXT의 textStyle·format이나 SIGNATURE의 signatureTypes·enableOneClick 같은 기존 옵션은 Anchor 방식에서도 그대로 사용할 수 있습니다. 참고로 SIGNATURE 필드의 signatureTypes는 위치 지정 방식과 무관하게 필수 값입니다.

사용할 수 있는 파일

Anchor는 문서에서 텍스트를 읽어 위치를 찾기 때문에, 텍스트 정보가 들어 있는 문서 파일에서만 동작합니다.

bmp, gif, jpg, jpeg, png, tiff 등 이미지 파일은 텍스트 정보가 없어 Anchor를 지원하지 않습니다. 이미지 파일에는 좌표 기반 방식을 사용하세요.

4. 매칭 규칙 — 필드가 여러 개 생길 수 있습니다

Anchor는 "가장 먼저 찾은 한 곳"에 배치하는 것이 아닙니다. anchor.text와 일치하는 텍스트가 문서에 여러 번 등장하면, 매칭된 개수만큼 동일한 설정의 필드가 자동으로 생성됩니다.

예를 들어 "text": "(인)"으로 지정했는데 문서에 (인)이 3번 등장하면, 같은 설정의 필드가 3개 만들어집니다. 이는 "모든 서명란에 한 번에 배치"할 때는 편리하지만, 의도치 않은 곳까지 필드가 생기는 원인이 되기도 합니다.

dataLabel 자동 넘버링

매칭이 여러 건일 때 해당 필드에 dataLabel이 지정되어 있으면 자동으로 번호가 붙습니다.

이때 자동 생성된 dataLabel이 다른 필드의 dataLabel과 겹치면 오류가 발생합니다. dataLabel 값을 정할 때 (숫자) 넘버링 패턴과 충돌하지 않도록 주의하세요.

필드 개수 제한

Anchor로 자동 생성되는 필드도 아래 제한에 포함됩니다.

제한을 초과하면 서명 요청이 실패합니다. 매칭 수가 많아질 것 같다면 anchor.text를 더 구체적으로 지정해(예: (인) 대신 근로자 (인)) 매칭 수를 조절하세요.

5. 전체 요청 예시

한 서명 요청 안에서 Anchor 기반 필드와 좌표 기반 필드를 함께 사용하는 예시입니다.

curl -X POST 'https://api.modusign.co.kr/documents' \
  -H 'Authorization: Basic {인코딩된 API-KEY}' \
  -H 'Content-Type: application/json' \
  -d @request.json

{
  "title": "근로계약서",
  "file": {
    "fileId": "{업로드한 파일의 fileId}",
    "token": "{업로드한 파일의 token}"
  },
  "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
              }
            }
          },
          "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
          }
        }
      ]
    }
  ]
}

CHECKBOX처럼 Anchor를 지원하지 않는 필드 타입은 위 예시처럼 좌표 기반으로 지정하면 됩니다. 다만 하나의 필드 안에서 좌표와 Anchor를 동시에 쓸 수는 없습니다.

6. 활용 시나리오

7. API 호출 시 주의사항

• 좌표와 Anchor는 상호 배타적입니다. 하나의 필드에서 position에 좌표(x, y, page)와 anchor를 동시에 지정하거나, 둘 다 지정하지 않으면 400 오류가 발생합니다.
• 기준 텍스트가 문서에 실제로 있어야 합니다. 대소문자·공백·특수문자가 정확히 일치해야 하며, 찾지 못하면 서명 요청 자체가 생성되지 않습니다.
• 필드가 페이지 영역을 벗어나면 안 됩니다. offset이 너무 크거나 size가 커서 필드가 문서 경계를 넘으면 오류가 발생하고 서명 요청이 생성되지 않습니다.
• API KEY는 서버사이드 전용입니다. 브라우저 등 클라이언트에 노출하지 마세요.
• Rate Limit — Standard는 분당 300·초당 10, High-cost는 분당 150·초당 5입니다. 이 문서에서 사용하는 서명 요청(POST /documents)과 파일 업로드(POST /files)는 모두 High-cost API이므로 대량 발송 시 특히 주의하세요. 초과 시 429와 함께 X-Retry-After(초)가 반환되므로 그만큼 대기한 뒤 지수 백오프로 재시도하세요. 체험(Trial) 기간에는 한도가 더 낮으므로 API Rate Limit 정책 안내를 확인하세요.
• 파일 크기 — 문서 파일은 PDF 최대 10MB, 그 외 확장자 최대 5MB입니다. 문서 파일은 PDF를 권장합니다.

자주 발생하는 오류

8. 자주 묻는 질문

FAQ

{
  "type": "ValidationFailedException",
  "title": "Validation failed",
  "instance": "/documents",
  "data": {
    "constraints": [
      {
        "property": "participants[0].fields[0].position",
        "message": "Position must have either (x, y, page) or anchor, not both or neither"
      }
    ]
  },
  "detail": "Validation failed with 1 properties: participants[0].fields[0].position"
}

{
  "statusCode": 400,
  "error": "BadRequestException",
  "message": "Anchor text not found in PDF"
}