던전앤파이터 API 레퍼런스

NeopleDFClient는 네오플 오픈 API를 통해 던전앤파이터 게임 데이터에 접근을 제공합니다.

클라이언트 초기화

import { NeopleDFClient } from 'neople-sdk-js';

const dfClient = new NeopleDFClient(apiKey, options?);

매개변수

• apiKey (string): 던전앤파이터 API 키
• options (object, 선택사항): 설정 옵션
  • httpAdapter: 사용자 지정 HTTP 클라이언트 어댑터
  • baseURL: API 요청을 위한 사용자 지정 기본 URL

캐릭터 메서드

searchCharacter(characterName, options?)

이름으로 캐릭터를 검색합니다.

엔드포인트: GET /df/characters

// 기본 검색
const characters = await dfClient.searchCharacter('홍길동');

// 고급 검색 옵션
const advancedSearch = await dfClient.searchCharacter('홍길동', {
  serverId: 'cain',
  limit: 20,
  wordType: 'match',
  isAllJobGrow: true,
  jobId: 'mage',
  jobGrowId: 'elementalist',
});

매개변수:

서버 ID 값: 서버 타입은 던전앤파이터 타입 → DFServerType을 참조하세요.

반환값: CharacterSearchResult - 페이지 정보가 포함된 캐릭터 검색 결과

응답 구조:

{
  "rows": [
    {
      "serverId": "cain",
      "characterId": "1234567890abcdef",
      "characterName": "홍길동",
      "level": 110,
      "jobId": "mage",
      "jobGrowId": "elementalist",
      "jobName": "마법사",
      "jobGrowName": "엘리멘탈마스터",
      "fame": 12345,
      "adventureName": "모험가이름"
    }
  ],
  "next": "nextPageUrl",
  "prev": null
}

getCharacter(serverId, characterId)

상세한 캐릭터 정보를 가져옵니다.

엔드포인트: GET /df/servers/{serverId}/characters/{characterId}

const character = await dfClient.getCharacter('cain', 'characterId');

매개변수:

반환값: CharacterDetail - 기본 스탯과 직업 정보를 포함한 상세 캐릭터 정보

응답 구조:

{
  "characterId": "1234567890abcdef",
  "characterName": "홍길동",
  "level": 110,
  "jobId": "mage",
  "jobGrowId": "elementalist",
  "jobName": "마법사",
  "jobGrowName": "엘리멘탈마스터",
  "adventureName": "모험가이름",
  "guildId": "guild123",
  "guildName": "길드명",
  "fame": 12345,
  "buff": {
    "skillInfo": {
      "buff": {
        "skillId": "skill123",
        "name": "스킬명",
        "option": "스킬 효과"
      }
    },
    "avatarInfo": {
      "buff": {
        "emblems": [
          {
            "slotId": "YELLOW",
            "itemName": "엠블렘명",
            "itemAvailableLevel": 1
          }
        ]
      }
    }
  }
}

getCharacterEquipment(serverId, characterId)

캐릭터의 장착 아이템을 가져옵니다.

엔드포인트: GET /df/servers/{serverId}/characters/{characterId}/equip/equipment

const equipment = await dfClient.getCharacterEquipment('cain', 'characterId');

매개변수:

• serverId (string): 서버 식별자
• characterId (string): 캐릭터 식별자

반환값: Equipment[] - 상세 스탯이 포함된 장착 아이템 목록

getCharacterAvatar(serverId, characterId)

캐릭터의 아바타 장비를 가져옵니다.

엔드포인트: GET /df/servers/{serverId}/characters/{characterId}/equip/avatar

const avatar = await dfClient.getCharacterAvatar('cain', 'characterId');

매개변수:

• serverId (string): 서버 식별자
• characterId (string): 캐릭터 식별자

반환값: Avatar[] - 아바타 장비 정보

getCharacterCreature(serverId, characterId)

캐릭터의 크리쳐 정보를 가져옵니다.

엔드포인트: GET /df/servers/{serverId}/characters/{characterId}/equip/creature

const creature = await dfClient.getCharacterCreature('cain', 'characterId');

매개변수:

• serverId (string): 서버 식별자
• characterId (string): 캐릭터 식별자

반환값: Creature - 크리쳐 정보와 스탯

getCharacterFlag(serverId, characterId)

캐릭터의 휘장 정보를 가져옵니다.

엔드포인트: GET /df/servers/{serverId}/characters/{characterId}/equip/flag

const flag = await dfClient.getCharacterFlag('cain', 'characterId');

매개변수:

• serverId (string): 서버 식별자
• characterId (string): 캐릭터 식별자

