La plataforma HstockPlus: cómo encajan realmente los pedidos, el cumplimiento y la API
Una visión técnica del marketplace: los roles, cómo fluye un pedido a través de él, qué expone la API y la distinción de un endpoint que decide si dos de tus trabajadores entregan el mismo pedido dos veces.
Sarah JohnsonEsta página describe cómo funciona el marketplace como sistema: los roles que tiene, el recorrido de un pedido y lo que expone la API. Desde esta página no se vende nada.
Dos catálogos, no uno
La plataforma maneja dos tipos de stock y se comportan de manera lo bastante distinta como para que tratarlos como una sola cosa cause problemas.
Listados de productos son bienes digitales vendidos como unidades del inventario de un vendedor: cuentas, buzones, proxies, claves. Aproximadamente diecisiete mil son visibles para los compradores en cualquier momento, extraídos de un catálogo más amplio que incluye borradores, listados pendientes de aprobación y listados que un vendedor ha desactivado. Se agrupan en categorías y subcategorías, se etiquetan para filtrar y se precian por variante en lugar de por listado, de modo que un solo listado puede tener varias opciones comprables a distintos precios.
Servicios de crecimiento se basan en cantidad: pides un número de seguidores, visualizaciones o comentarios para un enlace. Hay unos treinta mil activos. Usan su propia categorización y su propio vocabulario de etiquetas, y no cuentan contra el límite de listados de productos del vendedor.
Los vendedores son unos pocos cientos por catálogo activo, frente a unas mil quinientas cuentas con rol de vendedor, repartidas en unas quinientas sesenta tiendas.
Roles y qué puede alcanzar cada uno
Existen tres roles y son aditivos, no excluyentes, así que una misma cuenta puede ser compradora y vendedora a la vez.
- Compradores navegan, hacen pedidos, tienen saldo en la plataforma, siguen sus pedidos y abren tickets de soporte.
- Vendedores gestionan listados e inventario, procesan pedidos, configuran cupones y solicitan pagos. Un perfil de vendedor puede hacerse visible públicamente para que los compradores puedan ver todo lo que ese vendedor ofrece en un solo lugar.
- Administradores aprueban vendedores y listados, resuelven disputas y controlan los ajustes de los que depende la mayor parte del comportamiento de la plataforma.
Actualmente se requiere aprobación de vendedor, y eso también aplica a la API y a la interfaz: un vendedor cuya cuenta no haya sido aprobada recibe una respuesta explícita de aprobación pendiente en lugar de un catálogo vacío, algo útil de distinguir cuando una integración no devuelve nada.
Los vendedores se ubican en uno de cinco niveles según las ventas atribuidas de los últimos doce meses. El nivel no es decorativo. Determina cuánto espera la plataforma antes de liberar fondos automáticamente y alimenta el cálculo del límite de listados.
Cómo se mueve un pedido
El estado del pedido y el estado del pago se registran por separado, y ambos importan al leer la API.
El estado propio de un pedido pasa por pendiente, procesando, completado y luego posiblemente reembolsado, con cancelado y error como extremos terminales. El estado del pago es un campo aparte con sus propios valores: completado, parcial, reembolsado, fallido, pendiente y procesando. Un detalle si estás escribiendo un filtro: no existe un estado de pago "pagado". Una consulta que lo busque no devuelve nada, lo que parece un resultado vacío en lugar de un error en la consulta.
El cumplimiento varía según el tipo de listado. Los listados automáticos y respaldados por inventario entregan stock que la plataforma ya tiene. Los listados manuales son los que requieren que un vendedor o el software del vendedor actúe, y para eso está la API de cumplimiento.
Una vez que el comprador recibe lo que pidió, se abre una ventana de garantía. Se mide en horas y corre desde la entrega, no desde el pago, con un mínimo general de unas horas y ajustes por vendedor por encima de eso. Dentro de esa ventana el comprador puede abrir un ticket o una disputa; fuera de ella, la vía de disputa se niega. Los fondos se liberan al vendedor cuando el comprador confirma o cuando expira el temporizador de confirmación automática del nivel de ese vendedor, lo que ocurra primero, y una disputa activa retiene la liberación.
La API y la distinción que más importa
Hay dos superficies de API, ambas autenticadas por clave.
La superficie orientada al comprador sigue la convención de panel ampliamente usada: un único endpoint que recibe un parámetro action. Las acciones estándar están todas implementadas, así que las herramientas de panel existentes funcionan contra ella: services para listar lo disponible, add para hacer un pedido, status para consultar uno, balance, refill y cancel. Además añade acciones que la convención no define: categories y subcategory_info para navegar la taxonomía, products y shops, allowcancel, inventory para comprobar stock, y un conjunto completo de acciones de verificación por SMS que cubren proyectos, países, pedido de número y consulta del código. Trátala como la convención estándar más extensiones, no como un clon directo; las llamadas estándar funcionarán sin cambios, y las extensiones son donde reside la capacidad específica de la plataforma.
La superficie orientada al vendedor es una API REST convencional que cubre productos, pedidos, tickets y pagos. Dentro de ella hay una distinción que decide si tu integración es correcta, y es fácil equivocarse porque ambos endpoints devuelven pedidos.
- Listar pedidos es una lectura. No reclama nada. Dos workers consultándola reciben el mismo pedido, y ambos intentarán entregarlo.
- Extraer pedidos es un reclamo. Mueve cada pedido de pendiente a procesando con una escritura condicional y devuelve solo los pedidos cuya escritura realmente ganó. Si dos workers extraen simultáneamente, cada uno recibe un conjunto disjunto.
Cualquier cosa que cumpla automáticamente debería extraer, no listar. Usa la lectura para paneles y conciliación, donde ver el mismo pedido dos veces es inofensivo.
Tres detalles más te ahorran una tarde. Extraer devuelve solo líneas de cumplimiento manual, así que el stock automático y respaldado por inventario nunca aparecerá ahí. El lote predeterminado es de cien pedidos y el máximo es quinientos. Y un pedido extraído no se vuelve a ofrecer durante aproximadamente media hora, lo cual es un margen de seguridad deliberado: si tu worker se cae después de extraer, el pedido vuelve solo, pero no al instante.
La referencia completa de ambas superficies está en la documentación de la API de comprador y la documentación de la API de vendedor.
Pagos y saldos
La plataforma maneja un saldo interno por el que fluye la mayor parte de la actividad. Los compradores lo recargan y gastan de él, los reembolsos se acreditan ahí, y es de donde se paga la mayoría de los pedidos. Se admiten tanto criptomonedas como canales de pago convencionales para recargar, algunos liquidando directamente y otros a través de un procesador de pagos.
Los vendedores solicitan pagos contra el valor de pedidos liquidado y liberado. Se aplica un mínimo, establecido a nivel de plataforma con mínimos adicionales por método, y los pagos llevan una comisión porcentual. No se cobra comisión por pedido a los vendedores, así que la comisión de pago es donde está el margen de la plataforma, no en la venta en sí.
Soporte y disputas
El soporte funciona con un sistema de tickets compartido por los tres roles, de modo que un comprador, un vendedor y el soporte pueden estar en un mismo hilo en lugar de en tres conversaciones que nunca se encuentran. Los tickets llevan una clasificación del problema, y un vendedor puede resolver uno reemplazando el artículo entregado, reembolsándolo o rechazando la reclamación.
Las disputas son la vía más pesada y son deliberadamente más estrechas: requieren que el pedido esté completo y dentro de su ventana de garantía, al menos una captura de pantalla y una selección de una lista de problemas de dos niveles. Terminan con los fondos yendo al vendedor o de vuelta al comprador. Un reemplazo no es un resultado de disputa, por eso la vía de ticket resuelve la gran mayoría de los problemas reales y por qué abrir un ticket primero suele ser el camino más rápido.
Lo que se ejecuta en segundo plano
Varias cosas ocurren sin que nadie las active, y es más fácil razonar sobre una integración sabiendo que existen: los fondos se confirman y liberan automáticamente tras el retraso del nivel del vendedor; una disputa abandonada después de que todos sus tickets estén cerrados se resuelve a favor del vendedor tras un número fijo de días; las ubicaciones destacadas expiran en un trabajo diario; las promociones aprobadas se revisan semanalmente; y el texto de los listados se escanea por lotes contra las reglas de contacto fuera de la plataforma.
Nada de esto se anuncia a la API. Si tu conciliación ve que un pedido cambia de estado sin ninguna llamada tuya, normalmente una de estas cosas es la razón.
Cómo empezar
- Regístrate y luego solicita la aprobación de vendedor si piensas vender. La aprobación aplica tanto a la API como a la interfaz.
- Crea listados, o importa servicios de crecimiento desde un proveedor upstream configurado en lote en lugar de uno a uno.
- Genera una clave de API y confirma tu rol llamando al endpoint de perfil antes que a cualquier otra cosa.
- Si cumples manualmente, construye contra el endpoint de extracción desde el principio. Cambiar de listar a extraer después de haber enviado entregas duplicadas es un día peor que leer este párrafo.
- Configura las horas de garantía por listado deliberadamente. Es el reloj contra el que corre toda la protección al comprador de la plataforma, y empieza en la entrega.
