Aedu API

개요

Aedu 외부 API를 사용하면 총판에 속한 학원의 주문 정보를 외부 시스템(ERP, CRM 등)에서 조회할 수 있습니다.

기본 URL: https://api.aedu.co.kr

인증

모든 API 요청에는 API Key와 API Secret이 필요합니다. 두 가지 방식을 지원합니다.

방법 1: Authorization 헤더 (권장)

Authorization: Bearer {API_KEY}:{API_SECRET}

방법 2: 커스텀 헤더

X-API-Key: {API_KEY}
X-API-Secret: {API_SECRET}

예시 (cURL)

# 방법 1
curl -H "Authorization: Bearer aedu_abc123...:secret456..." \
     https://api.aedu.co.kr/api/external/orders.php

# 방법 2
curl -H "X-API-Key: aedu_abc123..." \
     -H "X-API-Secret: secret456..." \
     https://api.aedu.co.kr/api/external/orders.php

Rate Limit

API 키별로 분당 요청 수가 제한됩니다 (기본 100회/분). 응답 헤더에서 남은 횟수를 확인할 수 있습니다.

에러 처리

에러 발생 시 아래 형식으로 응답합니다.

{
  "success": false,
  "error": {
    "code": 401,
    "message": "유효하지 않은 API 키입니다."
  }
}

HTTP 상태 코드

주문 목록 조회

{
  "success": true,
  "data": {
    "items": [
      {
        "id": 1,
        "order_number": "ORD-20260318-0001",
        "academy": {
          "id": 1,
          "name": "테스트학원"
        },
        "product_name": "초등 영어 기본반",
        "member_name": "홍길동",
        "member_phone": "010-1234-5678",
        "amount": {
          "total": 50000,
          "discount": 5000,
          "shipping_fee": 3000,
          "payment": 48000
        },
        "payment": {
          "status": "paid",
          "method": "card",
          "paid_at": "2026-03-18 10:30:00"
        },
        "order_status": "shipped",
        "shipping": {
          "name": "홍길동",
          "phone": "010-1234-5678",
          "address": "서울시 마포구 연남로 71",
          "zipcode": "04001",
          "company": "CJ대한통운",
          "tracking_number": "1234567890",
          "shipped_at": "2026-03-18 14:00:00",
          "delivered_at": null
        },
        "created_at": "2026-03-18 09:00:00",
        "updated_at": "2026-03-18 14:00:00"
      }
    ],
    "pagination": {
      "total": 150,
      "page": 1,
      "limit": 20,
      "total_pages": 8
    }
  }
}

curl -H "Authorization: Bearer aedu_abc123:secret456" \
     "https://api.aedu.co.kr/api/external/orders.php?page=1&limit=10&payment_status=paid&date_start=2026-03-01"

주문 상세 조회

{
  "success": true,
  "data": {
    "id": 1,
    "order_number": "ORD-20260318-0001",
    "academy": { "id": 1, "name": "테스트학원" },
    "product_name": "초등 영어 기본반",
    "member": {
      "name": "홍길동",
      "phone": "010-1234-5678",
      "email": "hong@test.com"
    },
    "amount": {
      "total": 50000,
      "discount": 5000,
      "shipping_fee": 3000,
      "payment": 48000,
      "cancelled": 0
    },
    "payment": { "status": "paid", "method": "card", "paid_at": "2026-03-18 10:30:00" },
    "order_status": "shipped",
    "shipping": { /* ... 배송 정보 ... */ },
    "items": [
      {
        "id": 1,
        "type": "book",
        "name": "초등 영어 워크북 Level 1",
        "quantity": 2,
        "unit_price": 15000,
        "discount_amount": 2000,
        "total_price": 30000,
        "final_price": 28000,
        "status": "shipped"
      }
    ],
    "memo": null,
    "created_at": "2026-03-18 09:00:00",
    "updated_at": "2026-03-18 14:00:00"
  }
}

# ID로 조회
curl -H "Authorization: Bearer aedu_abc123:secret456" \
     "https://api.aedu.co.kr/api/external/orders-detail.php?id=1"

# 주문번호로 조회
curl -H "Authorization: Bearer aedu_abc123:secret456" \
     "https://api.aedu.co.kr/api/external/orders-detail.php?order_number=ORD-20260318-0001"

주문 통계

{
  "success": true,
  "data": {
    "summary": {
      "total_orders": 1500,
      "pending_count": 50,
      "paid_count": 1200,
      "refunded_count": 30,
      "cancelled_count": 220,
      "shipped_count": 1100,
      "delivered_count": 980,
      "total_payment_amount": 75000000,
      "paid_amount": 60000000
    },
    "trends": [
      {
        "period": "2026-03-18",
        "order_count": 45,
        "payment_amount": 2250000,
        "paid_count": 40
      }
    ],
    "by_academy": [
      {
        "academy_id": 1,
        "academy_name": "테스트학원",
        "order_count": 500,
        "payment_amount": 25000000
      }
    ]
  }
}

curl -H "Authorization: Bearer aedu_abc123:secret456" \
     "https://api.aedu.co.kr/api/external/orders-stats.php?date_start=2026-03-01&date_end=2026-03-31&group_by=day"

연동 예시 (Python)

import requests

API_KEY = "aedu_abc123..."
API_SECRET = "secret456..."
BASE_URL = "https://api.aedu.co.kr"

headers = {
    "Authorization": f"Bearer {API_KEY}:{API_SECRET}"
}

# 주문 목록 조회
response = requests.get(
    f"{BASE_URL}/api/external/orders.php",
    headers=headers,
    params={"payment_status": "paid", "limit": 50}
)

data = response.json()
if data["success"]:
    for order in data["data"]["items"]:
        print(f"주문 {order['order_number']}: {order['amount']['payment']}원")

연동 예시 (JavaScript / Node.js)

const API_KEY = 'aedu_abc123...';
const API_SECRET = 'secret456...';
const BASE_URL = 'https://api.aedu.co.kr';

const response = await fetch(
    `${BASE_URL}/api/external/orders.php?payment_status=paid&limit=50`,
    {
        headers: {
            'Authorization': `Bearer ${API_KEY}:${API_SECRET}`
        }
    }
);

const data = await response.json();
if (data.success) {
    data.data.items.forEach(order => {
        console.log(`주문 ${order.order_number}: ${order.amount.payment}원`);
    });
}

상태값 레퍼런스

결제 상태 (payment_status)

주문 상태 (order_status)

권한 (permissions)

데이터 범위