vtexads-api-docs

7. Transferencia de Créditos

La transferencia de créditos es el flujo que permite al marketplace transferir créditos de publicidad a sus sellers. Esta documentación detalla los endpoints que el marketplace debe implementar y el webhook que debe consumir para realizar la integración con VTEXAds.

• Endpoints a ser implementados por el Marketplace (Autenticación: Basic Auth):
  1. Consulta de Saldo (GET /checking_account)
     • Objetivo: Verificar el saldo disponible del seller.
     • Parámetros (Query): seller_id, publisher_id (opcional, utilizado solo en casos donde una entidad gestiona múltiples publishers).
     • Respuesta Exitosa (200 OK):

       { "total": "1111.00" }
       

  2. Solicitud de Transferencia (POST /checking_account/transfer)
     • Objetivo: Requerir la transferencia de un valor.
     • Cuerpo de la Solicitud:

       {
         "amount": "10.00",
         "seller_id": "SELLER_ID",
         "publisher_id": "PUBLISHER_ID",
         "transfer_identity_id": "uuid"
       }
       

     • Respuestas:
       • Síncrona (Éxito): 201 Created

         {
           "transaction_id": "TRANSACTION_ID",
           "status": "success"
         }
         

       • Síncrona (Falla): 400 Bad Request

         {
           "transaction_id": "TRANSACTION_ID",
           "status": "failure",
           "message": "Motivo del rechazo"
         }
         

       • Asíncrona: 202 Accepted

         {
           "transaction_id": "TRANSACTION_ID",
           "status": "processing"
         }
         

• Webhook a ser consumido por el Marketplace:
  • Objetivo: Notificar a VTEXAds sobre el estado final de la transferencia.
  • Endpoint: POST https://api-retail-media.newtail.com.br/webhook/marketplace/transfers/:publisher_id
  • Autenticación: x-api-key y x-secret-key.
  • Payload:

    {
      "transaction_id": "TRANSACTION_ID",
      "status": "success"
    }
    

    o

    {
      "transaction_id": "TRANSACTION_ID",
      "status": "failure",
      "message": "Descripción del problema"
    }
    

  • Lógica de Reintentos: En caso de falla en la llamada del webhook, el marketplace debe realizar nuevos intentos.
  • Respuesta Esperada: 204 No Content