Primeiros passos

Visão de alto nível do caminho para começar a integrar. Cada passo linka o conceito correspondente e a rota real da Referência de API.

Prefere código pronto a montar a chamada você mesmo? Use um dos SDKs oficiais (Java, Node.js/TypeScript, Python, Go) — mesma cobertura de API, idiomático em cada linguagem.

Está construindo com Claude, Codex, Cursor ou outro agente de IA? Conecte primeiro o servidor MCP oficial (npx -y @ishtaran/mcp) — ele fundamenta o agente nas capacidades reais da Ishtaran em vez de deixá-lo adivinhar.

Exemplo rápido: consultar saldo

O mesmo exemplo (GET do saldo de uma Account) nas 4 linguagens oficiais e via curl puro — rota real: GET /v1/accounts/{accountId}/balance.

Java

var client = IshtaranClient.builder()
    .apiKey(System.getenv("ISHTARAN_API_KEY"))
    .environment(Environment.SANDBOX)
    .build();

var balance = client.getBalance(accountId, assetNetworkId);
System.out.println("Available: " + balance.available());

Node.js/TypeScript

import { IshtaranClient, Environment } from '@ishtaran/sdk';

const client = IshtaranClient.create({
  apiKey: process.env.ISHTARAN_API_KEY,
  environment: Environment.Sandbox,
});

const balance = await client.getBalance(accountId, assetNetworkId);
console.log('Available:', balance.available);

Python

from ishtaran import IshtaranClient, Environment

client = IshtaranClient.create(
    api_key=os.environ["ISHTARAN_API_KEY"],
    environment=Environment.SANDBOX,
)

balance = client.get_balance(account_id, asset_network_id)
print("Available:", balance.available)

Go

client, err := ishtaran.NewClient(
	ishtaran.WithAPIKey(os.Getenv("ISHTARAN_API_KEY")),
	ishtaran.WithEnvironment(ishtaran.Sandbox),
)

balance, err := client.GetBalance(ctx, accountID, assetNetworkID)
fmt.Println("Available:", balance.Available)

cURL

curl -H "X-Api-Key: $ISHTARAN_API_KEY" \
  "https://sandbox-api.ishtaran.com/v1/accounts/$ACCOUNT_ID/balance?assetNetworkId=$ASSET_NETWORK_ID"

Ver SDKs oficiais para instalação e documentação completa de cada um, ou a Referência de API para o contrato HTTP universal.

1. Cadastre-se (sign up)

POST /v1/auth/signup (auth.signUp() em todos os SDKs) é o caminho recomendado para começar: uma única chamada provisiona sua Organization, uma Application padrão, o Environment sandbox dessa Application e uma primeira API Key — devolvida uma única vez, na resposta, pronta para uso imediato. Não é preciso nenhuma Organization/Application/Environment pré-existente. Comece sempre pelo sandbox — nenhum dado de teste chega a production.

import { IshtaranClient, Environment } from '@ishtaran/sdk';

const owner = IshtaranClient.create({ environment: Environment.Sandbox });
const signup = await owner.auth.signUp('Minha Organization', 'owner@example.com', 'uma-senha-forte');

const client = IshtaranClient.create({ apiKey: signup.apiKeyPlainText, environment: Environment.Sandbox });

Ver Organization, Application e Environment para o que cada um desses representa.

Avançado: configuração manual/granular

A única chamada signUp() acima cobre a primeira Organization de um novo integrador de ponta a ponta. Use as rotas granulares abaixo somente depois disso — para adicionar uma segunda Application ou Environment a uma Organization já existente, gerar API Keys adicionais, ou outro scripting de control-plane. Este não é o caminho de onboarding inicial.

• POST /v1/organizations — criar outra Organization. Ver Organization.
• POST /v1/organizations/{organizationId}/applications — adicionar outra Application (seu site, app, backoffice) a uma Organization existente. Ver Application.
• POST /v1/applications/{applicationId}/environments para criar um Environment adicional, depois POST /v1/environments/{environmentId}/api-keys para gerar mais uma credencial para ele. Ver Environment e API Key.

2. Criar a primeira Account

POST /v1/organizations/{organizationId}/accounts — a entidade que vai deter saldo. Ver Account.

3. Criar uma Transaction e liquidar

Crie a Transaction (workflowVersionId é opcional — omita completamente na sua primeira integração) e chame executeSettlement() assim que sua própria aplicação decidir que as condições foram satisfeitas. O próprio Settlement nunca verifica o estado do Workflow, então nada aqui exige o passo 4 abaixo.

4. (Opcional) Definir um Workflow

Se você quiser que a própria plataforma modele e acompanhe os estados do seu processo de negócio em vez de sua própria aplicação decidir sozinha, crie e publique uma Workflow Version que descreva as condições de liberação, e referencie o id dela ao criar uma Transaction. Pule isso completamente se seu próprio sistema já sabe quando liquidar — a maioria das integrações faz assim.

---

Para simular todo o ciclo (Deposit/Withdrawal) sem blockchain real, veja o guia de integração com o Sandbox.

Prefere código a documentação? examples/quickstart-node/ (na raiz do repositório da plataforma) é um script Node.js real e executado ao vivo antes de ser publicado — cobre login, Application, Environment, API Key, Account, Transaction, Payment Intent e crédito de saldo via Sandbox Faucet, com fetch puro (sem SDK). Para exemplos equivalentes usando os SDKs oficiais (Java, Node.js, Python, Go), incluindo o mesmo fluxo de ponta a ponta, veja SDKs oficiais — cada um linka para o exemplo completo no respectivo repositório no GitHub.

Vai trazer sua própria wallet em vez de manter fundos na plataforma? Veja Self-Custody.