Barrido de recompensas

El barrido de recompensas mueve las recompensas disponibles de una cuenta a una cuenta de gasto de otra cuenta de Fluz, una vez al día, sin que el usuario tenga que hacer nada. Tu app conecta la cuenta del usuario a una cuenta de destino aprobada. Fluz ejecuta el barrido. Úsalo cuando tu plataforma recopila las recompensas que tus usuarios ganan en Fluz. Por ejemplo, barre el cashback que ganan tus miembros hacia la cuenta de gasto operativa de tu plataforma. Esta página cubre la superficie GraphQL de TGS:

Cómo funciona

Fluz aprueba tu cuenta de destino, define la cuenta de gasto en la que se depositan las recompensas y agrega tu app a la lista de permitidos. Esta es una configuración única que realiza Fluz, y nada funciona hasta que esté completa. Consulta Configuración con Fluz.
El usuario autoriza tu app. Tu app llama a createRewardsSweepConnection con el token de acceso del usuario y el ID de tu cuenta de destino.
Una vez por cada día calendario de Nueva York, Fluz mueve el saldo completo de recompensas disponibles del usuario a tu cuenta de gasto de destino.
Para detenerlo, tu app llama a deleteRewardsSweepConnection con el token de acceso del usuario.

En esta página, la cuenta de origen es la cuenta del usuario cuyas recompensas se barren. La cuenta de destino es la cuenta que recibe el dinero. La cuenta de gasto es la cuenta de gasto del destino en la que se deposita el dinero.

Solo se barren las recompensas disponibles.El barrido toma el saldo de recompensas disponible para gastar en el momento en que se ejecuta. Las recompensas pendientes o bloqueadas permanecen en la cuenta de origen hasta que un barrido posterior las recoja. Nada se retiene por adelantado: el usuario puede gastar sus recompensas con normalidad hasta que se ejecute el barrido.

Configuración con Fluz

Fluz debe aprobar tu cuenta de destino y agregar tu app a la lista de permitidos antes de que puedas conectar cualquier cuenta.No puedes hacerlo por tu cuenta a través de la API. Hasta que Fluz haya hecho ambas cosas, createRewardsSweepConnection falla con App is not allowed to create a rewards sweep connection o Target account is not approved for rewards sweep.

Contacta a tu gerente de cuenta de Fluz con lo siguiente:

Envía a Fluz	Por qué
El ID de tu cuenta de destino	La cuenta que recibe las recompensas barridas. Fluz la agrega a los destinos aprobados.
La cuenta de gasto de esa cuenta de destino	Donde se deposita el dinero. Debe pertenecer a la cuenta de destino. Cada destino tiene exactamente una cuenta de gasto de destino.
El ID de tu app (o IDs)	Fluz agrega a la lista de permitidos cada app que llamará a las mutaciones de barrido de recompensas.

Fluz confirma cuando el destino está aprobado y la app está en la lista de permitidos. Para cambiar la cuenta de gasto de destino o agregar otra app más adelante, contacta a Fluz nuevamente. Tu app no puede modificar su propia configuración. Fluz también puede conectar una cuenta a tu destino desde su propio panel, sin una llamada a la API.

Requisitos para cada llamada

Requisito	Valor
Autenticación	Token Bearer de la cuenta de origen. No se admite Basic Auth.
Scope	`MAKE_PAYOUT_TRANSFER_SEND` (el mismo scope que `createTransfer`). Solicítalo cuando el usuario autorice tu app.
App	Agregada por Fluz a la lista de permitidos para el barrido de recompensas
Destino	Aprobado por Fluz para el barrido de recompensas

Conectar una cuenta

Llama a createRewardsSweepConnection con el token de acceso del usuario. La cuenta de origen siempre proviene del token. Pasa el ID de tu cuenta de destino, no el ID de una cuenta de gasto.

mutation {
  createRewardsSweepConnection(input: {
    targetAccountId: "b2c3d4e5-f6a7-8901-bcde-f23456789012"
  }) {
    rewardsSweepSourceAccountId
    sourceAccountId
    targetAccountId
  }
}

Authorization: Bearer <user-access-token>

{
  "data": {
    "createRewardsSweepConnection": {
      "rewardsSweepSourceAccountId": "7c1e2d3f-4a5b-4c6d-8e9f-0a1b2c3d4e5f",
      "sourceAccountId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "targetAccountId": "b2c3d4e5-f6a7-8901-bcde-f23456789012"
    }
  }
}

Reglas

Una cuenta de origen puede estar conectada a un solo destino a la vez.
Llamar a create nuevamente con el mismo destino es seguro. Devuelve la conexión existente.
Llamar a create con un destino diferente falla mientras exista una conexión. Para cambiar de destino, desconecta primero y luego conecta al nuevo destino.
La cuenta de origen y la de destino deben ser cuentas diferentes.
Fluz también puede crear una conexión para una cuenta desde su panel. Esa conexión se comporta igual y se puede eliminar con deleteRewardsSweepConnection.

