REST API v2

개요

이것이 AI 에이전트가 구동하는 인터페이스입니다. 모든 호출은 action으로 고른 하나의 동사이므로, 에이전트는 카탈로그를 검색하고, 단가와 한도를 되읽은 뒤, 실행합니다. 검색 후 실행이며, 돈이 움직이기 전에 가격이 확인됩니다. MCP 서버와 CLI가 바로 이 호출들을 감싸며, 이 페이지는 그 아래의 원시 프로토콜입니다.

이 API는 널리 채택된 SMM API v2 형식을 따르므로, 기존 패널 소프트웨어, 스크립트, 에이전트 연동이 최소한의 변경으로 작동합니다. 모든 작업은 단일 엔드포인트를 거치며 action 파라미터로 동사를 고릅니다. 응답은 JSON입니다. 스크립트나 LLM이 파싱하고 연결하기 쉽습니다.

엔드포인트

POST https://api.socialgo.com/api/v2

인증

인증은 요청마다 이루어지며, 세션도 핸드셰이크도 없습니다. 바로 그 점이 에이전트가 호출할 수 있게 만듭니다. 모든 호출에 여러분의 비밀 key를 보내세요. 대시보드의 계정 → API에서 찾고 회전할 수 있습니다. 키는 비밀번호처럼 다루세요. 서버 측에 두고, 클라이언트 코드나 에이전트 프롬프트에는 절대 넣지 마세요.

요청 형식

application/x-www-form-urlencoded 폼 파라미터를 POST로 보내세요. 모든 응답은 JSON입니다. 두 파라미터는 모든 호출에 들어갑니다:

• key: 여러분의 API 키 (필수)
• action: 실행할 동사 (필수)

오류 형식

실패 시 응답에는 사람이 읽을 수 있는 메시지가 담긴 error 필드가 포함되고, HTTP 상태가 문제를 반영합니다(예: 400 잘못된 요청, 401 유효하지 않은 키). 예측 가능한 하나의 형태이므로 스크립트나 에이전트가 추측 없이 분기할 수 있습니다.

{
  "error": "Incorrect request"
}

액션

각 동사는 한 가지 일을 합니다. 에이전트는 순서대로 연결합니다. 무엇을 살지 찾는 services, 그것을 사는 add, 추적하는 status. 읽기 호출(services, status, balance)로 가격과 자금을 확인한 뒤, 쓰기 호출(add, refill, cancel)이 무언가를 지출합니다.

1. 서비스 목록

에이전트가 가장 먼저 읽는 카탈로그입니다. 주문할 수 있는 모든 서비스와 서비스 ID, 카테고리, 단가(1000개당 가격), 최소/최대 수량이 담깁니다. 반환된 service ID로 주문을 넣고, 단가로 쓰기 전에 비용을 확인합니다.

요청

key=YOUR_API_KEY
action=services

응답

[
  {
    "service": 1,
    "name": "Instagram Followers",
    "type": "Default",
    "category": "Instagram",
    "rate": "0.90",
    "min": "50",
    "max": "10000",
    "refill": true,
    "cancel": true
  },
  {
    "service": 2,
    "name": "Instagram Likes",
    "type": "Default",
    "category": "Instagram",
    "rate": "0.40",
    "min": "10",
    "max": "20000",
    "refill": false,
    "cancel": true
  }
]

2. 주문 추가

쓰기 호출입니다. 한 서비스에 대한 주문을 넣습니다. service ID, 대상 link, quantity를 전달하세요. 응답은 추적할 새 order ID를 반환합니다. 에이전트는 단가와 한도를 확인한 뒤에만 이것을 실행합니다.

파라미터

• service: 서비스 목록의 서비스 ID
• link: 게시물 / 프로필 / 채널의 URL
• quantity: 전달할 단위 수

요청

key=YOUR_API_KEY
action=add
service=1
link=https://instagram.com/example
quantity=1000

응답

{
  "order": 23501
}

3. 주문 추가, 드립피드

더 완만한 곡선을 위해 하나의 주문을 시간에 걸쳐 나뉜 여러 전달로 분할합니다. runs(전달 횟수)와 interval(각 전달 사이 분)을 설정하세요. 총 전달량은 quantity × runs입니다. 여러분이 손으로 하지 않아도 에이전트가 캠페인 규모를 잡는 데 쓰는 계산입니다.

추가 파라미터

• runs: 전달 실행 횟수
• interval: 각 실행 사이의 분

요청

