Skip to main content
Publica tareas remuneradas desde tu propio producto, financíalas con el saldo de una cuenta y lleva la cola de envíos a tu propia interfaz. Esta guía cubre el ciclo completo: crear una recompensa, recibir trabajo, revisarlo y cancelar.
Necesitas una clave de API con bounty:create y payout:transfer_funds, porque publicar una recompensa mueve dinero. Leer los envíos requiere bounty:basic:read.

Publica una recompensa

POST /bounties necesita un title, una description con las instrucciones que sigue un trabajador y un gross_reward_amount.

Lo que te cuesta la recompensa

gross_reward_amount se expresa en dólares estadounidenses enteros por envío aceptado, no por recompensa. accepted_submissions_limit establece cuántos envíos pueden ganar, y su valor predeterminado es 1. Whop retiene en depósito de garantía el producto de ambos, y ese total debe ser de al menos $5. El ejemplo anterior retiene $100. Las comisiones de la plataforma y las participaciones de afiliados se descuentan del importe bruto en lugar de sumarse, por lo que una recompensa de $25 le cuesta $25 a quien la financia.

De dónde sale el dinero

El fondo se toma del saldo personal del llamador de forma predeterminada. Pasa account_id para financiarlo con el saldo de una cuenta, lo que requiere permiso para mover los fondos de esa cuenta.

Dónde se ubica la recompensa

experience_id coloca una recompensa en una experiencia específica, pública para una recompensa abierta o privada para una por invitación, y es obligatorio a menos que establezcas account_id. Cuando estableces account_id y omites la experiencia, la recompensa se ubica en el foro público de esa cuenta.

Declara el objetivo

business_goal_type indica lo que debe lograr el trabajo, y lo declaras una sola vez al crear la recompensa. Acepta clipping, post_engagement, owned_account_growth, ugc_content, local_activation, data_capture u other. capture_spec solo se acepta cuando el objetivo es data_capture. Enviarlo con cualquier otro objetivo falla.

Programa y repite

Una recompensa se publica en cuanto la creas, a menos que establezcas publish_at. Whop la crea como un borrador oculto y luego la financia y la publica a la hora que indicaste. publish_at_timezone es obligatorio siempre que se establezca publish_at. frequency convierte una recompensa programada en una recurrente. Su valor predeterminado es once, acepta hourly, daily, weekly o monthly, y solo se aplica junto con publish_at. Cada repetición es una recompensa independiente con sus propios envíos y su propio depósito de garantía.

Edita una recompensa

Lo que acepta PATCH /bounties/{id} depende de si la recompensa se ha publicado. Un borrador programado lo acepta todo: la recompensa, los cupos de ganadores, la programación y los campos de contenido. Una recompensa publicada solo acepta contenido, es decir, title, description, allowed_country_codes y business_goal_type. Incluso esos se rechazan una vez que la recompensa deja de aceptar intentos, o una vez que algún envío llega a submitted o approved. La recompensa, los cupos de ganadores y la programación quedan fijados una vez que se publica una recompensa. accepted_submissions_per_user_limit limita cuántos cupos puede ganar un trabajador. Su valor predeterminado es 1, no puede superar accepted_submissions_limit, y un trabajador realiza un intento a la vez.

Recibe envíos

POST /bounty_submissions acepta el bounty_id y un deliverable. Combina urls, file_ids y un caption, con al menos un enlace o un archivo. Whop rechaza un entregable vacío. En una recompensa estándar, esta única llamada es todo el flujo del trabajador, y el envío pasa directamente a revisión. Los envíos necesitan una credencial de usuario, por lo que una clave de API de cuenta no puede crear uno.
allowed_country_codes restringe quién puede realizar una recompensa. Acepta códigos ISO 3166 alfa-2. Una lista vacía significa todo el mundo. Un trabajador puede retirar su propio intento con DELETE /bounty_submissions/{id}. Solo puede hacerlo el trabajador que lo inició, y una clave de API de cuenta no puede hacerlo en su nombre.

Objetivos que tu integración no puede completar

Dos tipos de objetivo acumulan su prueba fuera de la API. En una recompensa data_capture, crea el envío sin un entregable: eso inicia un intento reclamado cuyos clips se acumulan en el servidor. La prueba de una recompensa de transmisión en vivo pasa por una superficie que la API pública no expone. Tu integración puede publicar estas recompensas y leer sus colas, pero el trabajador termina el intento en Whop.

Revisa la cola

Lee los envíos con GET /bounty_submissions, filtrados por bounty_id y, opcionalmente, por status.
Un envío pasa por cuatro estados:
La aprobación y el rechazo se realizan en el panel de Whop. La API no tiene ninguna operación de aprobar o rechazar, así que tu producto puede mostrar la cola y sus resultados, pero una persona decide en Whop.
Las recompensas no emiten webhooks. Para reflejar los resultados en tu propio producto, consulta periódicamente GET /bounty_submissions filtrado por la recompensa. Una vez por minuto es adecuado para una cola que revisa una persona. Reduce la frecuencia a cada pocos minutos cuando una recompensa no tenga actividad reciente.

Cancela una recompensa

POST /bounties/{id}/cancel reembolsa a quien la financió inmediatamente cuando no hay trabajo en curso. Cuando hay trabajo en revisión, detiene los nuevos envíos y se cancela una vez que ese trabajo se resuelve y se paga. Repetir la solicitud no hace nada. Una recompensa que ya pagó todos sus cupos devuelve un 400.

Solicitudes que pasan la validación y aun así fallan

Cuatro reglas que el esquema de la solicitud no puede expresar. Cada una devuelve un error aunque el cuerpo esté bien formado:
  • experience_id omitido sin account_id establecido.
  • frequency enviado sin publish_at.
  • capture_spec enviado cuando business_goal_type es cualquier valor distinto de data_capture.
  • Un deliverable que no incluye ni un enlace ni un archivo.

Próximos pasos

Descripción general de las recompensas

Los objetos y cómo encajan entre sí.

Sube archivos

Obtén los ID de archivo a los que hace referencia un entregable.

Referencia de recompensas

Estructuras de solicitud y respuesta de cada endpoint.

Referencia de envíos de recompensas

El objeto de envío y sus filtros.