Desconectar una cuenta

Llama a deleteRewardsSweepConnection con el token de acceso del usuario. No recibe ningún input. Elimina la conexión de la cuenta del token.

mutation {
  deleteRewardsSweepConnection {
    sourceAccountId
    disconnected
  }
}

{
  "data": {
    "deleteRewardsSweepConnection": {
      "sourceAccountId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "disconnected": true
    }
  }
}

disconnected es false cuando la cuenta no tenía una conexión. Eso no es un error, por lo que es seguro repetir la llamada. Si desconectas después de que el barrido del día esté programado pero antes de que se mueva el dinero, el barrido de ese día se cancela y no se debita nada.

Comportamiento del barrido


Frecuencia	Como máximo un barrido por cuenta de origen por día calendario, en horario de `America/New_York`. Fluz define la hora de ejecución.
Monto	El saldo completo de recompensas disponibles en el momento en que se ejecuta el barrido, redondeado hacia abajo a centavos completos. Cualquier fracción de centavo permanece en la cuenta de origen.
Saldo cero	No se realiza ninguna transferencia. El día cuenta como barrido.
Destino	La cuenta de gasto configurada para el destino cuando se programa el barrido del día.
Reintentos	Cada barrido diario tiene una clave de idempotencia fija, por lo que un reintento nunca mueve el dinero dos veces.
Saldo insuficiente	Si el saldo cambia antes de que se mueva el dinero, el barrido vuelve a leer el saldo y reintenta.
Barrido rechazado	Si Fluz no puede mover el dinero de esa cuenta, por ejemplo porque la cuenta está en revisión, el barrido de ese día se detiene y no se reintenta. Las recompensas permanecen en la cuenta de origen, y el barrido del día siguiente lo intenta de nuevo.
Desconectada	Si la cuenta se desconecta después de que el barrido del día esté programado pero antes de que se mueva el dinero, no se debita nada.

Lo que ven las cuentas

Cada barrido es una transferencia de cuenta a cuenta. Aparece en la actividad de ambas cuentas con la descripción Rewards transfer.

Cuenta	Fila de actividad
Origen	Dinero enviado del saldo de recompensas de Fluz a la cuenta de destino y a la cuenta de gasto
Destino	Dinero recibido de la cuenta de origen en la cuenta de gasto

Verificar una conexión

Actualmente no hay una consulta para leer una conexión ni los barridos anteriores. Guarda la conexión de tu lado a partir de las respuestas de createRewardsSweepConnection y deleteRewardsSweepConnection. Confirma los barridos desde la actividad de transacciones de la cuenta de destino.

Errores

Los fallos usan el envoltorio de errores estándar de GraphQL.

{
  "data": null,
  "errors": [
    {
      "message": "Target account is not approved for rewards sweep",
      "extensions": {
        "code": "APPLICATIONS-0012",
        "errorName": "InvalidArgument",
        "statusCode": 422
      }
    }
  ]
}

Los errores se verifican en este orden:

Código	Mensaje	Cuándo
`AUTH-0002`	Basic auth is not supported for this operation.	La solicitud usó Basic Auth. Usa el token Bearer del usuario.
`AUTH-0031`	Insufficient permissions: `<mutation>` requires MAKE_PAYOUT_TRANSFER_SEND	Al token le falta el scope `MAKE_PAYOUT_TRANSFER_SEND`.
`AUTH-0008`	Authenticated account is required.	El token no corresponde a ninguna cuenta.
`AUTH-0008`	App is not allowed to create a rewards sweep connection	Tu app no está en la lista de permitidos para el barrido de recompensas. Delete devuelve el mismo mensaje con “delete”.
`APPLICATIONS-0012`	Target account is not approved for rewards sweep	`targetAccountId` no es un destino registrado, o no tiene cuenta de gasto. Solo en create.
`APPLICATIONS-0012`	Source and target accounts must be different.	La cuenta del token es la cuenta de destino. Solo en create.
`APPLICATIONS-0012`	Source account is already connected to a rewards sweep target	La cuenta está conectada a un destino diferente. Desconecta primero. Solo en create.

Un token de acceso ausente, inválido o vencido se rechaza antes de que se ejecute GraphQL y devuelve un error HTTP, no un error de GraphQL. Consulta Autenticación.

​Cómo funciona

​Configuración con Fluz

​Requisitos para cada llamada

​Conectar una cuenta

​Desconectar una cuenta

​Comportamiento del barrido

​Lo que ven las cuentas

​Verificar una conexión

​Errores

Cómo funciona

Configuración con Fluz

Requisitos para cada llamada

Conectar una cuenta

Desconectar una cuenta

Comportamiento del barrido

Lo que ven las cuentas

Verificar una conexión

Errores