README

LG U+ Centrex REST API를 PHP에서 간편하게 사용할 수 있는 클라이언트 라이브러리입니다.

요구 사항

PHP >= 7.4
ext-curl
ext-json

설치

composer require knifelemon/lguplus-centrex-restapi

초기화

use LGUPlus\Centrex\LGUPlus;
use LGUPlus\Centrex\LGUPlusException;

$lgu = new LGUPlus('내선번호', '비밀번호');
// 또는
$lgu = LGUPlus::getInstance('내선번호', '비밀번호');

내선번호의 하이픈(-)은 자동으로 제거됩니다. 비밀번호는 SHA-512로 해싱되어 전송됩니다.

주의: 이 라이브러리는 LG U+ Centrex 유료 서비스 가입자 전용입니다. API 사용 전 LG U+에서 REST API 부가서비스를 신청해야 합니다.

통화 제어

전화 걸기

$lgu->call('010-1234-5678');

if ($lgu->isSuccess()) {
    // 성공
} else {
    $error = $lgu->getApiError();
    echo $error; // "[1003] 인증 오류"
}

전화 끊기

$lgu->hangup();

녹취

$lgu->startRecording(); // 녹취 시작
$lgu->stopRecording();  // 녹취 중지

통화 보류

$lgu->startHold(); // 보류 시작
$lgu->stopHold();  // 보류 해제

다자간 통화

$lgu->conference(['010-1111-2222', '010-3333-4444']);

주소록

// 단일 페이지 조회
$lgu->addressList(1);
$contacts = $lgu->getContacts(); // Contact[]
$pageInfo = $lgu->getPaginationInfo(); // ListInfo

// 페이지 순회 (Generator)
foreach ($lgu->eachAddressPage() as $page => $contacts) {
    foreach ($contacts as $contact) {
        echo $contact->name . ' / ' . $contact->phone1 . PHP_EOL;
    }
}

// 전체 주소록 한 번에 가져오기
$allContacts = $lgu->getAllAddresses(); // Contact[]

녹취 목록

$lgu->recordList(1);
$recordings = $lgu->getRecordings(); // Recording[]

foreach ($recordings as $rec) {
    echo $rec->fileName . ' (' . $rec->fileSize . ' bytes)' . PHP_EOL;
}

녹취 파일 다운로드 (유료 B타입 전용)

주의사항

동일 계정으로 동시 또는 연속 다운로드 시 실패하거나 차단될 수 있습니다.

반드시 1개 완료 후 수 초 간격을 두고 다음 파일을 요청하십시오.

반환값이 null이면 isSuccess() / getApiError()로 오류를 확인하십시오.

$binary = $lgu->downloadRecording('0854-010XXXX9087_20190813134606_mix.wav');

if ($binary !== null) {
    file_put_contents('recording.wav', $binary);
} else {
    echo $lgu->getApiError();
}

녹취 파일 삭제

$lgu->deleteRecording('0854-010XXXX9087_20190813134606_mix.wav');

통화 이력

$lgu->callHistory(1, 'outbound'); // 'inbound' | 'outbound'
$histories = $lgu->getCallHistories(); // CallHistory[]

외부인입 수신 통화이력

$lgu->getInboundCall(1, 10);
$calls = $lgu->getInboundCalls(); // InboundCall[]

foreach ($calls as $call) {
    echo $call->src . ' → ' . $call->dst;
    echo $call->isAnswered() ? ' (수신)' : ' (부재중)';
    echo PHP_EOL;
}

SMS

발송

발송 제한

수신자 최대 10개

SMS: 80 Byte 이내 (초과 시 LMS 처리)

LMS: 720 Byte 이내

잔여 건수가 0이면 발송 불가 (SmsResult::$restCount 확인)

// 단일 수신자
$lgu->smsSend('010-9999-8888', '안녕하세요!');
$result = $lgu->getSmsResult(); // SmsResult

echo '잔여 건수: ' . $result->restCount;

// 복수 수신자 (최대 10개)
$lgu->smsSend(['010-1111-2222', '010-3333-4444'], '공지사항입니다.');

수신 문자 목록 조회

$lgu->getRecvSmsList(1);
$messages = $lgu->getReceivedSmsMessages(); // ReceivedSms[]

