데이터 삭제 API

데이터 삭제 API는 Pushwoosh에서 대상의 개인 데이터를 삭제하는 셀프 서비스 방식입니다(GDPR 삭제권). 삭제는 되돌릴 수 없습니다. 직접 만든 시스템에서 Control Panel의 데이터 요청 페이지와 구독자 카드의 개인 데이터 삭제 작업을 그대로 재현하는 데 사용하세요.

기본 URL

https://rpc-api.svc-nue.pushwoosh.com

모든 엔드포인트는 HTTPS를 통해 제공됩니다. 요청과 응답은 application/json을 사용하며, Upload만 예외로 multipart/form-data를 사용합니다.

인증

모든 요청에는 서버 API 토큰이 포함된 Authorization 헤더가 있어야 합니다:

Authorization: Api YOUR_API_TOKEN

토큰은 application_codes에 지정된 모든 애플리케이션에 대한 수정 권한을 가지고 있어야 합니다. 이는 토큰이 해당 애플리케이션에서 기기 데이터를 기록하는 데 필요한 것과 동일한 권한입니다.

규칙

필드 명명 규칙: 요청 본문은 lowerCamelCase를 사용합니다(예: applicationCodes, identifierType). 응답은 proto 필드 이름을 사용하여 snake_case(task_id, identifier_hash 등)로 마샬링됩니다. 아래의 예시와 객체 참조는 이 표기법을 사용합니다.
식별자: 대상은 identifier_type(SUBJECT_IDENTIFIER_USER_ID, SUBJECT_IDENTIFIER_HWID, 또는 SUBJECT_IDENTIFIER_EMAIL)과 해당 한 가지 유형의 identifiers 목록으로 지정됩니다. 이메일 식별자는 대소문자를 구분하지 않고 일치합니다.
드라이 런을 먼저 실행한 뒤 인용하세요: dry_run: true로 Create를 호출하면 삭제될 항목의 수만 계산하고 아무것도 기록하지 않습니다. 실제 호출에서 해당 드라이 런의 task_id를 confirmation_dry_run_task_id로 인용하는 것은 선택 사항이지만, 인용할 경우 그 드라이 런의 애플리케이션 및 식별자와 정확히 일치해야 하며 드라이 런이 완료된 후 15분 이내에 호출해야 합니다. 그렇지 않으면 호출이 거부됩니다.
보고서는 식별자를 평문으로 담지 않습니다. GetTaskReport와 GetJournalReport 모두 각 식별자를 sha256 해시(identifier_hash)로 보고하며, 보고서 본문은 JSON 응답 안에 base64로 인코딩된 CSV입니다.

오류 응답

HTTP 상태	의미
`400 Bad Request`	잘못된 인수입니다. 예를 들어 빈 `identifier_type`, `identifiers`, `application_codes`, 10,000개를 초과하는 식별자, 50개를 초과하는 애플리케이션, 50,000개를 초과하는 식별자 × 애플리케이션 수, 빈 식별자 문자열, 또는 (Upload에서만) 누락되었거나 읽을 수 없는 CSV 파일인 경우입니다. 인용된 `confirmation_dry_run_task_id`가 지정한 완료된 드라이 런과 일치하지 않거나, 너무 오래되었거나(15분 초과), 완료된 드라이 런이 전혀 아닌 경우에도 통신 상에서 `FailedPrecondition`으로 반환됩니다.
`401 Unauthorized`	`Authorization` 헤더가 없거나 유효하지 않습니다.
`403 Forbidden`	토큰이 요청된 애플리케이션 중 하나에 대한 수정/기기 데이터 권한이 없거나, 호출자가 요청된 작업/보고서를 읽을 수 없는 경우입니다.
`404 Not Found`	작업을 찾을 수 없거나, 호출자의 계정에 속하지 않는 경우입니다.
`413 Payload Too Large`	(Upload에서만) 업로드된 파일이 5MB를 초과하는 경우입니다.
`429 Too Many Requests`	계정이 지난 24시간 동안 이미 20개의 데이터 삭제 작업(드라이 런 포함)을 시작한 경우입니다.

엔드포인트

메서드	경로	설명
`POST`	`/api/data_erasure/tasks`	삭제(또는 드라이 런) 작업을 생성합니다.
`POST`	`/api/data_erasure/upload`	업로드된 식별자 CSV로 삭제 작업을 생성합니다.
`GET`	`/api/data_erasure/tasks`	계정의 삭제 작업을 나열합니다.
`GET`	`/api/data_erasure/tasks/{task_id}`	삭제 작업 하나를 가져옵니다.
`GET`	`/api/data_erasure/tasks/{task_id}/rows`	작업 하나의 식별자별 결과를 나열합니다.
`GET`	`/api/data_erasure/tasks/{task_id}/report`	작업 하나의 보고서를 CSV로 다운로드합니다.
`GET`	`/api/data_erasure/report`	기간의 모든 작업을 하나의 CSV로 다운로드합니다.

Create

나열된 애플리케이션에서 나열된 대상의 개인 데이터 삭제를 시작합니다. dry_run: true를 사용하면 작업이 삭제될 항목의 수만 계산합니다.

