PATCH/v1/cards/{card_id}

카드 수정

update_card

인증

Authorization 헤더로 API 키를 보내세요: Authorization: Bearer <키>.

경로 파라미터

card_idstring필수

헤더 파라미터

Idempotency-Keystring
쓰기 요청을 안전하게 재시도하기 위한 키예요. 출력 가능한 ASCII 문자 1~255자이며, 논리적 처리 단위마다 UUID v4를 하나씩 쓰기를 권장해요. 24시간 안에 같은 키로 재시도하면 처리를 다시 실행하지 않고, 저장된 응답(상태, 헤더, 본문)을 Idempotency-Replayed: true 헤더와 함께 반환해요. 같은 키를 다른 메서드, 경로, Content-Type 값이나 본문과 함께 보내면 409 api.idempotency_mismatch 오류를 반환하고, 첫 요청이 아직 실행 중이면 409 api.idempotency_in_progress 오류를 Retry-After: 1 헤더와 함께 반환해요. 5xx나 429 응답 뒤에는 키가 해제되어, 재시도하면 처리가 다시 실행돼요. 키의 적용 범위는 조직과 호출자(API 키, 사용자, 사용자 지정 소스 키)예요.
length ≥ 1, length ≤ 255
X-View-Asstring
admin 역할의 API 키만 쓸 수 있어요. <profile>[:viewer|verifier|editor] 형식의 데이터 프로필로 요청을 보내요(예: employee:viewer). 설치 키는 이 헤더를 쓸 수 없어요(403).

쿠키 파라미터

kb_view_asstring
세션의 “View as” 모드(다른 사용자로 보기) 쿠키. POST /auth/view-as 요청으로 설정하고 DELETE /auth/view-as 요청으로 지워요.

요청 본문

application/json

객체: CardUpdate

external_idstring | null
카드의 external_id 값을 설정하거나 변경해요. "" 또는 null이면 제거돼요. 조직의 다른 카드가 이 값을 쓰고 있으면 요청은 409 cards.external_id_taken 오류를 반환해요. 소스 카드의 external_id 값은 바뀌지 않아요(409 cards.managed_by_source).
length ≤ 512
metadataMetadataPatch
titlestring | null
owner_idinteger | null
verifier_idsarray of integer | null
verify_interval_daysinteger | null
≥ 1, ≤ 3650
tagsarray of string | null
statusstring | null
source_urlstring | null
categorystring | null
sensitiveboolean | null
table_categoriesmap of object | null

응답

200성공 응답

응답 헤더

RateLimit-Policy
적용 중인 한도. IETF 초안 draft-ietf-httpapi-ratelimit-headers 형식이며, 쉼표로 구분한 "<name>";q=<quota>;w=<window in seconds> 항목으로 이루어져요. key 항목은 API 키의 요청 속도예요(할당량은 버스트, 시간 창은 버스트가 완전히 다시 채워지는 시간이에요. 세션에서는 user, 자격 증명이 없으면 ip예요). minute, day, month 항목은 UTC 기준 달력상의 분, 일, 월에 대한 조직의 할당량이에요.
RateLimit
RateLimit-Policy 헤더의 각 한도에서 남은 양: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
RateLimit-Policy 헤더에서 가장 엄격한 항목(남은 요청 수가 가장 적은 항목)의 한도.
X-RateLimit-Remaining
가장 엄격한 한도에서 남은 요청 수.
X-RateLimit-Reset
가장 엄격한 한도가 초기화될 때까지 남은 초.
Idempotency-Replayed
true이면 이 Idempotency-Key 값으로 저장된 응답을 재생한 것이에요. 처리는 다시 실행되지 않았어요.

application/json

객체: Card

