Facebook 페이지 발행

capabilities.publishPosts: true인 Facebook 페이지 연결을 사용합니다. 요청 하나는 페이지 1개를 대상으로 하며 posts·video·instagram·youtube 대신 자기완결적인 facebook 객체를 전달합니다.

GET /api/v1/accounts에서 페이지 accountId를 가져오세요. 발행·예약에는 정상 연결, pages_manage_posts scope, 페이지의 CREATE_CONTENT task가 모두 필요하며 Posteady의 공개 쓰기 rollout이 활성화되어야 합니다. capability는 탐색용 정보이며 Posteady는 매 요청마다 현재 플랜·워크스페이스 권한·rollout 상태·페이지 자격을 다시 검사합니다. rollout 전에는 신규 작업이 **503 SERVICE_UNAVAILABLE**을 반환하지만 기존 작업의 replay·상태 조회·취소는 계속 사용할 수 있습니다.

지원 콘텐츠

본문은 최대 63,206자이며 앞뒤 공백을 제거합니다. 이미지는 완료 확인된 최대 8 MiB JPEG여야 합니다. 영상은 완료 확인된 최대 1 GiB·20분 MP4 또는 QuickTime이어야 하며, Reels와 영상 Story에는 위의 더 짧은 제한도 적용됩니다. Posteady는 모든 mediaId가 페이지와 같은 워크스페이스에 있는지 확인하고 저장 객체와 미디어 메타데이터를 검증한 뒤 발행합니다.

미디어 선택 또는 업로드

완료 확인된 이미지나 영상을 조회합니다.

curl "https://www.posteady.com/api/v1/media?mediaType=IMAGE" \
  -H "Authorization: Bearer $POSTEADY_API_KEY"

새 미디어는 POST /api/v1/media/uploads로 업로드를 예약하고 반환된 비공개 staging URL에 모든 requiredHeaders와 함께 바이트를 PUT한 뒤 POST /api/v1/media/uploads/confirm으로 완료를 확인합니다. 반환된 mediaId만 사용하세요. Facebook 공개 발행 계약은 임의 공개 URL이나 호출자가 주장하는 미디어 메타데이터를 받지 않습니다.

즉시 발행

작업용 UUID를 한 번 만들고 같은 요청을 재시도할 때 유지합니다.

curl -X POST https://www.posteady.com/api/v1/posts \
  -H "Authorization: Bearer $POSTEADY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "accountIds": ["<facebook-page-account-uuid>"],
    "facebook": {
      "requestId": "<request-uuid>",
      "contentType": "FEED",
      "message": "새 버전을 출시했습니다",
      "items": [{ "mediaId": "<confirmed-image-uuid>" }]
    }
  }'

Facebook 발행은 항상 비동기입니다. 새 작업이나 진행 중 작업은 results[0].jobId와 함께 HTTP 202를 반환합니다. success: true는 접수됐다는 뜻이며 발행 완료가 아닙니다. published·failed·canceled·unknown 중 어느 terminal 상태든 동일 요청을 멱등 재조회하면 HTTP 200입니다. HTTP 200은 기존 작업을 조회했다는 뜻이지 게시 성공을 뜻하지 않습니다. failed·canceled·unknown에서는 success가 계속 false이므로 두 필드를 모두 확인하세요.

curl "https://www.posteady.com/api/v1/publish-jobs/<job-uuid>" \
  -H "Authorization: Bearer $POSTEADY_API_KEY"

native postId를 사용하려면 published를 기다리세요. unknown은 Meta 전송 결과를 확정하지 못한 상태입니다. Posteady는 자동으로 다시 전송하지 않으므로 새 요청을 만들기 전에 페이지를 확인하세요.

같은 requestId와 정규화된 입력은 기존 작업을 반환합니다. 페이지·콘텐츠 형식·본문·미디어 순서·예약 시각·시간대가 달라지면 **409 REQUEST_CONFLICT**입니다. 재조회도 현재 접근 권한을 검사하며 rate·quota·audit에서 API 호출 1회로 집계됩니다.

예약과 취소

같은 facebook 객체와 미래 시각을 POST /api/v1/scheduled-posts로 보냅니다.

{
  "accountIds": ["<facebook-page-account-uuid>"],
  "facebook": {
    "requestId": "<request-uuid>",
    "contentType": "STORY",
    "items": [{ "mediaId": "<confirmed-image-uuid>" }]
  },
  "scheduledAt": "<future-time-with-offset>",
  "timezone": "Asia/Seoul"
}

Facebook 예약 접수는 HTTP 202입니다. GET /api/v1/scheduled-posts?provider=facebook으로 목록을 보고 발행 시작 전에 취소합니다.

curl -X DELETE "https://www.posteady.com/api/v1/scheduled-posts/<scheduled-post-uuid>?platform=facebook" \
  -H "Authorization: Bearer $POSTEADY_API_KEY"

처리가 시작되면 POST_NOT_CANCELLABLE을 반환합니다. 즉시 발행 작업과 결과가 불명확한 unknown 작업은 예약 목록에 표시하지 않습니다.

게시물과 지표 조회

GET /api/v1/posts?provider=facebook을 호출합니다. Posteady에 이미 동기화된 비삭제 페이지 게시물을 반환하며 Graph를 실시간으로 새로 고치지 않습니다. mediaType은 TEXT·LINK·PHOTO·MULTI_PHOTO·VIDEO·REEL·STORY 또는 null입니다. Facebook post_media_view는 views, 댓글은 replies, 공유 횟수는 shares와 reposts에 동일하게 표시됩니다. 지원하지 않는 reach·quotes·bookmarks는 null입니다. 모든 null 지표는 0이 아니라 사용할 수 없다는 뜻입니다.

MCP로 사용

list_accounts·미디어 도구·publish_post·schedule_post·get_publish_status·list_scheduled_posts·cancel_scheduled_post·list_posts를 사용합니다. 동일한 facebook 객체를 전달하세요. 발행·예약은 페이지, 상태 조회는 job으로 워크스페이스를 결정합니다. 할 수 있는 작업을 참고하세요.