반환값: Flag - 휘장 정보와 스탯

getCharacterTalisman(serverId, characterId)

캐릭터의 탈리스만 정보를 가져옵니다.

엔드포인트: GET /df/servers/{serverId}/characters/{characterId}/equip/talisman

const talisman = await dfClient.getCharacterTalisman('cain', 'characterId');

매개변수:

• serverId (string): 서버 식별자
• characterId (string): 캐릭터 식별자

반환값: Talisman[] - 탈리스만 장비 정보

getCharacterTimeline(serverId, characterId, code?, startDate?, endDate?, limit?)

캐릭터의 활동 타임라인을 가져옵니다.

엔드포인트: GET /df/servers/{serverId}/characters/{characterId}/timeline

const timeline = await dfClient.getCharacterTimeline(
  'cain',
  'characterId',
  null,
  '2024-01-01',
  '2024-01-31'
);

매개변수:

code 값:

• 'all': 모든 타임라인 정보
• 'level': 레벨업 기록
• 'dungeon': 던전 입장 기록
• 'quest': 퀘스트 완료 기록

반환값: Timeline[] - 캐릭터 활동 타임라인

getCharacterSkillStyle(serverId, characterId)

캐릭터의 스킬 스타일 정보를 가져옵니다.

엔드포인트: GET /df/servers/{serverId}/characters/{characterId}/skill/style

const skillStyle = await dfClient.getCharacterSkillStyle('cain', 'characterId');

매개변수:

• serverId (string): 서버 식별자
• characterId (string): 캐릭터 식별자

반환값: SkillStyle - 스킬 스타일 정보

getCharacterBuffSkillEquipment(serverId, characterId)

캐릭터의 장비 버프 스킬을 가져옵니다.

엔드포인트: GET /df/servers/{serverId}/characters/{characterId}/skill/buff/equip/equipment

const buffSkills = await dfClient.getCharacterBuffSkillEquipment(
  'cain',
  'characterId'
);

매개변수:

• serverId (string): 서버 식별자
• characterId (string): 캐릭터 식별자

반환값: BuffSkill[] - 장비 버프 스킬 정보

getCharacterBuffSkillAvatar(serverId, characterId)

캐릭터의 아바타 버프 스킬을 가져옵니다.

엔드포인트: GET /df/servers/{serverId}/characters/{characterId}/skill/buff/equip/avatar

const avatarBuffSkills = await dfClient.getCharacterBuffSkillAvatar(
  'cain',
  'characterId'
);

매개변수:

• serverId (string): 서버 식별자
• characterId (string): 캐릭터 식별자

반환값: BuffSkill[] - 아바타 버프 스킬 정보

getCharacterBuffSkillCreature(serverId, characterId)

캐릭터의 크리처 버프 스킬을 가져옵니다.

엔드포인트: GET /df/servers/{serverId}/characters/{characterId}/skill/buff/equip/creature

const creatureBuffSkills = await dfClient.getCharacterBuffSkillCreature(
  'cain',
  'characterId'
);

매개변수:

• serverId (string): 서버 식별자
• characterId (string): 캐릭터 식별자

반환값: BuffSkill[] - 크리처 버프 스킬 정보

getCharactersByFame(serverId, jobId?, jobGrowId?, limit?)

서버별 명성도 상위 캐릭터를 가져옵니다.

엔드포인트: GET /df/servers/{serverId}/characters

const famousCharacters = await dfClient.getCharactersByFame('cain', 'jobId');

매개변수:

반환값: Character[] - 명성도 상위 캐릭터 목록

getCharacterStatus(serverId, characterId)

캐릭터의 상세 상태 정보를 가져옵니다.

엔드포인트: GET /df/servers/{serverId}/characters/{characterId}/status

const status = await dfClient.getCharacterStatus('cain', 'characterId');

매개변수:

• serverId (string): 서버 식별자
• characterId (string): 캐릭터 식별자

반환값: CharacterStatus - 상세 캐릭터 스탯과 속성

아이템 메서드

searchItems(itemName, limit?)

이름으로 아이템을 검색합니다.

엔드포인트: GET /df/items

const items = await dfClient.searchItems('무기');

매개변수:

반환값: ItemSearchResult - 아이템 검색 결과

getItem(itemId)

상세한 아이템 정보를 가져옵니다.

엔드포인트: GET /df/items/{itemId}

const item = await dfClient.getItem('itemId');

매개변수:

반환값: ItemDetail - 스탯과 설명을 포함한 상세 아이템 정보

getSetItem(setItemId)

세트 아이템 정보를 가져옵니다.

엔드포인트: GET /df/setitems/{setItemId}