POST /api/data_erasure/tasks

요청 본문

매개변수	유형	필수	설명
`identifierType`	string	예	`SUBJECT_IDENTIFIER_USER_ID`, `SUBJECT_IDENTIFIER_HWID`, 또는 `SUBJECT_IDENTIFIER_EMAIL`.
`identifiers`	array of strings	예	해당 한 가지 유형의 대상 식별자로, 작업당 최대 10,000개까지 가능하며 빈 값은 허용되지 않습니다.
`applicationCodes`	array of strings	예	삭제 대상이 되는 애플리케이션 코드로, 최대 50개까지 가능합니다. 한 번의 호출로 계정의 모든 애플리케이션에서 삭제할 방법은 없으므로 각각을 명시적으로 지정하세요. 보고서가 식별자당 애플리케이션당 한 행을 담기 때문에 `identifiers.length × applicationCodes.length`는 50,000을 초과할 수 없습니다.
`dryRun`	boolean	아니요	삭제될 항목의 수만 계산하고 아무것도 기록하지 않습니다. 기본값은 `false`입니다.
`confirmationDryRunTaskId`	integer	아니요	이 정확한 삭제를 측정한 완료된 드라이 런의 `task_id`입니다. 규칙을 참조하세요.

요청 예시

{
  "identifierType": "SUBJECT_IDENTIFIER_EMAIL",
  "identifiers": ["subject@example.com"],
  "applicationCodes": ["XXXXX-XXXXX"],
  "dryRun": true
}

응답

필드	유형	설명
`task_id`	integer	생성된 작업의 ID입니다. 이 페이지의 다른 모든 엔드포인트에서 사용하세요.

Upload

Create와 동일한 종류의 작업을 생성하지만, 식별자는 JSON 배열 대신 업로드된 CSV에서 가져옵니다. 대량 대상 목록에 이 방법을 사용하세요.

POST /api/data_erasure/upload

요청 (multipart/form-data)

필드	필수	설명
`file`	예	CSV 파일로, 최대 5MB까지 가능하며 단일 열에 행당 하나의 식별자를 담습니다. 첫 번째 행은 식별자를 담는 대신 열 이름을 지정할 수 있습니다(`user_id`, `userid`, `user id`, `hwid`, `email`, `identifier`, 또는 `subject`, 대소문자 구분 없음). 이 경우 해당 행은 헤더로 간주되어 건너뛰며 개수에 포함되지 않습니다. 빈 행은 건너뛰며 별도로 집계됩니다. 중복된 식별자(이메일의 경우 대소문자 구분 없음)는 하나로 합쳐지며 별도로 집계됩니다.
`identifier_type`	예	`user_id`, `hwid`, 또는 `email`이며 소문자로 작성합니다. 이 페이지의 다른 곳에서 사용되는 JSON `identifierType` 열거형 값과는 대소문자 표기가 다릅니다. 파일 전체에 하나의 유형이 적용됩니다.
`application_codes`	예	쉼표로 구분된 애플리케이션 코드입니다.
`dry_run`	아니요	`true`/`false`.
`confirmation_dry_run_task_id`	아니요	`Create`와 동일합니다.

응답

{
  "task_id": 123,
  "identifier_count": 480,
  "duplicate_count": 3,
  "skipped_rows": 1
}

ListTasks

계정의 삭제 작업을 최신순으로 나열합니다. 누가 무엇을 언제 삭제했는지에 대한 감사 저널입니다. includeDryRuns를 설정하지 않으면 드라이 런은 제외됩니다.

GET /api/data_erasure/tasks

쿼리 매개변수

매개변수	유형	설명
`limit` / `offset`	integer	페이징.
`includeDryRuns`	boolean	드라이 런(측정 전용) 작업을 포함합니다.
`from` / `to`	string (RFC 3339)	`[from, to)` 구간에서 시작된 작업만 유지합니다.
`applicationCode`	string	이 애플리케이션을 대상으로 하는 작업만 유지합니다.
`initiatorUserId`	integer	이 Control Panel 사용자가 시작한 작업만 유지합니다. `0`(기본값)은 모든 시작자를 유지합니다.
`initiatorTokenId`	integer	이 API 토큰이 시작한 작업만 유지합니다. `0`(기본값)은 모든 시작자를 유지합니다.
`initiatorEmail`	string	이메일로 대소문자 구분 없이 일치하는, 이 Control Panel 사용자가 시작한 작업만 유지합니다.

응답

필드	유형	설명
`tasks`	데이터 삭제 작업 객체 배열	일치하는 작업입니다.

GetTask

삭제 작업 하나를 상태 및 카운터와 함께 반환합니다. Create 또는 Upload로 시작한 작업을 추적하는 데 사용하세요.

GET /api/data_erasure/tasks/{task_id}

응답

필드	유형	설명
`task`	데이터 삭제 작업 객체	요청된 작업입니다.

ListTaskRows

작업 하나의 식별자별 결과를 반환합니다. 삭제됨, 찾을 수 없음, 건너뜀, 실패 여부를 나타냅니다. 식별자는 sha256 해시로 보고됩니다.

