Skip to main content

Architecture

The full sequence​

Alice/BobMercatto (SDK)Ishtaran APISandbox1. auth.signUp()OrganizationTenancy — org+app+env+key, one call2. accounts.createAccountHolderInvitation() ×23. accountHolders.signUpAndClaimInvitation()Accounts — each claims their own session4. accounts.authorizeApplication() ×3Member session required — GAPS.md §F.95. workflows.create/createVersion/createRule/publishVersionWorkflowRules — AguardandoEntrega → Entregue6. transactions.create(alice, bob 90%, mercatto 10%)Transactions — BR-SPL-004 requires this explicit split7. deposits.createPaymentIntent()Deposits — returns a real deposit address8. sandbox.simulateDeposit() + simulateConfirmation()Transaction auto-reserves — no reserve() call9. events.ingest("ProdutoEntregue")WorkflowRules — audit trail, NOT a Settlement gate10. settlements.executeSettlement()SigningRequest built — sign, confirm, then Ledger posted (DEC-037)11. ledger.getBalance(bob)Ledger — Mercatto reads it on Bob's behalf (GAPS.md §F.10)12. withdrawals.createDestination() + request()422 WITHDRAWAL_DESTINATION_NOT_USABLE — real 24h cooldown, not bypassedSolid arrows = requests · dashed = responses/events · full source in every step's SDK link
All 12 steps ran for real against a live instance during this Business Case's validation — see Run it yourself to reproduce them.

Method map​

Every real call this Business Case uses, and which Ishtaran module owns it:

StepSDK callModuleChapter
Sign upauth.signUp(...)OrganizationTenancySetup
Invite + claimaccounts.createAccountHolderInvitation, accountHolders.signUpAndClaimInvitationAccountsSeller onboarding
Authorizeaccounts.authorizeApplicationAccountsSeller onboarding
Workflowworkflows.create/createVersion/createRule/publishVersion, eventTypes.createWorkflowRulesCreating an order
Ordertransactions.createTransactionsCreating an order
Paymentdeposits.createPaymentIntent/getPaymentIntentDepositsAccepting payment
Simulated fundingsandbox.simulateDeposit/simulateConfirmationSandboxHolding funds
Delivery eventevents.ingestWorkflowRulesConfirming delivery
Settlementsettlements.executeSettlement, signingRequests.get/submitSignedTransaction, sandbox.simulateBroadcastConfirmationSettlement → ExecutionCustody → LedgerSettlement and Split
Balanceledger.getBalanceLedgerSeller balance
Withdrawalwithdrawals.createDestination/quote/requestWithdrawalsWithdrawal

Two real authorization rules worth knowing up front​

  • Some calls need Mercatto's Member session, not its API Key. accounts.authorizeApplication, every workflows.* mutation, and events.ingest all reject an Application API Key today (confirmed live). Mercatto's examples keep two clients around — owner (Member) and mercatto (API Key) — for exactly this reason. See Known Limitations §F.9.
  • Bob and Alice's own logins are for identity only. Once they've claimed their invitation, their own session can't call Ledger, Settlement, or Withdrawals — those all require Mercatto's own credentials. Mercatto reads Bob's balance and requests his withdrawal on his behalf, the same way a real marketplace backend would. See Known Limitations §F.10.