const setItem = await dfClient.getSetItem('setItemId');

매개변수:

• setItemId (string): 세트 아이템 식별자

반환값: SetItemDetail - 세트 효과와 구성 아이템 정보

searchSetItems(setItemName, limit?)

이름으로 세트 아이템을 검색합니다.

엔드포인트: GET /df/setitems

const setItems = await dfClient.searchSetItems('세트이름');

매개변수:

• setItemName (string): 검색할 세트 아이템 이름
• limit (number, 선택사항): 최대 결과 개수

반환값: SetItemSearchResult - 세트 아이템 검색 결과

getMultiItems(itemIds)

여러 아이템 정보를 한 번에 가져옵니다.

엔드포인트: GET /df/multi/items

const items = await dfClient.getMultiItems(['itemId1', 'itemId2', 'itemId3']);

매개변수:

• itemIds (string[]): 아이템 식별자 배열

반환값: ItemDetail[] - 여러 아이템의 상세 정보

getMultiSetItems(setItemIds)

여러 세트 아이템 정보를 한 번에 가져옵니다.

엔드포인트: GET /df/multi/setitems

const setItems = await dfClient.getMultiSetItems(['setId1', 'setId2']);

매개변수:

• setItemIds (string[]): 세트 아이템 식별자 배열

반환값: SetItemDetail[] - 여러 세트 아이템의 상세 정보

getItemHashtags()

아이템 검색용 해시태그 목록을 가져옵니다.

엔드포인트: GET /df/items/hashtags

const hashtags = await dfClient.getItemHashtags();

반환값: string[] - 아이템 검색에 사용할 수 있는 해시태그 목록

직업 및 스킬 메서드

getJobs()

사용 가능한 직업 목록을 가져옵니다.

엔드포인트: GET /df/jobs

const jobs = await dfClient.getJobs();

반환값: Job[] - 직업 ID와 이름이 포함된 직업 목록

getSkillsByJob(jobId)

특정 직업의 스킬 목록을 가져옵니다.

엔드포인트: GET /df/skills/{jobId}

const skills = await dfClient.getSkillsByJob('jobId');

매개변수:

반환값: Skill[] - 해당 직업의 모든 스킬 정보

getSkillDetail(jobId, skillId)

특정 스킬의 상세 정보를 가져옵니다.

엔드포인트: GET /df/skills/{jobId}/{skillId}

const skill = await dfClient.getSkillDetail('jobId', 'skillId');

매개변수:

반환값: SkillDetail - 스킬 상세 정보와 효과

getMultiSkills(jobId, skillIds)

여러 스킬 정보를 한 번에 가져옵니다.

엔드포인트: GET /df/multi/skills

const skills = await dfClient.getMultiSkills('jobId', ['skillId1', 'skillId2']);

매개변수:

• jobId (string): 직업 식별자
• skillIds (string[]): 스킬 식별자 배열

반환값: SkillDetail[] - 여러 스킬의 상세 정보

아바타 마켓 메서드

getAvatarMarketSale(params)

아바타 마켓 판매 목록을 가져옵니다.

엔드포인트: GET /df/avatar-market/sale

const sales = await dfClient.getAvatarMarketSale({
  jobId: 'jobId',
  limit: 20,
});

매개변수:

• params (object): 검색 매개변수
  • jobId (string, 선택사항): 직업 필터
  • limit (number, 선택사항): 최대 결과 개수
  • hashtags (string[], 선택사항): 해시태그 필터

반환값: AvatarMarketSale[] - 아바타 마켓 판매 목록

getAvatarMarketSold(params)

아바타 마켓 판매 완료 목록을 가져옵니다.

엔드포인트: GET /df/avatar-market/sold

const sold = await dfClient.getAvatarMarketSold({
  jobId: 'jobId',
});

매개변수:

• params (object): 검색 매개변수

반환값: AvatarMarketSold[] - 아바타 마켓 판매 완료 목록

getAvatarMarketItem(itemId)

아바타 마켓 특정 아이템 정보를 가져옵니다.

엔드포인트: GET /df/avatar-market/items/{itemId}

const item = await dfClient.getAvatarMarketItem('itemId');

매개변수:

• itemId (string): 아바타 아이템 식별자

반환값: AvatarItem - 아바타 아이템 상세 정보

getAvatarMarketSoldItem(itemId)

아바타 마켓 판매 완료 아이템 정보를 가져옵니다.

엔드포인트: GET /df/avatar-market/sold/{itemId}

const soldItem = await dfClient.getAvatarMarketSoldItem('itemId');

매개변수:

• itemId (string): 아바타 아이템 식별자