GET /api/data_erasure/tasks/{task_id}/rows

쿼리 매개변수

매개변수	유형	설명
`limit` / `offset`	integer	페이징.

응답

필드	유형	설명
`rows`	데이터 삭제 작업 행 객체 배열	현재 페이지의 결과입니다.

GetTaskReport

작업 하나의 전체 보고서를 CSV 파일로 반환합니다. 식별자당 애플리케이션당 한 행에 그 결과가 담깁니다. ListTaskRows는 대신 동일한 행을 페이지 단위로 보여줍니다.

GET /api/data_erasure/tasks/{task_id}/report

응답

필드	유형	설명
`filename`	string	제안된 파일 이름입니다(예: `data-erasure-task-42.csv`).
`content_type`	string	`text/csv`.
`content`	string (base64)	CSV 파일입니다. 열: `task_id`, `created`, `identifier_type`, `identifier_hash`, `application_code`, `result`, `detail`.

GetJournalReport

기간의 모든 삭제 작업을 하나의 CSV 파일로 반환합니다. 각 행에는 식별자당 애플리케이션당 정보와 함께 해당 작업 및 시작한 사용자가 담깁니다. 이는 계정이 감사자에게 제출하는 자료입니다.

GET /api/data_erasure/report

쿼리 매개변수

매개변수	유형	필수	설명
`from`	string (RFC 3339)	예	기간의 시작입니다.
`to`	string (RFC 3339)	아니요	기간의 끝입니다. 기본값은 현재 시간입니다.
`includeDryRuns`	boolean	아니요	드라이 런 작업을 포함합니다.

응답

필드	유형	설명
`filename`	string	제안된 파일 이름입니다(예: `data-erasure-2026-01-01-2026-04-01.csv`).
`content_type`	string	`text/csv`.
`content`	string (base64)	CSV 파일입니다. 열: `task_id`, `task_created`, `initiator_user_id`, `initiator_email`, `initiator_token_id`, `dry_run`, `identifier_type`, `identifier_hash`, `application_code`, `result`, `detail`, `row_created`.

데이터 삭제 작업 객체

필드	유형	설명
`task_id`	integer	작업 ID입니다.
`identifier_type`	string	`SUBJECT_IDENTIFIER_USER_ID`, `SUBJECT_IDENTIFIER_HWID`, 또는 `SUBJECT_IDENTIFIER_EMAIL`.
`application_codes`	array of strings	작업이 대상으로 하는 애플리케이션입니다.
`dry_run`	boolean	이 작업이 볼륨만 측정했는지 여부입니다.
`status`	string	`ERASURE_TASK_STATUS_PENDING`, `_IN_PROGRESS`, `_DONE`, 또는 `_FAILED`.
`total_count`	integer	이 작업이 대상으로 하는 식별자 × 애플리케이션 수입니다.
`deleted_count`	integer	삭제된(또는 드라이 런의 경우 삭제될) 수입니다.
`not_found_count`	integer	일치하는 항목이 없었던 수입니다.
`failed_count`	integer	실패한 수입니다. 원인은 ListTaskRows 또는 보고서를 참조하세요.
`fail_reason`	string	`status`가 `ERASURE_TASK_STATUS_FAILED`일 때 설정됩니다.
`initiator_user_id`	integer	작업을 시작한 Control Panel 사용자입니다. API 토큰이 시작한 경우 `0`입니다.
`initiator_token_id`	integer	작업을 시작한 API 토큰입니다. Control Panel 사용자가 시작한 경우 `0`입니다.
`initiator_email`	string	작업을 시작한 Control Panel 사용자의 이메일 주소입니다. API 토큰의 경우 비어 있습니다.
`created`	string (RFC 3339)	작업이 생성된 시점입니다.
`started_at`	string (RFC 3339)	삭제 작업이 시작된 시점입니다.
`finished_at`	string (RFC 3339)	작업이 최종 상태에 도달한 시점입니다.

데이터 삭제 작업 행 객체

필드	유형	설명
`identifier_hash`	string	식별자의 sha256입니다. 보고서는 식별자 자체를 저장하거나 반환하지 않습니다.
`application_code`	string	이 행의 결과가 적용되는 애플리케이션입니다.
`result`	string	`ERASURE_ROW_RESULT_DELETED`, `_NOT_FOUND`, `_SKIPPED`, 또는 `_FAILED`.
`detail`	string	기술적인 세부 정보로, 주로 실패 시 설정됩니다.
`created`	string (RFC 3339)	이 행이 기록된 시점입니다.

데이터 삭제 API

기본 URL

인증

규칙

오류 응답

엔드포인트

Create

요청 본문

요청 예시

응답

Upload

요청 (multipart/form-data)

응답

ListTasks

쿼리 매개변수

응답

GetTask

응답

ListTaskRows

쿼리 매개변수

응답

GetTaskReport

응답

GetJournalReport

쿼리 매개변수

응답

데이터 삭제 작업 객체

데이터 삭제 작업 행 객체

관련 항목