expandedCardExpanded
permissionsObjectPermissionList
accessstring
허용 값: wholepartial
access_contactstring
접근 권한을 문의할 사람(access=partial일 때만).
aclobject
필드
- verifyboolean필수
- writeboolean필수
categorystring필수
category_confidencenumber | null필수
category_lockedboolean필수
category_reviewboolean필수
category_sourceCategorySource | null필수
collectionstring필수
collection_idinteger필수
collection_titlestring
commentsarray of CardComment
content_jsonContentJSON | null
최근 게시된 버전의 편집기 콘텐츠. 이 필드는 없을 수 있으며, 그럴 때는 초안에서 편집기 콘텐츠를 가져오세요(card_id 값을 넣은 POST /v1/drafts).
editing_lockEditingLock | null
활성 편집 잠금. 이 필드는 없을 수 있으며, 그럴 때 편집기는 POST /v1/cards/{card_id}/lock 요청의 409 cards.locked 오류로 잠금을 가진 사람을 알 수 있어요.
created_atstring (date-time)필수
days_since_verifiedinteger필수
errorstring | null필수
eventsarray of CardEvent
feedback_neginteger필수
feedback_posinteger필수
foldersarray of CardFolderRef
카드 목록에만 있어요: 카드가 들어 있는 폴더(사용자가 볼 수 있는 폴더)와 컬렉션 최상위부터의 경로. 빈 목록이면 카드가 어떤 폴더에도 없다는 뜻이에요.
has_tablesboolean
카드 목록에만 있어요.
hidden_partsboolean
idstring필수
jobJob | null
kindCardKind필수
org_idinteger필수
owner_activeboolean | null
owner_idinteger | null필수
owner_namestring | null필수
pagesinteger | null필수
parserstring | null필수
중립 코드로 나타낸 문서 파서: document(전체 구조: 페이지, 제목, 표, 스캔한 페이지), pdf(PDF 텍스트 레이어), docx, xlsx, csv, markdown, html, text. 목록은 늘어날 수 있어요.
partsarray of CardPart필수
sensitiveboolean필수
sha256string | null필수
sizeinteger필수
snoozed_atstring (date-time) | null
snoozed_byinteger | null
snoozed_untilstring | null
source_changedboolean필수
source_pathstring | null필수
source_urlstring | null필수
statusstring필수
허용 값: processingreadyerrorarchived
tablesarray of CardTable
tagsarray of string필수
titlestring필수
trustnumber필수
trust_if_verifiednumber
trust_partsTrustParts필수
updated_atstring (date-time)필수
verificationVerification필수
verified_atstring (date-time) | null필수
verified_byinteger | null필수
verified_by_namestring | null
verifier_idsarray of integer필수
verifiersarray of object
필드
- activeboolean필수
- idinteger필수
- namestring필수
verify_interval_daysinteger필수
versioninteger필수
versionsarray of CardVersion
source_archiveArchiveSource
created_byinteger | null
manual_optionsobject
수동 파싱 설정(미리 보기).
doc_kindDocKind | null
문서 유형. 유형이 정해지지 않았으면 null이에요(예: 문서 유형이 도입되기 전에 인덱싱된 카드).
doc_kind_confidencenumber | null
문서 유형의 확신도(0부터 1까지).
doc_kind_sourcestring | null
유형을 정한 주체: 규칙(rules), 사용자(manual) 또는 자동 분류. 목록은 늘어날 수 있으므로 알 수 없는 값은 자동 분류로 처리하세요.
허용 값: rulesmanualnull
invoiceDocInvoiceExtraction | null
청구서, 크레딧 노트 또는 영수증의 필드(이 유형에만, 그리고 목록이 아닌 카드에만 있어요). 필드는 문서 전체에서 추출하므로 문서 전체에 접근할 수 없으면 null이에요.
warningsarray of ReviewWarning
문서 파싱 경고(ReviewWarning. 목록이 아닌 카드에만 있어요).
enrichmentCardEnrichmentStatus | null
정보 보강 상태(목록이 아닌 카드에만 있어요). 문서 유형, 청구서 필드, 재무 기록은 인덱싱 후 백그라운드에서 추가되며 나중에 다시 계산될 수 있어요. 준비되면 카드에 나타나요. null이면 상태를 알 수 없어요(백그라운드 정보 보강 없이 인덱싱된 카드).
external_idstring | null
연동 개발자 시스템에서 쓰는 카드 ID. 소스에서 오지 않은 카드 사이에서 조직 내 고유해요. null이면 설정되지 않은 상태예요. /v1/cards-by-external-id/{external_id} 경로는 이 값으로 카드를 읽고 교체해요.
length ≤ 512
metadataMetadata

400잘못된 요청이에요. 파라미터 값이나 객체의 상태 때문에 이 동작을 할 수 없어요(`detail` 필드에 메시지가 있어요).

응답 헤더

