역할별 엔드포인트 접근
로그인할 수 없거나, 작업이 차단되거나, POS에서 업데이트를 요청하면 앱 메시지의 코드를 확인하고 여기에서 해결하세요:
오류 진단
다시 로그인하기 (AUTH101)
앱에 "토큰 갱신 후에도 요청이 인증되지 않았습니다 - 다시 로그인하세요" 메시지가 표시됩니다.
- WCPOS가 WordPress 로그인 창을 자동으로 엽니다. 같은 캐셔 계정으로 로그인하세요.
- 창을 닫았다면 앱에 "계속하려면 로그인하세요" 메시지가 표시됩니다. 메시지의 로그인 버튼을 눌러 창을 다시 여세요.
- 다시 로그인하면 전송 대기 중인 판매 내역이 자동으로 전송됩니다.
메시지가 곧바로 다시 나타나면 사이트 관리자에게 도움을 요청하고 AUTH101 페이지를 보내세요.
로그인 실패 상세 정보
앱이 401을 받아 토큰을 갱신했지만 재시도에서도 401을 받았습니다. 이는 역할이 아닌 로그인 계층의 문제입니다. 403은 토큰 갱신을 유발하지 않습니다. 앱과 WordPress 사이에서 무언가가 토큰을 제거하거나 거부하고 있으며, 보안 또는 인증 플러그인이 원인인 경우가 많습니다(AUTH301).
관리자에게 역할 확인 요청하기 (AUTH201)
로그인되어 있지만 현재 역할로는 이 작업을 수행할 수 없습니다. 사이트 관리자에게 직원 접근 권한에서 접근 권한을 확인해 달라고 요청하세요. 관리자는 AUTH201의 안내에 따라 원인을 찾을 수 있습니다.
역할 권한 상세 정보
서버가 로그인한 사용자에게 403으로 응답했습니다. 사용자에게 access_woocommerce_pos가 없거나, 해당 경로에 manage_woocommerce_pos 또는 install_plugins가 필요합니다. 아래 목록에서 엔드포인트를 찾으세요. 목록상 사용자의 역할이 접근할 수 있다면 역할이 기본값에서 변경되었을 가능성이 큽니다. WCPOS 기본값에서 변경됨 표시가 있는 접근 권한 화면, 역할 편집 플러그인 또는 사용자 정의 코드에서 변경되었을 수 있습니다. 사용자에게 추가로 부여된 역할이 권한을 거부할 수도 있습니다.
엔드포인트가 목록에 없으면 이 목록의 근거가 되는 테스트에서 다루지 않는 것입니다. 해당 경로 자체의 권한 검사를 확인하세요. WCPOS Pro는 사용자에게 권한이 없는 매장에 대한 접근도 거부할 수 있습니다. 예를 들어 403 wcpos_display_store_forbidden ("이 매장에 대한 권한이 없습니다.")을 반환합니다.
앱 업데이트하기 (SYNC341)
앱에 "이 기기의 POS 앱을 업데이트하세요." 메시지가 표시됩니다. 사이트의 플러그인이 앱보다 최신 버전입니다. 앱을 업데이트한 다음 다시 여세요:
- 웹: 브라우저 탭을 새로고침하세요. 메시지가 다시 나타나면 컴퓨터에서는 Shift 키를 누른 채 새로고침하세요. 휴대전화나 태블릿에서는 사이트 관리자에게 도움을 요청하고 SYNC341 페이지를 보내세요.
- 데스크톱: 앱에서 제공하는 업데이트를 설치한 다음 앱을 다시 여세요. 업데이트가 제공되지 않으면 Windows, Mac (Intel 또는 Apple silicon), Linux용 최신 데스크톱 빌드를 다운로드하세요.
- iPhone 및 iPad: TestFlight 베타에서 WCPOS를 업데이트하세요.
- Android: Google Play 베타에서 WCPOS를 업데이트하세요.
아직 새 앱 버전이 없을 때 사이트 관리자가 할 수 있는 조치를 비롯한 나머지 내용은 SYNC341에 있습니다.
앱 버전 상세 정보
앱이 플러그인의 동기화 프로토콜보다 오래되어 서버가 v2 경로에서 426으로 응답했습니다.
권한 오류와 토큰 오류의 차이
AUTH201은 사용자가 로그인했지만 권한이 없다는 뜻입니다. 관리자에게 역할을 문의하세요. AUTH101은 로그인 자체가 실패했다는 뜻입니다. 다시 로그인하세요.
두 오류를 구분하는 방법
403(AUTH201): 사용자가 로그인했지만 이 작업에 대한 권한이 없습니다. 역할에 부여된 권한과 아래 목록에서 엔드포인트에 필요한 권한을 확인하세요.401(AUTH101, "토큰 갱신 후에도 요청이 인증되지 않았습니다"): 서버가 앱의 요청을 인증하지 못했으며 로그인한 사용자가 없습니다. 다시 로그인하세요. 계속 반복되면 토큰과 앱과 WordPress 사이에서 토큰을 제거하거나 거부하는 요소를 확인하세요.
브라우저의 네트워크 패널이나 서버 측 로그에서 거부 응답을 확인하세요. WP Admin > POS > 설정 > 도구 > 로그에도 토큰 형식이 잘못되었거나 단순 만료 이외의 이유로 거부된 각 401이 기록됩니다. 상태와 오류 코드는 응답 본문에 있습니다. 로그인한 사용자는 본문에 없으므로 서버에서 확인하세요. 예를 들어 요청이 실행되는 동안 디버그 로그에서 get_current_user_id()를 사용할 수 있습니다.
역할 또는 권한 오류:
- 상태:
403 - 코드:
woocommerce_pos_rest_forbidden또는rest_forbidden과 같은 경로 자체의 코드 - 로그인한 사용자(서버 측): 캐셔의 WordPress 사용자 ID
토큰 또는 로그인 오류:
- 상태:
401 - 코드:
woocommerce_pos_rest_unauthorized data.reason:woocommerce_pos_auth_token_expired와 같은 토큰 오류- 로그인한 사용자(서버 측):
0(로그인한 사용자 없음)
사용자 값이 영이 아니면 권한 문제를 가리킵니다. 사용자 값이 0이면 토큰이나 앱과 WordPress 사이의 요소를 가리킵니다.
관련 문서
관리자 및 개발자용 안내
캐셔는 여기까지만 읽어도 됩니다. 이 페이지의 나머지 내용은 로그인, 사용자 역할, 앱 버전 중 무엇이 원인인지 알아야 하는 사이트 관리자와 개발자를 위한 것입니다. 각 기본 역할이 접근할 수 있는 WCPOS REST 엔드포인트와 서버가 요청을 거부할 때 반환하는 응답을 나열합니다. 역할이 수행할 수 있는 작업을 변경하려면 직원 접근 권한을 사용하세요.
각 기본 역할이 접근할 수 있는 범위
캐셔는 환불을 포함해 판매에 필요한 모든 작업을 수행할 수 있으며 영수증 전송을 위해 클라우드 인쇄 프린터 정보를 읽을 수 있습니다. 그 외의 모든 설정, 로그, 매장 관리에는 관리자 또는 상점 관리자 역할이 필요합니다.
각 기본 역할의 접근 범위
administrator: 이 페이지의 모든 엔드포인트.shop_manager: WordPress의install_plugins권한이 필요한 Pro의 확장 프로그램 설치 및 업데이트 작업을 제외한 모든 엔드포인트.cashier: 환불을 포함한 판매 과정의 모든 작업. 설정 화면, 로그, 확장 프로그램, 매장 관리에는 접근할 수 없습니다. 읽을 수 있는 설정은 클라우드 인쇄 프린터 정보뿐이며, 이를 통해 POS에서 해당 프린터로 영수증을 보낼 수 있습니다.
이 목록의 검증 방법
목록은 플러그인의 통합 테스트를 바탕으로 작성되었습니다. 각 테스트는 앱과 마찬가지로 WCPOS 액세스 토큰으로 로그인하고 각 역할로 엔드포인트를 호출합니다. 무료 버전 테스트에서 허용된 엔드포인트는 400 미만의 상태로 응답해야 합니다. Pro 테스트는 테스트 데이터가 최소한으로 구성되어 있어 400 또는 404도 허용합니다. 어느 응답이든 사용자가 권한 검사를 통과했음을 입증합니다. 거부된 엔드포인트는 사용자가 로그인한 상태를 유지하면서 403으로 응답해야 합니다.
서버의 요청 검사 방식
POS로 보내는 모든 요청은 앱 버전, 로그인, POS 접근 권한, 경로 자체 규칙의 순서로 최대 네 가지 검사를 거칩니다. 처음 실패한 검사에 따라 응답이 결정됩니다.
네 가지 검사의 순서
/wcpos/v1/ 또는 /wcpos/v2/에 대한 요청은 다음 검사를 순서대로 거칩니다. 공개 로그인 경로와 프린터 폴링은 검사 2와 3을 건너뜁니다. 세 가지 동기화 유지보수 경로는 WooCommerce의 manage_woocommerce를 가진 사용자에 대해 검사 3을 건너뛰고 대신 해당 권한을 요구합니다.
- 앱 프로토콜 (대부분의 v2 경로). 실패하면
426과 코드wcpos_update_required를 반환합니다. 앱에 SYNC341이 표시되면 앱을 업데이트하세요. - 액세스 토큰. 실패하면
401과 코드woocommerce_pos_rest_unauthorized를 반환하며 로그인한 사용자가 없습니다. 앱은 토큰을 한 번 갱신하고 재시도합니다. 재시도도 실패하면 AUTH101: 세션이 만료되었습니다가 표시됩니다. - POS 접근 권한. 로그인한 사용자에게
access_woocommerce_pos가 없으면403과 코드woocommerce_pos_rest_forbidden을 반환합니다. 앱에 AUTH201: 역할 권한이 부족합니다가 표시됩니다. - 경로 자체의 검사. 실패하면
403과 함께rest_forbidden등의 코드를 반환합니다. 이 경우에도 앱에 AUTH201이 표시됩니다.
세 가지 권한과 이를 가진 역할
플러그인은 활성화될 때 자체 권한 두 가지를 기본 역할에 부여합니다. 업데이트 시에는 해당 릴리스에서 새로 추가된 권한만 부여하므로 접근 권한 화면에서 제거한 권한은 제거된 상태로 유지됩니다. install_plugins는 WordPress 자체 권한입니다.
access_woocommerce_pos: 관리자, 상점 관리자, 캐셔. 공개 로그인 경로, 프린터 폴링, 세 가지 동기화 유지보수 경로(/wcpos/v2/uuid/backfill,/orders/index/backfill,/integrity/rebuild)를 제외한 모든 POS 엔드포인트에 필요합니다. 이 예외 경로들은 대신 WooCommerce의manage_woocommerce가 필요하며, 일부 엔드포인트에는 아래 두 권한 중 하나도 필요합니다.manage_woocommerce_pos: 관리자와 상점 관리자. 설정, 로그, 확장 프로그램 목록, Pro 매장 관리에 접근할 수 있습니다.install_plugins(WordPress): 관리자만 해당합니다. Pro의 확장 프로그램 설치 및 업데이트를 사용할 수 있습니다.
동기화 엔드포인트 (v2)
2.0 앱은 /wcpos/v2/를 통해 동기화합니다. 모든 기본 역할은 앱이 사용하는 모든 동기화 경로에 접근할 수 있습니다.
모든 역할: v2 동기화 경로
- 상태:
GET /wcpos/v2/status - 카탈로그:
GET /wcpos/v2/products,/variations,/products/categories,/products/tags,/products/brands - 고객, 쿠폰, 세금:
GET /wcpos/v2/customers,/coupons,/taxes - 주문:
GET /wcpos/v2/orders,/orders/pull - 변경 피드:
GET /wcpos/v2/changes/sequence-log,/changes/revision-hash,/changes/range-checksum,/changes/config-fingerprint,/changes/tick - 무결성 검사:
GET /wcpos/v2/digests,/integrity/scan,/integrity/bucket - 바코드 조회:
GET /wcpos/v2/resolve/barcode - 새 주문 전송:
POST /wcpos/v2/push/orders
무료 플러그인의 엔드포인트 접근 권한표
이 /wcpos/v1/ 경로는 로그인, 결제, 영수증, 설정 화면에 사용됩니다. 모든 역할이 판매에 사용되는 경로에 접근할 수 있습니다. 설정 화면, 로그, 확장 프로그램 목록에는 관리자 또는 상점 관리자 역할이 필요합니다.
모든 역할(관리자, 상점 관리자, 캐셔): 엔드포인트 27개
GET /wcpos/v1/stores: 앱에서 열 수 있는 매장GET /wcpos/v1/cashier/{id}: 로그인한 캐셔GET /wcpos/v1/cashier/{id}/stores: 이 캐셔가 사용할 수 있는 매장GET /wcpos/v1/products,/products/variations: 카탈로그GET /wcpos/v1/products/categories,/tags,/brands: 카탈로그 필터GET /wcpos/v1/coupons: 쿠폰 조회GET /wcpos/v1/orders: 주문 내역POST /wcpos/v1/orders: 판매PATCH /wcpos/v1/orders/{id}: 주문 완료GET및POST /wcpos/v1/orders/{id}/checkout: 결제 처리GET /wcpos/v1/receipts/{order_id}: 영수증 렌더링GET /wcpos/v1/data/order_statuses: 상태 이름GET /wcpos/v1/customers: 고객 검색POST /wcpos/v1/customers: 고객 추가PATCH /wcpos/v1/customers/{id}: 고객 편집GET /wcpos/v1/taxes,/taxes/classes: 세율 및 세금 클래스GET /wcpos/v1/shipping_methods: 배송 항목GET /wcpos/v1/payment-gateways: 결제 옵션POST /wcpos/v1/payment-gateways/{id}/bootstrap: 결제 설정GET /wcpos/v1/templates,/templates/active,/templates/gallery: 영수증 템플릿
모든 역할은 클라우드 인쇄 프린터 정보를 제공하는 GET /wcpos/v1/settings/cloud-print도 읽을 수 있어 POS에서 해당 프린터로 영수증을 보낼 수 있습니다. 필요한 권한은 access_woocommerce_pos뿐입니다. 이는 27개에 포함되지 않습니다. 별도 테스트에서 이 권한은 있지만 설정 접근 권한은 없는 사용자를 검사합니다.
관리자와 상점 관리자만: 엔드포인트 6개
여기에는 manage_woocommerce_pos가 필요하며, 캐셔에게는 403이 반환됩니다.
GET /wcpos/v1/settings/general: 일반 설정 화면GET /wcpos/v1/settings/checkout: 결제 설정 화면GET /wcpos/v1/settings/tax_ids: 세금 ID 설정 화면GET /wcpos/v1/settings/payment-gateways: 결제 게이트웨이 설정 화면GET /wcpos/v1/extensions: 확장 프로그램 목록GET /wcpos/v1/logs: 로그 화면
/wcpos/v1/settings 자체에는 읽을 수 있는 인덱스가 없습니다. 대신 /settings/general과 같은 섹션을 읽으세요.
Pro 플러그인의 엔드포인트 접근 권한표
WCPOS Pro는 다음 경로를 추가합니다. 모든 역할이 주문을 환불할 수 있습니다. 매장 관리와 라이선스 키에는 관리자 또는 상점 관리자 역할이 필요하고, 확장 프로그램 설치에는 관리자 역할이 필요합니다.
역할별 Pro 경로
모든 역할:
POST /wcpos/v1/orders/{id}/refunds: 주문 환불
관리자와 상점 관리자만 (manage_woocommerce_pos 필요):
GET /wcpos/v1/stores/{id}/edit: 편집할 매장 열기POST /wcpos/v1/stores: 매장 추가PATCH /wcpos/v1/stores/{id}: 매장 저장POST /wcpos/v1/settings/license: 라이선스 키 저장
관리자만 (WordPress의 install_plugins 권한 필요):
POST /wcpos/v1/extensions/action: 확장 프로그램 설치 또는 업데이트
토큰 만료 테스트 범위
기본적으로 앱의 로그인은 30분 동안 유효하며 캐셔가 로그인한 시점부터 최대 30일 동안 자동으로 갱신됩니다. 그 이후에는 캐셔가 다시 로그인합니다(AUTH101). 만료된 토큰은 항상 401을 반환하고 403은 반환하지 않으므로 역할 문제로 나타나지 않습니다.
토큰 유효 기간과 각 경우의 반환값
앱은 유효 기간이 30분인 액세스 토큰과 30일인 갱신 토큰으로 로그인합니다. 코드에서 wcpos_jwt_access_token_expire 및 wcpos_jwt_refresh_token_expire 필터로 두 기간을 변경할 수 있습니다. 같은 테스트에서 세 역할 모두에 대해 각 토큰이 만료될 때의 동작을 확인합니다:
- 유효한 액세스 토큰: 엔드포인트가 정상적으로 응답합니다.
- 만료되었거나 누락되었거나 형식이 잘못된 액세스 토큰:
401, 코드woocommerce_pos_rest_unauthorized, 로그인한 사용자 없음. 앱은 토큰을 한 번 갱신하고 재시도합니다. - 만료된 액세스 토큰, 유효한 갱신 토큰: 갱신 시 새 액세스 토큰이 반환되고 재시도가 성공합니다.
- 만료된 갱신 토큰:
woocommerce_pos_auth_token_expired와 함께 갱신이 거부되며 캐셔가 다시 로그인합니다(AUTH101).
만료된 액세스 토큰으로는 사용자가 로그인되지 않으므로 역할 검사에 도달하지 않습니다. 항상 401이며 403은 반환하지 않습니다. 테스트는 캐셔 역할의 v2 경로에서도 동일함을 입증합니다.