Plataforma HstockPlus: Como Pedidos, Atendimento e a API Realmente se Conectam

Esta página descreve como o marketplace funciona como sistema: os papéis que possui, o caminho que um pedido percorre e o que a API expõe. Nada é vendido a partir desta página.

Dois catálogos, não um

A plataforma carrega dois tipos de estoque e eles se comportam de maneiras diferentes o suficiente para que tratá-los como uma coisa só cause problemas.

Listagens de produtos são bens digitais vendidos como unidades do inventário de um vendedor: contas, caixas de e-mail, proxies, chaves. Aproximadamente dezessete mil estão visíveis para compradores a qualquer momento, extraídas de um catálogo maior que inclui rascunhos, listagens aguardando aprovação e listagens que um vendedor desativou. Elas são agrupadas em categorias e subcategorias, marcadas para filtragem e precificadas por variante em vez de por listagem, então uma única listagem pode ter várias opções compráveis a preços diferentes.

Serviços de crescimento são baseados em quantidade: você pede um número de seguidores, visualizações ou comentários para um link. Cerca de trinta mil estão ativos. Eles usam sua própria categorização e seu próprio vocabulário de tags, e não contam contra o limite de listagens de produtos de um vendedor.

Os vendedores somam algumas centenas por catálogo ativo, contra cerca de mil e quinhentas contas com o papel de vendedor, distribuídas por aproximadamente quinhentas e sessenta lojas.

Papéis e o que cada um pode acessar

Existem três papéis e eles são aditivos em vez de exclusivos, então uma conta pode ser compradora e vendedora ao mesmo tempo.

• Compradores navegam, fazem pedidos, mantêm saldo no site, acompanham pedidos e abrem tickets de suporte.
• Vendedores gerenciam listagens e inventário, processam pedidos, configuram cupons e solicitam saques. Um perfil de vendedor pode ser tornado publicamente visível para que compradores possam navegar por tudo o que aquele vendedor oferece em um só lugar.
• Administradores aprovam vendedores e listagens, resolvem disputas e detêm as configurações das quais a maior parte do comportamento da plataforma depende.

A aprovação de vendedor é atualmente obrigatória e também controla o acesso à API e à interface: um vendedor cuja conta não foi aprovada recebe uma resposta explícita de aprovação pendente em vez de um catálogo vazio, o que é algo útil de distinguir quando uma integração não retorna nada.

Os vendedores estão em um de cinco níveis derivados das vendas atribuídas nos últimos doze meses. O nível não é decorativo. Ele define quanto tempo a plataforma espera antes de liberar fundos automaticamente e alimenta o cálculo do limite de listagens.

Como um pedido se move

O estado do pedido e o estado do pagamento são rastreados separadamente, e ambos importam ao ler a API.

O estado de um pedido passa por pendente, processando, concluído e, possivelmente, reembolsado, com cancelado e erro como extremidades terminais. O estado do pagamento é um campo separado com seus próprios valores: concluído, parcial, reembolsado, falhou, pendente e processando. Uma coisa a notar se você estiver escrevendo um filtro: não existe estado de pagamento "pago". Uma consulta por ele não retorna nada, o que parece um resultado vazio em vez de um erro na consulta.

A entrega difere por tipo de listagem. Listagens automáticas e com suporte de inventário entregam estoque que a plataforma já possui. Listagens manuais são as que precisam que um vendedor ou o software de um vendedor aja, e é para elas que a API de entrega existe.

Assim que um comprador recebe o que pediu, uma janela de garantia se abre. Ela é medida em horas e começa a partir da entrega, não do pagamento, com um piso de algumas horas em todo o site e configurações por vendedor acima disso. Dentro dessa janela, o comprador pode abrir um ticket ou uma disputa; fora dela, o caminho de disputa recusa. Os fundos são liberados ao vendedor quando o comprador confirma ou quando o temporizador de confirmação automática do nível daquele vendedor expira, o que ocorrer primeiro, e uma disputa ativa segura a liberação.

A API e a distinção que mais importa

Existem duas superfícies de API, ambas autenticadas por chave.

A superfície voltada ao comprador segue a convenção de painel amplamente usada: um único endpoint que recebe um parâmetro action. As ações padrão estão todas implementadas, então ferramentas de painel existentes funcionam com ela: services para listar o que está disponível, add para fazer um pedido, status para verificar um, balance, refill e cancel. Além delas, ela adiciona ações que a convenção não define: categories e subcategory_info para navegar pela taxonomia, products e shops, allowcancel, inventory para verificações de estoque e um conjunto completo de ações de verificação por SMS cobrindo projetos, países, pedido de número e consulta do código. Trate-a como a convenção padrão mais extensões, em vez de um clone direto; as chamadas padrão funcionarão sem alterações, e as extensões são onde reside a capacidade específica da plataforma.