RateLimit-Policy
적용 중인 한도. IETF 초안 draft-ietf-httpapi-ratelimit-headers 형식이며, 쉼표로 구분한 "<name>";q=<quota>;w=<window in seconds> 항목으로 이루어져요. key 항목은 API 키의 요청 속도예요(할당량은 버스트, 시간 창은 버스트가 완전히 다시 채워지는 시간이에요. 세션에서는 user, 자격 증명이 없으면 ip예요). minute, day, month 항목은 UTC 기준 달력상의 분, 일, 월에 대한 조직의 할당량이에요.
RateLimit
RateLimit-Policy 헤더의 각 한도에서 남은 양: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
RateLimit-Policy 헤더에서 가장 엄격한 항목(남은 요청 수가 가장 적은 항목)의 한도.
X-RateLimit-Remaining
가장 엄격한 한도에서 남은 요청 수.
X-RateLimit-Reset
가장 엄격한 한도가 초기화될 때까지 남은 초.

application/json

객체: Error

401자격 증명(세션 쿠키나 API 키)을 보내지 않았거나 키를 찾을 수 없어요.

응답 헤더

RateLimit-Policy
적용 중인 한도. IETF 초안 draft-ietf-httpapi-ratelimit-headers 형식이며, 쉼표로 구분한 "<name>";q=<quota>;w=<window in seconds> 항목으로 이루어져요. key 항목은 API 키의 요청 속도예요(할당량은 버스트, 시간 창은 버스트가 완전히 다시 채워지는 시간이에요. 세션에서는 user, 자격 증명이 없으면 ip예요). minute, day, month 항목은 UTC 기준 달력상의 분, 일, 월에 대한 조직의 할당량이에요.
RateLimit
RateLimit-Policy 헤더의 각 한도에서 남은 양: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
RateLimit-Policy 헤더에서 가장 엄격한 항목(남은 요청 수가 가장 적은 항목)의 한도.
X-RateLimit-Remaining
가장 엄격한 한도에서 남은 요청 수.
X-RateLimit-Reset
가장 엄격한 한도가 초기화될 때까지 남은 초.

application/json

객체: Error

403이 동작은 허용되지 않아요. 역할이 부족하거나, 컬렉션이나 카드에 접근할 수 없거나, 요청이 “View as” 모드로 실행 중이거나, 조직이 정지 또는 삭제된 경우예요(`detail` 필드는 `code: org_suspended | org_deleted` 값을 가진 객체예요).

응답 헤더

RateLimit-Policy
적용 중인 한도. IETF 초안 draft-ietf-httpapi-ratelimit-headers 형식이며, 쉼표로 구분한 "<name>";q=<quota>;w=<window in seconds> 항목으로 이루어져요. key 항목은 API 키의 요청 속도예요(할당량은 버스트, 시간 창은 버스트가 완전히 다시 채워지는 시간이에요. 세션에서는 user, 자격 증명이 없으면 ip예요). minute, day, month 항목은 UTC 기준 달력상의 분, 일, 월에 대한 조직의 할당량이에요.
RateLimit
RateLimit-Policy 헤더의 각 한도에서 남은 양: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
RateLimit-Policy 헤더에서 가장 엄격한 항목(남은 요청 수가 가장 적은 항목)의 한도.
X-RateLimit-Remaining
가장 엄격한 한도에서 남은 요청 수.
X-RateLimit-Reset
가장 엄격한 한도가 초기화될 때까지 남은 초.

application/json

객체: Error

404객체가 없거나 접근할 수 없어요. API는 접근이 제한된 객체가 존재하는지 확인해 주지 않아요.

응답 헤더

RateLimit-Policy
적용 중인 한도. IETF 초안 draft-ietf-httpapi-ratelimit-headers 형식이며, 쉼표로 구분한 "<name>";q=<quota>;w=<window in seconds> 항목으로 이루어져요. key 항목은 API 키의 요청 속도예요(할당량은 버스트, 시간 창은 버스트가 완전히 다시 채워지는 시간이에요. 세션에서는 user, 자격 증명이 없으면 ip예요). minute, day, month 항목은 UTC 기준 달력상의 분, 일, 월에 대한 조직의 할당량이에요.
RateLimit
RateLimit-Policy 헤더의 각 한도에서 남은 양: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
RateLimit-Policy 헤더에서 가장 엄격한 항목(남은 요청 수가 가장 적은 항목)의 한도.
X-RateLimit-Remaining
가장 엄격한 한도에서 남은 요청 수.
X-RateLimit-Reset
가장 엄격한 한도가 초기화될 때까지 남은 초.

