{"openapi":"3.1.0","info":{"title":"LinkFarm Brand API","summary":"브랜드 쇼핑몰 → 링크팜 전환 트래킹","description":"브랜드 쇼핑몰이 주문·환불을 전송해 크리에이터 커미션을 정산받는 공개 API 입니다. 엔드포인트는 `POST /v1/events` 하나이고, `order.paid` 는 `order_id` 기준 멱등 upsert 라 어제 주문 전량을 다시 보내는 방식으로 누락을 복구할 수 있습니다.\n\n에이전트용 전체 가이드: https://openapi.linkfarm.ai/llms-full.txt","version":"v1"},"servers":[{"url":"https://openapi.linkfarm.ai"}],"paths":{"/v1/ping":{"get":{"tags":["Brand API v1"],"summary":"키 검증","description":"첫 호출로 쓰세요 — 키가 유효한지, 어느 브랜드·어느 모드인지 알려줍니다.","operationId":"ping_v1_ping_get","parameters":[{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}},{"name":"origin","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Origin"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PingOut"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/integration/status":{"get":{"tags":["Brand API v1"],"summary":"연동 상태(최근 24시간)","operationId":"integration_status_v1_integration_status_get","parameters":[{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}},{"name":"origin","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Origin"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntegrationStatusOut"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/orders/{order_id}":{"get":{"tags":["Brand API v1"],"summary":"주문 상태 조회","operationId":"get_order_v1_orders__order_id__get","parameters":[{"name":"order_id","in":"path","required":true,"schema":{"type":"string","title":"Order Id"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}},{"name":"origin","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Origin"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderOut"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/orders":{"get":{"tags":["Brand API v1"],"summary":"주문 목록(대사용)","description":"우리 쪽 뷰를 그대로 돌려준다 — 브랜드가 자기 원장과 대조할 수 있게.\n\n`(occurred_at, id)` 안정 커서로 페이지를 넘긴다. 최신 N건만 주면 주문이\n500건을 넘는 브랜드는 전수 대사가 불가능하다.","operationId":"list_orders_v1_orders_get","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":100,"title":"Limit"}},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cursor"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}},{"name":"origin","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Origin"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderListOut"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/events":{"post":{"tags":["Brand API v1"],"summary":"이벤트 전송","description":"주문·환불·취소·확정과 브라우저 이벤트를 이 엔드포인트 하나로 보냅니다.\n\n`order.paid` 는 멱등 upsert 입니다 — 같은 `order_id` 를 다시 보내도 원장이\n두 번 생기지 않으므로, 매일 밤 어제 주문을 통째로 재전송하는 방식으로\n누락을 복구할 수 있습니다.","operationId":"create_event_v1_events_post","parameters":[{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}},{"name":"origin","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Origin"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventIn"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventOut"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/events/batch":{"post":{"tags":["Brand API v1"],"summary":"이벤트 일괄 전송(대사용)","description":"최대 500건. 자체몰의 야간 대사(어제 주문 전량 재전송)에 씁니다.\n\n이벤트는 순서대로 개별 커밋됩니다. 중간에 실패하면 **그 앞까지는 반영된\n채로** 에러가 반환되며, `error.param` 이 `events[i].…` 형태로 실패한\n이벤트의 인덱스를 가리킵니다. `order.paid` 가 멱등 upsert 이므로 실패\n지점부터(또는 통째로) 재전송하면 안전하게 이어집니다.","operationId":"create_events_batch_v1_events_batch_post","parameters":[{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}},{"name":"origin","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Origin"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchIn"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/EventOut"},"title":"Response Create Events Batch V1 Events Batch Post"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"AttributionOut":{"properties":{"status":{"type":"string","title":"Status"},"via":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Via"}},"type":"object","required":["status"],"title":"AttributionOut"},"BatchIn":{"properties":{"events":{"items":{"$ref":"#/components/schemas/EventIn"},"type":"array","maxItems":500,"minItems":1,"title":"Events"}},"additionalProperties":false,"type":"object","required":["events"],"title":"BatchIn"},"EventData":{"properties":{"order_id":{"anyOf":[{"type":"string","maxLength":120},{"type":"null"}],"title":"Order Id","description":"쇼핑몰의 주문번호. 브랜드 안에서 유일해야 합니다(멱등 키)."},"amount":{"anyOf":[{"type":"integer","maximum":2147483647.0,"minimum":0.0},{"type":"null"}],"title":"Amount","description":"할인 적용 후 소비자가 실제 부담한 **커미션 대상** 상품 금액. 배송비·포인트 충전·상품권·비대상 상품 제외. 한 주문에 제휴 대상과 비대상이 섞이면 대상분만 보내세요. currency 의 최소단위(KRW=원, USD=센트)."},"currency":{"anyOf":[{"type":"string","maxLength":3,"minLength":3},{"type":"null"}],"title":"Currency","description":"ISO 4217. 생략하면 KRW. 지원: KRW·USD·JPY·EUR·GBP."},"fx_rate":{"anyOf":[{"type":"number","maximum":100000.0,"exclusiveMinimum":0.0},{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$"},{"type":"null"}],"title":"Fx Rate","description":"1 통화단위당 KRW 환율. KRW 가 아니면 필수. 주문에 고정되어 이후 환불도 같은 환율로 계산됩니다."},"click_ref":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}],"title":"Click Ref","description":"랜딩 URL 의 `lf_click` 값. 자사 도메인 쿠키에 저장했다가 보냅니다."},"coupon_code":{"anyOf":[{"type":"string","maxLength":40},{"type":"null"}],"title":"Coupon Code","description":"크리에이터 할인코드. click_ref 와 둘 다 있으면 **코드가 우선**합니다."},"parent_order_id":{"anyOf":[{"type":"string","maxLength":120},{"type":"null"}],"title":"Parent Order Id","description":"구독 갱신 결제일 때 최초 결제의 order_id. 귀속을 상속하고 회차가 자동 계산됩니다."},"refund_id":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}],"title":"Refund Id","description":"환불 식별자. 한 주문에 환불이 여러 번 들어올 수 있어 필요하고, 같은 값 재전송은 멱등입니다."},"reason":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"Reason","description":"환불·취소 사유(자유 텍스트)."},"last_touch_channel":{"anyOf":[{"type":"string","maxLength":32},{"type":"null"}],"title":"Last Touch Channel","description":"마지막 유입 채널. 어필리에이트가 last-click 이 아니면 다른 값을 보내 중복 계상을 피할 수 있습니다(Awin `ch` 상당)."},"customer_hash":{"anyOf":[{"type":"string","maxLength":64,"minLength":32,"pattern":"^[0-9a-fA-F]{32,64}$"},{"type":"null"}],"title":"Customer Hash","description":"구매자 식별자의 **16진 해시**(sha256 권장, 32~64자). 자기구매 판정에만 씁니다. **원문 PII 는 받지 않습니다** — 이메일·전화·이름을 넣으면 422 로 거절됩니다."},"items":{"anyOf":[{"items":{"$ref":"#/components/schemas/OrderItem"},"type":"array"},{"type":"null"}],"title":"Items","description":"주문 라인아이템(선택). 상품별 분석에 쓰입니다."}},"additionalProperties":false,"type":"object","title":"EventData"},"EventIn":{"properties":{"type":{"type":"string","maxLength":40,"title":"Type"},"occurred_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Occurred At"},"data":{"$ref":"#/components/schemas/EventData"}},"additionalProperties":false,"type":"object","required":["type"],"title":"EventIn"},"EventOut":{"properties":{"id":{"type":"string","title":"Id"},"object":{"type":"string","title":"Object","default":"event"},"type":{"type":"string","title":"Type"},"livemode":{"type":"boolean","title":"Livemode"},"status":{"type":"string","title":"Status"},"attribution":{"$ref":"#/components/schemas/AttributionOut"},"conversion_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Conversion Id"},"request_id":{"type":"string","title":"Request Id"}},"type":"object","required":["id","type","livemode","status","attribution","request_id"],"title":"EventOut"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"IntegrationStatusOut":{"properties":{"object":{"type":"string","title":"Object","default":"integration_status"},"livemode":{"type":"boolean","title":"Livemode"},"platform":{"type":"string","title":"Platform"},"clicks_24h":{"type":"integer","title":"Clicks 24H"},"orders_24h":{"type":"integer","title":"Orders 24H"},"unattributed_24h":{"type":"integer","title":"Unattributed 24H"},"last_event_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Event At"},"last_error_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Error Code"},"consecutive_failures":{"type":"integer","title":"Consecutive Failures"}},"type":"object","required":["livemode","platform","clicks_24h","orders_24h","unattributed_24h","consecutive_failures"],"title":"IntegrationStatusOut"},"OrderItem":{"properties":{"sku":{"anyOf":[{"type":"string","maxLength":120},{"type":"null"}],"title":"Sku"},"name":{"anyOf":[{"type":"string","maxLength":300},{"type":"null"}],"title":"Name"},"quantity":{"anyOf":[{"type":"integer","maximum":2147483647.0,"minimum":0.0},{"type":"null"}],"title":"Quantity","description":"구매 수량."},"amount":{"anyOf":[{"type":"integer","maximum":2147483647.0,"minimum":0.0},{"type":"null"}],"title":"Amount","description":"이 라인아이템의 커미션 대상 금액(주문 currency 최소단위)."}},"additionalProperties":false,"type":"object","title":"OrderItem"},"OrderListOut":{"properties":{"object":{"type":"string","title":"Object","default":"list"},"data":{"items":{"$ref":"#/components/schemas/OrderOut"},"type":"array","title":"Data"},"has_more":{"type":"boolean","title":"Has More","default":false},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor","description":"다음 페이지 커서. 그대로 `?cursor=` 에 넣어 이어서 조회하세요. null 이면 마지막 페이지입니다."}},"type":"object","required":["data"],"title":"OrderListOut","description":"대사용 목록. 500건 넘는 브랜드도 전수 조회가 가능해야 한다."},"OrderOut":{"properties":{"object":{"type":"string","title":"Object","default":"order"},"order_id":{"type":"string","title":"Order Id"},"livemode":{"type":"boolean","title":"Livemode"},"status":{"type":"string","title":"Status"},"amount":{"type":"integer","title":"Amount"},"currency":{"type":"string","title":"Currency"},"original_amount":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Original Amount"},"original_currency":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Original Currency"},"fx_rate":{"anyOf":[{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$"},{"type":"null"}],"title":"Fx Rate"},"commission_amount":{"type":"integer","title":"Commission Amount"},"refunded_amount":{"type":"integer","title":"Refunded Amount"},"refunded_commission_amount":{"type":"integer","title":"Refunded Commission Amount"},"remaining_amount":{"type":"integer","title":"Remaining Amount"},"attributed":{"type":"boolean","title":"Attributed"},"attributed_via":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Attributed Via"},"parent_order_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Parent Order Id"},"occurred_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Occurred At"},"confirm_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Confirm At"}},"type":"object","required":["order_id","livemode","status","amount","currency","commission_amount","refunded_amount","refunded_commission_amount","remaining_amount","attributed"],"title":"OrderOut","description":"우리가 인식한 주문 상태 — 브랜드(와 그 에이전트)가 자기 통합을 검증한다."},"PingOut":{"properties":{"object":{"type":"string","title":"Object","default":"ping"},"ok":{"type":"boolean","title":"Ok","default":true},"brand":{"type":"string","title":"Brand"},"brand_id":{"type":"string","title":"Brand Id"},"livemode":{"type":"boolean","title":"Livemode"},"key_type":{"type":"string","title":"Key Type"},"api_version":{"type":"string","title":"Api Version","default":"v1"}},"type":"object","required":["brand","brand_id","livemode","key_type"],"title":"PingOut"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}},"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","description":"`sk_live_…`/`sk_test_…`(서버) 또는 `pk_live_…`/`pk_test_…`(브라우저). publishable 키로는 주문·환불을 보낼 수 없습니다."}}},"security":[{"ApiKey":[]}]}