반환값: AvatarItem - 판매 완료된 아바타 아이템 정보

getAvatarMarketHashtags()

아바타 마켓 해시태그 목록을 가져옵니다.

엔드포인트: GET /df/avatar-market/hashtags

const hashtags = await dfClient.getAvatarMarketHashtags();

반환값: string[] - 아바타 마켓에서 사용할 수 있는 해시태그 목록

기타 메서드

getItemShop()

아이템 상점 정보를 가져옵니다.

엔드포인트: GET /df/itemshop

const shop = await dfClient.getItemShop();

반환값: ItemShop - 아이템 상점 판매 목록

경매장 메서드

searchAuction(params)

경매장 목록을 검색합니다.

엔드포인트: GET /df/auction

// 기본 검색
const auctions = await dfClient.searchAuction({
  itemName: '무기',
  minLevel: 85,
  maxLevel: 90,
});

// 고급 검색 옵션
const advancedAuction = await dfClient.searchAuction({
  itemName: '강화의 숨결',
  wordType: 'front',
  minLevel: 85,
  maxLevel: 90,
  rarity: 'unique',
  minReinforce: 10,
  maxReinforce: 15,
  sort: 'price_asc',
  limit: 100,
});

매개변수:

rarity 값:

• 'common': 일반
• 'uncommon': 고급
• 'rare': 희귀
• 'unique': 유니크
• 'epic': 에픽
• 'legendary': 레전더리

sort 값:

• 'unitPrice': 개당 가격순
• 'reinforce': 강화 수치순
• 'level': 레벨순
• 'deadline': 마감시간순
  • sort (string, 선택사항): 정렬 방식
    • 'price_asc': 가격 낮은 순
    • 'price_desc': 가격 높은 순
    • 'reinforce_asc': 강화 낮은 순
    • 'reinforce_desc': 강화 높은 순
    • 'level_asc': 레벨 낮은 순
    • 'level_desc': 레벨 높은 순
  • limit (number, 선택사항): 결과 제한

반환값: AuctionSearchResult - 경매장 검색 결과

getAuctionItem(auctionNo)

특정 경매 아이템의 상세 정보를 가져옵니다.

엔드포인트: GET /df/auction/{auctionNo}

const auctionItem = await dfClient.getAuctionItem('auctionNo');

매개변수:

• auctionNo (string): 경매 번호

반환값: AuctionItem - 경매 아이템 상세 정보

getAuctionSold(params)

판매된 경매 아이템을 검색합니다.

엔드포인트: GET /df/auction-sold

const soldItems = await dfClient.getAuctionSold({
  itemId: 'itemId',
  serverId: 'cain',
  limit: 20
});

매개변수:

• params (AuctionSoldParams): 검색 매개변수
  • itemId (string, 선택사항): 아이템 ID
  • serverId (string, 선택사항): 서버 ID
  • limit (number, 선택사항): 최대 결과 수

반환값: AuctionSoldResult - 판매된 경매 아이템 목록

서버 정보

getServers()

사용 가능한 서버 목록을 가져옵니다.

엔드포인트: GET /df/servers

const servers = await dfClient.getServers();

반환값: Server[] - 식별자가 포함된 사용 가능한 서버 목록

오류 처리

모든 메서드는 다양한 이유로 오류를 발생시킬 수 있습니다:

try {
  const character = await dfClient.getCharacter('cain', 'invalidId');
} catch (error) {
  if (error.status === 404) {
    console.log('캐릭터를 찾을 수 없습니다');
  } else if (error.status === 401) {
    console.log('잘못된 API 키입니다');
  } else {
    console.error('API 오류:', error.message);
  }
}

사용 예시

import { NeopleDFClient } from 'neople-sdk-js';

async function getCharacterInfo(characterName: string) {
  const dfClient = new NeopleDFClient(process.env.NEOPLE_DF_API_KEY);

  try {
    // 캐릭터 검색
    const searchResults = await dfClient.searchCharacter(characterName);

    if (searchResults.rows.length === 0) {
      console.log('캐릭터를 찾을 수 없습니다');
      return;
    }

    const { serverId, characterId } = searchResults.rows[0];

    // 캐릭터 세부 정보 조회
    const [character, equipment, skills] = await Promise.all([
      dfClient.getCharacter(serverId, characterId),
      dfClient.getCharacterEquipment(serverId, characterId),
      dfClient.getCharacterSkill(serverId, characterId),
    ]);

    console.log('캐릭터:', character);
    console.log('장비:', equipment);
    console.log('스킬:', skills);
  } catch (error) {
    console.error('오류:', error.message);
  }
}