DocsReferencesChangelog
Docs

metadata로 분류하기

metadata 분류하기

문서를 사용자가 원하는 기준으로 분류하기 위해 metadata 를 활용할 수 있습니다.
아래의 API들에서 metadatas 값을 전달해 이후 생성된 문서 또는 템플릿에 메타데이터를 설정할 수 있습니다.

템플릿으로 서명요청 API에서 메타데이터 설정하기

curl --request POST \
     --url https://api.modusign.co.kr/documents/request-with-template \
     --header 'Accept: application/json' \
     --header 'Authorization: Basic VVNFUjo=' \
     --header 'Content-Type: application/json' \
     --data '
{
  "templateId": "TEMPLATE_ID",
  "document": {
    "title": "2020_근로계약서_홍길동"
    "participantMappings": [
      {
        "name": "김모두",
        "signingMethod": {
          "type": "EMAIL",
          "value": "[email protected]"
        }
      }
    ],
    "metadatas": [
      {
        "key": "고객사_ID",
        "value": "a-024"
      },
      {
        "key": "담당자_사번",
        "value": "21013"
      }
    ]
  }
}
'

🚧

메타데이터 설정은 최대 10개로 제한됩니다.

서명요청 시 한 문서에 메타데이터를 최대 10개까지 등록할 수 있습니다.

metadata 수정하기

"문서 메타데이터 변경 API" 를 통해 문서에 metadatas 를 수정할 수 있습니다.

curl --request PUT \
     --url https://api.modusign.co.kr/documents/DOCUMENT_ID/metadatas \
     --header 'Accept: application/json' \
     --header 'Authorization: Basic YWFhOmFhYQ==' \
     --header 'Content-Type: application/json' \
     --data '
{
     "metadatas": [
          {
               "key": "고객사_ID",
               "value": "a-024"
          },
          {
               "key": "담당자_사번",
               "value": "21013"
          }
     ]
}
'

요청 시 metadatas 에 key와 value로 이루어진 객체들을 배열로 요청해 문서에 메타데이터를 적용할 수 있습니다.
또한 같은 API를 사용해 메타데이터를 수정할 수도 있습니다.

❗️

"메타데이터 수정 API" 는 배열 전체를 수정합니다.

여러 개의 메타데이터를 한 문서에 설정했을 때, 특정 값을 수정하고자 한다면 기존의 메타데이터 목록 전체에서 특정 값을 수정한 메타데이터 목록 전체를 body에 담아 요청해야합니다. 일부 메타데이터만 body에 담아 요청할 시, 목록에 포함되지 않은 메타데이터는 사라집니다.

 

 

목록 필터링에 사용하기

이렇게 지정한 metadata는 "문서 리스트 조회 API" 의 metadatas 쿼리 파라미터를 통해 목록 필터에 사용합니다.

설정하고자 하는 메타데이터의 key/value를 각각 JSON name/value로 하는 JSON 스트링을 url 인코딩하여 적용합니다.

이름필수 여부설명예시
metadatas선택문서에 설정된 메타데이터로 목록에 포함할 문서를 필터합니다.{ "고객사_ID": "a-024", "담당자_사번": "21013" }

아래의 예시에서는 특정 고객사_ID와 담당자_사번을 가진 문서 목록을 조회합니다.

const fetch = require('node-fetch');

const metadatasFilter = { 
  "고객사_ID": "a-024",
  "담당자_사번": "21013"
};
const encodedMetadatasFilter = encodeURIComponent(JSON.stringify(metadatasFilter));
// ㄴ 해당 값은 우측과 같이 인코딩됩니다. '%7B%22%EA%B3%A0%EA%B0%9D%EC%82%AC_ID%22%3A%22a-024%22%2C%22%EB%8B%B4%EB%8B%B9%EC%9E%90_%EC%82%AC%EB%B2%88%22%3A%2221013%22%7D'

const url = `https://api.modusign.co.kr/documents?offset=0&limit=10&metadatas=${encodedMetadatasFilter}`;
const options = {method: 'GET', headers: {Accept: 'application/json'}};

fetch(url, options)
  .then(res => res.json());

Updated 9 months ago