IMPLEMENTATION-BACKED CONTRACT · 2026-07-14

아리페이 관리자 API

현재 AriPay 백오피스 구현과 레거시 전체 기능을 대조해 만든 관리자 API 계약입니다. 1차 배포 자격증명은 admin:* 전체권한이며, 실제 공개 경계는 API 키·scope·감사 계층 구현 뒤 활성화합니다.

배포 전 계약https://lgalchfhimllpgrswxlv.supabase.co/functions/v1/admin-api

현재 URL은 아직 호출 계약입니다.

admin-api Edge Function과 API 키 저장소·scope 집행이 아직 없으므로 문서의 공개 경로는 배포 전 404가 정상입니다. 기존 Supabase service_role 키를 외부에 전달해 우회하면 안 됩니다.

전체권한의 경계

admin:*는 키에 고정된 AriPay 테넌트 안에서만 모든 v1 기능과 PII를 허용합니다. 다른 테넌트, Auth Admin, DB 직접 접근, 플랫폼 전역 platform.*, secret 원문 조회는 포함하지 않습니다.

빠른 시작

권한 구현 후 사용할 공통 호출 형식입니다.

인증

키는 X-API-Key로 전달합니다. 브라우저 번들·URL·로그에 넣지 않습니다.

curl -sS 'https://lgalchfhimllpgrswxlv.supabase.co/functions/v1/admin-api/v1/me' \
  -H 'X-API-Key: ari_live_REPLACE_ME' \
  -H 'Accept: application/json'

금전·파괴 작업

POST/PATCH/DELETE는 Idempotency-Key를 사용합니다. 같은 키+같은 본문은 같은 결과, 다른 본문은 409입니다.

curl -sS -X POST 'https://lgalchfhimllpgrswxlv.supabase.co/functions/v1/admin-api/v1/settlement-marks/transitions' \
  -H 'X-API-Key: ari_live_REPLACE_ME' \
  -H 'Idempotency-Key: 4aa6d9a8-1f50-4f98-a46e-0b4c7d326e42' \
  -H 'Content-Type: application/json' \
  --data '{"eventIds":["14000000-0000-0000-0000-000000000001"],"mark":"wait"}'

인증 · 공통 규칙

서버 권위, 테넌트 격리, 오류·페이지·시간 계약입니다.

항목	계약
인증	`X-API-Key`. 원문은 최초 1회만 표시하고 서버에는 Argon2id/HMAC 해시만 저장.
테넌트	tenantId는 키에서 결정. body/query의 tenantId는 거부하거나 무시하지 말고 400으로 실패.
v1 권한	최초 자격증명은 `admin:*`. 세부 scope는 문서화만 먼저 하고 후속 발급부터 최소권한 적용.
PII	full access는 원문 조회 가능. 응답 캐시 금지, 열람·파일 URL 발급 감사, secret은 항상 제외.
시간	저장은 UTC ISO-8601. 날짜 경계·월/분기 집계는 `tenants.timezone` IANA 값.
금액	KRW 원 단위 정수. 수수료율은 percent number. 부동소수 금액 금지.
페이지	목록은 cursor 우선, 기본 100, 최대 1000. 안정 정렬에 고유 ID tie-break 포함.
멱등	금전·상태·생성·삭제는 `Idempotency-Key` 필수. 24시간 이상 결과 보존 권장.
감사	requestId, clientId, tenantId, action, resource, result, IP, User-Agent 기록. secret·주민번호·계좌 원문은 로그 금지.
호출한도	초기 60 req/min/client, export 5 jobs/min/client 제안. 429 + Retry-After.

API 레퍼런스

v1은 최초 배포 대상, 후속은 전체 기능 카탈로그에 포함되지만 호출 대상이 아닙니다.

데이터 스키마

엔드포인트가 공유하는 핵심 필드입니다.

권한 매트릭스

1차 키의 admin:*가 모두 충족하지만, 서버는 endpoint별 세부 scope도 기록합니다.

Scope	기능	경계

기능 커버리지

레거시 AriPay 관리자 메뉴와 현재 native 구현의 대조 결과입니다.

기능	출시	백엔드	비고