A superfície voltada ao vendedor é uma API REST convencional cobrindo produtos, pedidos, tickets e pagamentos. Dentro dela há uma distinção que decide se sua integração está correta, e é fácil errar porque ambos os endpoints retornam pedidos.

• Listar pedidos é uma leitura. Não reivindica nada. Dois workers consultando recebem o mesmo pedido, e ambos tentarão entregá-lo.
• Puxar pedidos é uma reivindicação. Move cada pedido de pendente para processando com uma escrita condicional e retorna apenas os pedidos cuja escrita realmente venceu. Se dois workers puxarem simultaneamente, cada um recebe um conjunto disjunto.

Qualquer coisa que entregue automaticamente deve puxar, não listar. Use a leitura para painéis e reconciliação, onde ver o mesmo pedido duas vezes é inofensivo.

Mais três detalhes economizam uma tarde. Puxar retorna apenas linhas de entrega manual, então estoque automático e com suporte de inventário nunca aparecerá ali. O lote padrão é de cem pedidos e o teto é de quinhentos. E um pedido puxado não é oferecido novamente por cerca de meia hora, o que é uma margem de segurança deliberada: se seu worker travar após puxar, o pedido volta sozinho, mas não instantaneamente.

A referência completa para ambas as superfícies está em documentação da API do comprador e documentação da API do vendedor.

Pagamentos e saldos

A plataforma opera um saldo interno pelo qual a maior parte da atividade passa. Compradores o recarregam e gastam a partir dele, reembolsos são creditados nele, e é de onde a maioria dos pedidos é realmente paga. Tanto criptomoedas quanto canais de pagamento convencionais são suportados para recarga, alguns liquidando diretamente e outros por meio de um processador de pagamento.

Vendedores solicitam saques contra o valor de pedidos liquidados e liberados. Um mínimo se aplica, definido em toda a plataforma com mínimos adicionais por método por cima, e os saques têm uma taxa percentual. Não há comissão por pedido retirada dos vendedores, então a taxa de saque é onde está a fatia da plataforma, em vez de na venda em si.

Suporte e disputas

O suporte funciona por um sistema de tickets compartilhado pelos três papéis, então um comprador, um vendedor e o suporte podem estar em uma única conversa em vez de três conversas que nunca se encontram. Tickets carregam uma classificação de problema, e um vendedor pode resolver um substituindo o item entregue, reembolsando-o ou rejeitando a reclamação.

Disputas são o caminho mais pesado e são deliberadamente mais estreitas: exigem que o pedido esteja concluído e dentro da janela de garantia, pelo menos uma captura de tela e uma seleção de uma lista de problemas de dois níveis. Elas terminam com os fundos indo para o vendedor ou de volta ao comprador. Uma substituição não é um resultado de disputa, e é por isso que o caminho de ticket resolve a grande maioria dos problemas reais e por que abrir um ticket primeiro costuma ser o caminho mais rápido.

O que roda em agendamento

Várias coisas acontecem sem ninguém acioná-las, e uma integração é mais fácil de entender sabendo que elas existem: fundos são confirmados e liberados automaticamente após o atraso do nível do vendedor; uma disputa deixada de lado depois que todos os seus tickets são fechados é resolvida a favor do vendedor após um número fixo de dias; posições em destaque expiram em um job diário; compartilhamentos promocionais aprovados são reverificados semanalmente; e o texto das listagens é escaneado em lotes contra as regras de contato fora da plataforma.

Nenhuma dessas coisas se anuncia à API. Se sua reconciliação vir um pedido mudar de estado sem nenhuma chamada sua, uma delas costuma ser o motivo.

Começando

1. Registre-se e, se pretende vender, solicite a aprovação de vendedor. A aprovação controla a API e a interface.
2. Crie listagens ou importe serviços de crescimento de um provedor upstream configurado em massa, em vez de um por um.
3. Gere uma chave de API e confirme seu papel chamando o endpoint de perfil antes de qualquer outra coisa.
4. Se você entrega manualmente, construa contra o endpoint de puxar desde o início. Trocar de listar para puxar depois de já ter enviado entregas duplicadas é um dia pior do que ler este parágrafo.
5. Defina as horas de garantia por listagem deliberadamente. É o relógio contra o qual toda proteção ao comprador na plataforma corre, e ele começa na entrega.