Pular para o conteúdo principal

Creating an order

Alice quer comprar os fones de ouvido de Bob. A Mercatto descreve a vida do pedido como um mapa de dois estados — aguardando entrega, depois entregue — e cria a Transaction que vai reter o dinheiro de Alice, dizendo de antemão para a Ishtaran exatamente como isso deve ser dividido no fim: 90% para Bob, 10% para a própria comissão da Mercatto.

AguardandoEntrega ──(evento ProdutoEntregue)──► Entregue

Código​

examples/marketplace-mercatto/create-order.ts
const workflow = await owner.workflows.create(organizationId, 'Mercatto - Ciclo do Pedido');
const version = await owner.workflows.createVersion(
  workflow.workflowId,
  [
    { id: awaitingDeliveryStateId, name: 'AguardandoEntrega', isInitial: true, isFinal: false },
    { id: deliveredStateId, name: 'Entregue', isInitial: false, isFinal: true },
  ],
  [{ id: transitionId, fromStateId: awaitingDeliveryStateId, toStateId: deliveredStateId }],
);
const eventType = await owner.eventTypes.create(organizationId, 'ProdutoEntregue');
await owner.workflows.createRule(workflow.workflowId, version.workflowVersionId, awaitingDeliveryStateId, deliveredStateId, eventType.eventTypeId, []);
await owner.workflows.publishVersion(workflow.workflowId, version.workflowVersionId);

const buyer = { accountId: aliceAccountId, role: 'buyer', isPayer: true };
const seller = { accountId: bobAccountId, role: 'seller', isPayer: false, splitPercentage: '90' };
const marketplace = { accountId: mercattoRevenueAccountId, role: 'marketplace', isPayer: false, splitPercentage: '10' };

const transaction = await mercatto.transactions.create(
  organizationId, applicationId, version.workflowVersionId, assetNetworkId, '200',
  [buyer, seller, marketplace], `mercatto-order-${runId}`,
);

Resultado​

{ "transactionId": "…", "status": "CREATED" }

O que aconteceu por baixo dos panos​

As Rules precisam existir antes de você publicar. Chamar createRule numa WorkflowVersion já Published é rejeitado (422 WORKFLOW_VERSION_NOT_MUTABLE) — ordem real, confirmada ao vivo, não apenas uma convenção de documentação.

O Split é explícito de propósito. Com dois Participants não-pagadores (Bob e Mercatto), a Ishtaran exige um splitPercentage explícito em cada um — um único beneficiário sem split declarado receberia 100% implicitamente no lugar (BR-SPL-004, veja Failure scenarios para esse caso mais simples). Essa regra existe por causa de um bug financeiro real, histórico: antes dela, uma suposição implícita de 100%-para-um- beneficiário era aplicada mesmo com dois ou mais beneficiários, credidando a mais quem quer que fosse avaliado primeiro. Os percentuais são validados para somar exatamente 100% na criação da Transaction, não no Settlement — um split inválido (digamos, 90% + 20%) sequer chega a produzir uma Transaction.