key=YOUR_API_KEY
action=add
service=1
link=https://instagram.com/example
quantity=1000
runs=10
interval=60

응답

{
  "order": 23502
}

4. 주문 상태

한 주문의 현재 상태를 반환합니다: 청구액, 시작 수치, 상태, 남은 수량, 통화. 여러분이 대시보드를 새로고침하지 않아도 에이전트가 주문을 지켜보고, 리필로 표시할 만한 감소를 포착하는 방식입니다.

요청

key=YOUR_API_KEY
action=status
order=23501

응답

{
  "charge": "0.90",
  "start_count": "4250",
  "status": "In progress",
  "remains": "200",
  "currency": "USD"
}

가능한 status 값: Pending, In progress, Processing, Completed, Partial, Canceled.

5. 다중 주문 상태

한 번의 호출로 여러 주문을 확인합니다. orders 파라미터에 쉼표로 구분한 ID 목록을 전달하세요. 응답은 주문 ID를 키로 하므로, 에이전트가 주문마다 한 번씩 호출하는 대신 한 번의 왕복으로 캠페인 전체를 폴링합니다.

요청

key=YOUR_API_KEY
action=status
orders=23501,23502,23503

응답

{
  "23501": {
    "charge": "0.90",
    "start_count": "4250",
    "status": "Completed",
    "remains": "0",
    "currency": "USD"
  },
  "23502": {
    "charge": "9.00",
    "start_count": "1200",
    "status": "In progress",
    "remains": "500",
    "currency": "USD"
  },
  "23503": {
    "error": "Incorrect order ID"
  }
}

6. 리필

서비스가 리필을 지원하는(서비스 목록에서 refill: true) 주문에 리필을 요청하고, 추적할 리필 ID를 반환합니다. 단일 order나 쉼표로 구분한 orders 목록을 전달하세요. 상태 확인이 감소를 표시한 뒤 에이전트가 대량으로 리필을 요청할 수 있습니다.

요청 (단일)

key=YOUR_API_KEY
action=refill
order=23501

응답

{
  "refill": 4001
}

요청 (다중)

key=YOUR_API_KEY
action=refill
orders=23501,23502

응답

[
  { "order": 23501, "refill": 4001 },
  { "order": 23502, "refill": { "error": "Refill not available" } }
]

7. 취소

아직 처리되지 않은 주문(서비스에 cancel: true)의 취소를 요청합니다. 쉼표로 구분한 orders 목록을 전달하면 응답이 주문별 결과를 알려줍니다. 무언가 실수로 대기열에 올랐을 때 에이전트가 찾는 되돌리기입니다.

요청

key=YOUR_API_KEY
action=cancel
orders=23501,23502

응답

[
  { "order": 23501, "cancel": 1 },
  { "order": 23502, "cancel": { "error": "Incorrect order ID" } }
]

8. 잔액

계정 잔액과 통화를 반환합니다. 에이전트는 주문을 넣기 전에 지출을 통제하기 위해 이를 읽고, 여러분의 패널은 자금을 표시하기 위해 이를 읽습니다. 쓸 돈이 있는지 확인하는 가장 저렴한 호출입니다.

요청

key=YOUR_API_KEY
action=balance

응답

{
  "balance": "182.45",
  "currency": "USD"
}

무엇에서든 호출하세요

하나의 엔드포인트, 단순한 폼 파라미터. 그래서 셸, cron 작업, 에이전트가 같은 방식으로 구동할 수 있습니다. 커맨드 라인에서 넣은 완전한 주문의 예입니다:

curl -X POST https://api.socialgo.com/api/v2 \
  -d "key=YOUR_API_KEY" \
  -d "action=add" \
  -d "service=1" \
  -d "link=https://instagram.com/example" \
  -d "quantity=1000"

참고 사항 및 모범 사례

• 쓰기 전에 읽으세요. services(또는 balance)를 호출해 단가, 한도, 자금을 확인한 뒤 add를 호출하세요. 대시보드와 MCP 서버가 쓰는 것과 동일한 검색 후 실행 가드레일이므로, 확인된 가격 없이는 아무것도 지출되지 않습니다.
• 서비스 목록을 캐시하고 주기적으로 새로고침하세요. ID, 단가, 한도는 바뀝니다.
• 거부되는 호출을 피하려면 주문을 제출하기 전에 min/max 수량을 검증하세요.
• 주문마다 한 번씩 요청하는 대신 다중 주문 호출로 상태를 일괄 폴링하세요.
• 키를 서버 측에 두세요. 노출되면 대시보드에서 즉시 회전하세요.