Arah Logo

Wiki Arah

Documentação Completa

Marketplace - API Arah

Parte de: API Arah - Lógica de Negócio e Usabilidade
Versão: 2.0
Data: 2025-01-20

🏪 Marketplace

O Marketplace lida exclusivamente com produtos e serviços oferecidos por moradores. Stores e Items não são TerritoryAssets e não podem vender ou transferir TerritoryAssets. Produtos/serviços podem referenciar um TerritoryAsset apenas de forma contextual (ex.: "Serviço de guia na trilha X"), sem implicar propriedade ou venda do asset.

Criar Store (POST /api/v1/stores)

Descrição: Cria uma loja/comércio no território para operação econômica de um morador.

Como usar:

  • Exige autenticação
  • Body: territoryId, nome, descrição, contato, contactVisibility

Regras de negócio:

  • Permissão: Apenas moradores verificados (geo/doc) podem criar stores (curadores podem gerenciar stores de terceiros)
  • Limites: Nome máximo 200 caracteres, descrição máxima 2000 caracteres
  • Status: Store é criada como ACTIVE
  • Contato: contactVisibility define se contato é público ou privado
  • Não é Asset: Store representa operação econômica, não é um TerritoryAsset

Criar Item (POST /api/v1/items)

Descrição: Cria um produto ou serviço em uma store (oferecido por um morador).

Como usar:

  • Exige autenticação
  • Body: territoryId, storeId, título, descrição, tipo (PRODUCT, SERVICE), pricingType, preço (opcional)

Regras de negócio:

  • Permissão: Apenas moradores verificados (geo/doc) podem criar items
  • Tipos: PRODUCT (produto) ou SERVICE (serviço)
  • Preço: Pode ser FREE, FIXED (preço fixo), NEGOTIABLE (negociável)
  • Status: Item é criado como ACTIVE
  • Não vende Assets: Items não podem vender ou transferir TerritoryAssets; podem apenas referenciar contextualmente (ex.: serviço de guia relacionado a uma trilha)

Buscar Items (GET /api/v1/items)

Descrição: Busca produtos e serviços no marketplace.

Como usar:

  • Exige autenticação
  • Query params: territoryId (opcional), storeId (filtro), type (filtro), q (busca de texto), skip, take (paginação)
  • Header X-Session-Id para identificar território ativo

Regras de negócio:

  • Visibilidade: Apenas items ativos (ACTIVE) são retornados
  • Filtros: storeId, type, q são opcionais e combinados
  • Paginação: Padrão 20 itens

Criar Inquiry (POST /api/v1/items/{itemId}/inquiries)

Descrição: Cria uma consulta sobre um item (interesse em comprar/contratar).

Como usar:

  • Exige autenticação
  • Path param: itemId
  • Body: message (mensagem)

Regras de negócio:

  • Permissão: Todos usuários autenticados podem criar inquiries
  • Status: Inquiry é criado como OPEN
  • Notificação: Owner da store recebe notificação

Carrinho e Checkout

Descrição: Sistema de carrinho e checkout para produtos.

Como usar:

  • POST /api/v1/cart: Adiciona item ao carrinho
  • GET /api/v1/cart: Obtém itens do carrinho
  • PUT /api/v1/cart/{itemId}: Atualiza quantidade
  • DELETE /api/v1/cart/{itemId}: Remove item
  • POST /api/v1/cart/checkout: Finaliza compra

Regras de negócio:

  • Carrinho: Por usuário e território
  • Checkout: Calcula taxas de plataforma (se configuradas)
  • Permissão: Todos usuários autenticados podem usar carrinho

Feature Flag: O módulo de marketplace é controlado por flag territorial MARKETPLACEENABLED. Quando desabilitado no território, endpoints de consulta/ação retornam 404 para evitar exposição do marketplace.

Merchants, carteira Aratá e consumo (FASE55 v0)

Descrição: aliases comerciais e leitura de saldo/consumo.

Método Path Comportamento
POST /api/v1/merchants/{merchantId}/subscription Alias de criar subscription para a store (merchantId = store id). Somente o owner. Location: /api/v1/subscriptions/{id}.
GET /api/v1/merchants/{merchantId}/consumption Medidores ai / media / notifications (zeros até writers). Seed atômico/idempotente na primeira leitura. Somente o owner.
GET /api/v1/wallets/{walletId} Carteira Aratá. Para seller, walletId = SellerBalance.Id; balance = (Pending + ReadyForPayout) / 100 — não inclui Paid. Reprojeta a cada GET a partir do ledger. Somente o titular.

Regras:

  • Autenticação JWT obrigatória; 403 se não for owner/titular; 404 se store/wallet inexistente.
  • PaidAmountInCents é histórico de payout já transferido — não entra no saldo disponível da Wallet.

📚 Documentação Relacionada

Voltar para: Índice da Documentação da API

← Voltar às Boas-VindasVer Todos os Docs →