서버 API | Noxyr 문서

API가 제공하는 것

API는 읽기 전용이며 한 서버에만 적용돼요. 로그인 없이 대시보드의 수치를 보고 싶은 상태 페이지, 스프레드시트, 내부 도구를 위한 것이에요. 설정을 바꾸거나, 티켓을 닫거나, 인보이스를 만들 수는 없어요.

모든 엔드포인트는 https://noxyrbot.com/api/v1 아래에 있으며 JSON을 반환해요. 키가 서버를 식별하므로 어떤 엔드포인트도 서버 ID를 받지 않아요.

GET /api/v1/: 이 키에서 켜진 범위와 접근할 수 있는 엔드포인트.
GET /api/v1/server: 이름, 아이콘, 멤버 수, 온라인 수, 부스트, 생성일.
GET /api/v1/tickets: 전체 합계, 열림 및 닫힘 수, 7일과 30일 동안의 추이, 평균 평점.
GET /api/v1/activity?days=30: 최대 90일 동안의 일별 메시지, 입장, 퇴장 수.
GET /api/v1/invoices: 인보이스 수, 통화별 매출, 결제 상태. 인보이스 링크 범위를 켜면 ?limit=으로 최근 인보이스와 다운로드 가능한 이미지 URL을 추가로 받을 수 있어요.
GET /api/v1/reviews: 평균 평점, 별점별 분포, 최신 공개 리뷰 5개.
GET /api/v1/giveaways: 진행 중 및 종료된 기브어웨이 수, 전체 참가 수, 현재 기브어웨이 목록.

키 만들기

서버마다 키는 하나예요. 서버의 API 페이지에서 생성되며 한 번만 표시돼요. 해시만 저장되므로, 키를 잃어버리면 다시 생성해야 하고 기존 키는 무효화돼요.

대시보드에서 서버를 열고 API로 이동하세요.
생성을 누르고 nxr_로 시작하는 키를 복사하세요. 다시 표시되지 않아요.
필요 없는 범위는 모두 끄세요. 인보이스 링크는 고객의 인보이스 이미지를 노출하므로 기본으로 꺼져 있어요.
선택 사항으로 채널 설정을 누르면, 봇이 서버에 API 카테고리와 엔드포인트 목록이 있는 채널을 만들어 줘요.

이 페이지에는 키가 마지막으로 사용된 시간과 요청 횟수도 표시돼요. 키가 유출됐는지 가장 빠르게 확인할 수 있어요. 토글로 끌 수 있고, 폐기하면 완전히 삭제돼요.

범위

범위는 필드가 아니라 엔드포인트를 제어해요. 범위가 꺼진 엔드포인트에 요청하면 403과 함께 해당 범위 이름이 적힌 메시지가 반환돼요.

overview: /server
tickets: /tickets
activity: /activity
invoices: /invoices
invoiceLinks: 이미지 링크가 포함된 최근 인보이스 목록을 추가해요. 기본으로 꺼져 있어요.
reviews: /reviews
giveaways: /giveaways

인증과 예시 요청

키를 Authorization 헤더의 Bearer 토큰으로 보내세요. 브라우저에서도 호출할 수 있어요(CORS 허용). 다만 프런트엔드 코드에 들어간 키는 공개 키이므로, API는 내가 관리하는 서버에서 호출하세요.

curl -H "Authorization: Bearer nxr_your_key" https://noxyrbot.com/api/v1/tickets
응답: {"total":128,"open":4,"closed":124,"opened7d":9,"opened30d":41,"closed7d":8,"averageRating":4.6,"ratingsCount":37}

요청 제한

키 하나당 분당 60회까지 요청할 수 있어요. 제한은 모든 응답의 표준 RateLimit 헤더로 알려 주며, 초과하면 HTTP 429와 함께 오류 “rate_limited”가 반환돼요. 데이터가 바뀌는 속도보다 빠르게 조회하지 마세요. 티켓과 판매 합계는 1분에 한 번만 읽어도 충분해요.

오류

모든 오류는 기계가 읽을 수 있는 오류 코드와 사람이 읽을 수 있는 메시지가 담긴 JSON으로 반환돼요.

401 인증 오류: Authorization 헤더가 없거나, Bearer 토큰이 아니거나, 키가 존재하지 않아요.
403 key_disabled: 대시보드에서 이 키가 꺼져 있어요.
403 scope_disabled: 이 키에서 해당 범위가 꺼져 있어요.
404 not_found: 알 수 없는 엔드포인트예요. 메시지에 사용할 수 있는 엔드포인트 목록이 나와요.
404 guild_unavailable: 봇이 더 이상 서버에 없어요.
429 rate_limited: 1분에 60회를 넘는 요청이에요.
500 internal_error: Noxyr 쪽에서 문제가 발생했어요. 나중에 다시 시도하세요.