foreach ($messages as $sms) {
    echo $sms->src . ': ' . $sms->message . PHP_EOL;
}

착신전환

// 착신전환 설정
$lgu->setForward('070-1111-2222');

// 착신전환 해제
$lgu->stopForward();

// 착신전환 유형별 설정
$lgu->setForwardType('070-1111-2222', LGUPlus::FORWARD_TYPE_NO_ANSWER);

// 설정 조회
$lgu->getForwardType();
$info = $lgu->getForwardTypeInfo(); // ForwardTypeInfo
echo $info->isActive() ? '착신전환 활성' : '비활성';

착신전환 유형 상수:

상수	값	설명
`FORWARD_TYPE_ALWAYS`	`'0'`	무조건
`FORWARD_TYPE_NO_ANSWER`	`'1'`	받지 않을 경우
`FORWARD_TYPE_BUSY`	`'2'`	통화 중일 경우
`FORWARD_TYPE_SIMULTANEOUS`	`'3'`	동시 연결
`FORWARD_TYPE_BUSY_OR_NO_ANSWER`	`'4'`	통화 중 또는 무응답 시

상태 조회

// 사용자 정보
$lgu->userInfo();
$user = $lgu->getUserInfo(); // UserInfo
echo $user->name . ' (' . $user->exten . ')';

// 폰 상태
$lgu->phoneStatus();
echo $lgu->isSuccess() ? '정상' : '오프라인';

// 통화 채널 상태
$lgu->channelStatus();
$status = $lgu->getChannelStatus(); // ChannelStatus

웹훅 (URL 알림)

주의사항

https 미지원, http만 가능합니다.

callbackurl의 경로에는 반드시 확장자 포함 필요 (예: /call.php, /sms.php)

실제 HTTP 호출은 callbackurl의 호스트명이 아닌 callbackhost IP로 직접 수행됩니다.

웹훅은 GET 방식으로 전달됩니다. WebhookPayload::fromGet($_GET)으로 수신하십시오.

등록은 계정당 하나만 유지됩니다. 재등록 시 기존 설정이 덮어쓰여집니다.

전화 수신 웹훅

// 등록
$lgu->registerCallWebhook('http://example.com/call.php', '10.10.10.2', '80');

// 조회
$lgu->getRingCallback();
$info = $lgu->getRingCallbackResult(); // RingCallbackResult

// 삭제
$lgu->deleteRingCallback();

SMS 수신 웹훅

// 등록
$lgu->registerSmsWebhook('http://example.com/sms.php', '10.10.10.2', '80');

// 조회
$lgu->getSmsCallback();

// 삭제
$lgu->deleteSmsCallback();

웹훅 수신 처리

use LGUPlus\Centrex\Models\WebhookPayload;

// GET 파라미터로 수신
$payload = WebhookPayload::fromGet($_GET);

if ($payload->isCall()) {
    echo '전화 수신: ' . $payload->sender . ' → ' . $payload->receiver;
} elseif ($payload->isSms()) {
    echo 'SMS 수신: ' . $payload->message;
}

비밀번호 관리

비밀번호 규칙 (변경/초기화 모두 동일)

문자 + 숫자 + 특수문자 혼합 필수 (동일 문자 연속 불가)

8~10자리

허용 특수문자 (14종): ~ ! @ $ % ^ * ( ) - _ , . ?

이전 3회 사용한 비밀번호 재사용 불가

changePassword() / resetPassword()에 전달하는 비밀번호는 평문으로 전달합니다 (라이브러리가 SHA-512 처리하지 않음 — 서버에서 직접 처리)

비밀번호 변경

$lgu->changePassword('새비밀번호');

비밀번호 유효기간 연장

$lgu->extendPasswordExpiry();

비밀번호 초기화 (인증코드 방식)

IP폰 단말기 사전 등록 필요 (LG U+에 신청)

인증코드는 등록된 IP폰으로 전송되며 6자리, SESSIONID는 5분간 유효

인증코드는 1회만 사용 가능 (재사용 시 오류코드 1203)

// 1단계: 인증코드 요청
$lgu->getAuthCode();
$authResult = $lgu->getAuthCodeResult(); // AuthCodeResult
// $authResult->sessionId — 2단계에서 사용 (5분 이내)
// $authResult->tryCnt   — 남은 인증 시도 횟수

