Apinoa Docs

Feedback API

실패한 호출, 틀리거나 빠진 데이터를 알리고, 없는 API를 요청합니다. 무료이며 API 키가 없어도 됩니다. 답변은 리포트 id로 확인합니다.

원본 .mdx 보기
POST /v1/feedback
GET  /v1/feedback/{id}

호출이 실패했을 때, 값이 틀렸을 때, 페이지에 있는 내용이 응답에 빠졌을 때, 또는 필요한 플랫폼·오퍼레이션·옵션이 없을 때 알려 주세요. 무료이며 API 키 없이도 보낼 수 있어서, AI 에이전트가 문제를 만난 순간 바로 보낼 수 있습니다. 키를 함께 보내면 리포트가 계정에 연결되어, requestId로 지정한 그 호출을 저희가 직접 확인할 수 있습니다.

모든 리포트에는 id가 붙습니다. 상태와 답변은 GET /v1/feedback/{id}에서 확인할 수 있고, contact에 이메일 주소를 주거나 키를 함께 보내면 답변이 이메일로도 갑니다.

피드백 보내기

curl -X POST "https://gateway.apinoa.com/v1/feedback" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "wrong_data",
    "message": "price is the list price, not the sale price shown on the page",
    "platform": "amazon",
    "operation": "product",
    "params": { "asin": "B0CX23V2ZK" },
    "requestId": "43d899616f8e468aa22368bffaae1953",
    "received": "\"price\": { \"amount\": 29.99 }",
    "expected": "24.99",
    "contact": "dev@example.com"
  }'

파라미터

헤더

헤더필수설명
Content-Typeapplication/json.
x-api-key리포트를 계정에 연결할 API 키. 빼면 익명으로 보냅니다. 보낸 키는 유효해야 합니다.

본문: 최대 64 KB의 JSON 객체.

필드타입필수설명
typestring예아래 타입 중 하나.
messagestring예무슨 일이 있었는지, 무엇이 필요한지 직접 적은 내용. 최대 4,000자.
platformstring경로에 쓰는 플랫폼 이름: amazon, tiktok, google…
operationstring경로에 쓰는 오퍼레이션 이름: search, product, posts…
paramsobject호출에 보낸 파라미터. 최대 8 KB.
requestIdstring알리려는 응답의 requestId. 키와 함께 보내면 저희가 그 호출을 확인할 수 있습니다.
urlstring올바른 데이터가 보이는 페이지, 또는 리포트 대상 항목.
receivedany응답에서 틀린 부분. 텍스트로, 또는 받은 JSON 값 그대로. 최대 16 KB.
expectedany원래 나와야 했던 값. 텍스트 또는 JSON 값. 최대 4,000자.
contactstring답변을 받을 이메일 주소.
sourcestring보낸 주체, 예를 들어 에이전트나 앱 이름. 최대 32자.
type이럴 때함께 보낼 것
error호출이 실패했거나 잘못 동작했을 때.platform, operation, params, requestId, 그리고 받은 오류를 received에.
wrong_data필드 값이 틀렸을 때.위와 같고, expected 또는 올바른 값이 보이는 url.
missing_data페이지에 보이는 내용이 응답에 없을 때.위와 같고, 그 페이지의 url.
feature_request없는 플랫폼, 오퍼레이션, 필드, 옵션이 필요할 때.어떻게 호출하고 무엇을 받고 싶은지 message에.
other그 밖의 모든 것.

응답

새 리포트는 201 Created로 답합니다:

{
  "success": true,
  "data": {
    "id": "fb_6f1c2a9e0b4d4e7f8a3b5c1d2e9f0a7b",
    "status": "received",
    "createdAt": "2026-11-11T10:00:00Z"
  }
}

같은 키로(키가 없으면 같은 발신자에게서) 같은 type과 message를 하루 안에 다시 보내면, 새로 만들지 않고 처음 리포트를 200 OK로 돌려줍니다.

상태와 답변 확인

curl "https://gateway.apinoa.com/v1/feedback/fb_6f1c2a9e0b4d4e7f8a3b5c1d2e9f0a7b"

키는 필요 없습니다. id만 있으면 됩니다. 보낸 내용은 돌려주지 않고, 저희 쪽 상태와 답변만 돌려줍니다:

{
  "success": true,
  "data": {
    "id": "fb_6f1c2a9e0b4d4e7f8a3b5c1d2e9f0a7b",
    "type": "wrong_data",
    "status": "resolved",
    "reply": "Fixed: product now returns the sale price. Retry the call.",
    "repliedAt": "2026-11-12T08:30:00Z",
    "createdAt": "2026-11-11T10:00:00Z",
    "updatedAt": "2026-11-12T08:30:00Z"
  }
}
필드타입의미
statusstringreceived, 작업 중에는 in_progress, 이후 resolved 또는 declined.
replystring | null저희 답변. 답하기 전에는 null.
repliedAtstring | null답한 시각.
createdAt, updatedAtstring리포트가 도착한 시각과 마지막으로 바뀐 시각.

SDK와 MCP

  • TypeScript: client.feedback.send({ type, message, ... })와 client.feedback.get({ id }). 키 없이 보내려면 new ApinoaClient({ auth: false })로 클라이언트를 만드세요.
  • Python: client.feedback.send(type=..., message=..., request_id=...)와 client.feedback.get(id).
  • MCP: send_feedback와 get_feedback 도구. 키 없이도 동작합니다.

오류

상태코드의미
400BAD_REQUEST본문이 type과 message가 있는 JSON 객체가 아니거나, 필드가 잘못됐습니다. 메시지가 그 필드를 알려 줍니다.
401UNAUTHORIZEDx-api-key를 보냈지만 키가 유효하지 않거나 폐기됐습니다. 키 없이 보내려면 헤더를 빼세요.
404NOT_FOUND이 id의 피드백이 없습니다.
413PAYLOAD_TOO_LARGE본문이 64 KB를 넘습니다.
429RATE_LIMITED한 발신자의 리포트가 너무 많습니다. Retry-After초만큼 기다리세요.
503SERVICE_UNAVAILABLE지금은 리포트를 저장하지 못했습니다. 잠시 후 다시 보내세요.

한도와 가격

  • 무료. 키가 있든 없든 피드백은 과금되지 않습니다.
  • 빈도. 키 없이는 한 발신자당 시간당 10건, 하루 50건, 키가 있으면 키당 시간당 30건입니다. 키 없이는 몰리는 시간대에 429가 더 일찍 올 수 있고, 키와 함께 보낸 리포트는 영향을 받지 않습니다.
  • 보관하는 것. 리포트와, 주신 경우 이메일 주소는 답변하고 문제를 고치기 위해 보관합니다. 개인정보처리방침을 참고하세요.

이 페이지 내용