application/json

객체: Error

422유효성 검사 오류예요. 본문이나 파라미터가 스키마와 맞지 않거나(`detail` 필드는 유효성 검사 오류 목록), 파라미터 값이 허용 범위를 벗어났어요(`detail` 필드는 메시지).

응답 헤더

RateLimit-Policy
적용 중인 한도. IETF 초안 draft-ietf-httpapi-ratelimit-headers 형식이며, 쉼표로 구분한 "<name>";q=<quota>;w=<window in seconds> 항목으로 이루어져요. key 항목은 API 키의 요청 속도예요(할당량은 버스트, 시간 창은 버스트가 완전히 다시 채워지는 시간이에요. 세션에서는 user, 자격 증명이 없으면 ip예요). minute, day, month 항목은 UTC 기준 달력상의 분, 일, 월에 대한 조직의 할당량이에요.
RateLimit
RateLimit-Policy 헤더의 각 한도에서 남은 양: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
RateLimit-Policy 헤더에서 가장 엄격한 항목(남은 요청 수가 가장 적은 항목)의 한도.
X-RateLimit-Remaining
가장 엄격한 한도에서 남은 요청 수.
X-RateLimit-Reset
가장 엄격한 한도가 초기화될 때까지 남은 초.

application/json

객체: Error

429요청이 너무 많거나(`api.rate_limited`), 조직의 분·일·월 할당량을 다 썼거나(`api.quota_exceeded`, `error.details` 필드에 `quota`, `limit`, `reset_at` 값이 있어요), 조직의 한도에 도달했거나, 답변 서비스가 바쁜 상태예요(`answers.engine_busy`). `Retry-After` 헤더에 적힌 시간만큼 기다리세요.

응답 헤더

Retry-After
요청을 다시 시도하기 전에 기다릴 초.
RateLimit-Policy
적용 중인 한도. IETF 초안 draft-ietf-httpapi-ratelimit-headers 형식이며, 쉼표로 구분한 "<name>";q=<quota>;w=<window in seconds> 항목으로 이루어져요. key 항목은 API 키의 요청 속도예요(할당량은 버스트, 시간 창은 버스트가 완전히 다시 채워지는 시간이에요. 세션에서는 user, 자격 증명이 없으면 ip예요). minute, day, month 항목은 UTC 기준 달력상의 분, 일, 월에 대한 조직의 할당량이에요.
RateLimit
RateLimit-Policy 헤더의 각 한도에서 남은 양: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
RateLimit-Policy 헤더에서 가장 엄격한 항목(남은 요청 수가 가장 적은 항목)의 한도.
X-RateLimit-Remaining
가장 엄격한 한도에서 남은 요청 수.
X-RateLimit-Reset
가장 엄격한 한도가 초기화될 때까지 남은 초.

application/json

객체: Error

오류 코드

모든 요청에 공통으로 쓰이는 코드 외에 이 엔드포인트가 error.code로 반환할 수 있는 코드예요.

안전한 재시도

POST와 PATCH 요청마다 Idempotency-Key 헤더(예: UUID)를 보내세요. 24시간 안에 같은 키로 재시도하면 요청을 다시 실행하지 않고 저장된 응답을 반환해요.

호출 한도

응답에는 RateLimit, RateLimit-Policy 헤더와 이전 헤더인 X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset이 담겨요. 429 응답에는 초 단위의 Retry-After 헤더가 있어요. 그만큼 기다린 뒤 재시도하세요.

← cards · API 레퍼런스

curl -X PATCH 'https://api.sursa.com/v1/cards/CARD_ID' \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"external_id":"crm-1042","metadata":{"key":"string"},"title":"Refund policy"}' \
  -H "Authorization: Bearer $SURSA_API_KEY"

사용해 보기

API 키

키는 이 탭의 메모리에만 보관되며 https://api.sursa.com 주소로만 전송돼요.

요청은 조직의 실제 데이터에 적용돼요.

Idempotency-Key header

X-View-As header

card_id path *

Idempotency-Key

비워 두면 요청마다 새 키가 생성돼요.

요청 본문(JSON)