// 2단계: 인증코드로 비밀번호 재설정
$lgu->resetPassword($authResult->sessionId, '새비밀번호', '인증코드6자리');
$resetResult = $lgu->getPasswordResetResult(); // PasswordResetResult

주요 오류 코드

코드	설명
`0000`	성공
`1001`	필수 파라미터 누락
`1002`	파라미터 형식 오류
`1003`	인증 오류 (id/pass 불일치)
`1004`	비밀번호 오류 횟수 초과
`1007`	초기 비밀번호 변경 필요
`1008`	비밀번호 만료 (변경 또는 연장 필요)
`1202`	비밀번호 변경 한도 초과
`1203`	인증코드 이미 사용됨
`1204`	인증코드 오류 또는 만료
`2001`	등록되지 않은 IP
`2002`	사용 권한 없음
`3001`	명령 처리 오류
`3002`	메시지 길이 초과
`3003`	수신자 수 초과
`3004`	SMS 잔여 건수 없음
`4002`	조회 데이터 없음
`4004`	통화 채널 없음
`9999`	기타 오류

전체 오류 설명은 ErrorCode::describe($code)로 확인할 수 있습니다.

use LGUPlus\Centrex\Models\ErrorCode;

echo ErrorCode::describe('1008'); // '비밀번호가 만료되었습니다'

API 응답 메서드 요약

메서드	반환 타입	설명
`isSuccess()`	`bool`	성공 여부 (`SVC_RT === '0000'`)
`getApiError()`	`?ApiError`	오류 정보, 성공 시 `null`
`getContacts()`	`Contact[]`	주소록 목록
`getPaginationInfo()`	`?ListInfo`	페이지 정보
`getRecordings()`	`Recording[]`	녹취 목록
`getCallHistories()`	`CallHistory[]`	통화 이력 목록
`getInboundCalls()`	`InboundCall[]`	외부인입 수신 이력
`getSmsResult()`	`?SmsResult`	SMS 발송 결과
`getReceivedSmsMessages()`	`ReceivedSms[]`	수신 문자 목록
`getUserInfo()`	`?UserInfo`	사용자 정보
`getChannelStatus()`	`?ChannelStatus`	통화 채널 상태
`getRingCallbackResult()`	`?RingCallbackResult`	URL 알림 설정 정보
`getForwardTypeInfo()`	`?ForwardTypeInfo`	착신전환 유형별 설정 정보
`getAuthCodeResult()`	`?AuthCodeResult`	인증코드 요청 결과
`getPasswordResetResult()`	`?PasswordResetResult`	비밀번호 재설정 결과

일반 주의사항

모든 API 호출은 동기(synchronous) 방식입니다. 대량 처리 시 적절한 딜레이를 두십시오.
API 서버(centrex.uplus.co.kr)에 대한 접근은 허용된 IP에서만 가능합니다 (오류코드 2001).
동일 id/pass로 동시 다중 호출을 자제하십시오 — 특히 녹취 다운로드.
응답 후 반드시 isSuccess()를 확인하십시오. API가 HTTP 200을 반환해도 처리 실패일 수 있습니다.
비밀번호 오류가 반복되면 계정이 잠길 수 있습니다 (오류코드 1004).

예외 처리

cURL 통신 오류 발생 시 LGUPlusException이 던져집니다.

try {
    $lgu->call('010-1234-5678');
} catch (LGUPlusException $e) {
    echo '통신 오류: ' . $e->getMessage();
}

라이선스

MIT

knifelemon / lguplus-centrex-restapi

Maintainers

Package info

Statistics

Security

README

요구 사항

설치

초기화

통화 제어

전화 걸기

전화 끊기

녹취

통화 보류

다자간 통화

주소록

녹취 목록

녹취 파일 다운로드 (유료 B타입 전용)

녹취 파일 삭제

통화 이력

외부인입 수신 통화이력

SMS

발송

수신 문자 목록 조회

착신전환

상태 조회

웹훅 (URL 알림)

전화 수신 웹훅

SMS 수신 웹훅

웹훅 수신 처리

비밀번호 관리

비밀번호 변경

비밀번호 유효기간 연장

비밀번호 초기화 (인증코드 방식)

주요 오류 코드

API 응답 메서드 요약

일반 주의사항

예외 처리

라이선스