Primeros pasos

Visión de alto nivel del camino para empezar a integrar. Cada paso enlaza al concepto correspondiente y a la ruta real de la Referencia de API.

¿Prefieres código listo antes que armar la llamada tú mismo? Usa uno de los SDKs oficiales (Java, Node.js/TypeScript, Python, Go) — misma cobertura de API, idiomático en cada lenguaje.

¿Estás construyendo con Claude, Codex, Cursor u otro agente de IA? Conecta primero el servidor MCP oficial (npx -y @ishtaran/mcp) — fundamenta al agente en las capacidades reales de Ishtaran en lugar de dejarlo adivinar.

Ejemplo rápido: consultar saldo

El mismo ejemplo (GET del saldo de una Account) en los 4 lenguajes oficiales y vía curl puro — ruta 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 oficiales para instalación y documentación completa de cada uno, o la Referencia de API para el contrato HTTP universal.

1. Regístrate (sign up)

POST /v1/auth/signup (auth.signUp() en todos los SDKs) es la forma recomendada de empezar: una sola llamada aprovisiona tu Organization, una Application predeterminada, el Environment sandbox de esa Application, y una primera API Key — devuelta una única vez, en la respuesta, lista para usar de inmediato. No hace falta ninguna Organization/Application/Environment previa. Empieza siempre por sandbox — ningún dato de prueba llega a production.

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

const owner = IshtaranClient.create({ environment: Environment.Sandbox });
const signup = await owner.auth.signUp('Mi Organization', 'owner@example.com', 'una-contraseña-fuerte');

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

Ver Organization, Application y Environment para lo que representa cada uno.

Avanzado: configuración manual/granular

La única llamada signUp() de arriba cubre la primera Organization de un nuevo integrador de principio a fin. Usa las rutas granulares de abajo solo después de eso — para agregar una segunda Application o Environment a una Organization ya existente, generar API Keys adicionales, u otro scripting de control-plane. Este no es el camino de onboarding inicial.

• POST /v1/organizations — crear otra Organization. Ver Organization.
• POST /v1/organizations/{organizationId}/applications — agregar otra Application (tu sitio, app, backoffice) a una Organization existente. Ver Application.
• POST /v1/applications/{applicationId}/environments para crear un Environment adicional, luego POST /v1/environments/{environmentId}/api-keys para generar una credencial más para él. Ver Environment y API Key.

2. Crear la primera Account

POST /v1/organizations/{organizationId}/accounts — la entidad que va a mantener saldo. Ver Account.

3. Crear una Transaction y liquidar

Crea la Transaction (workflowVersionId es opcional — omítelo por completo en tu primera integración) y llama a executeSettlement() en cuanto tu propia aplicación decida que se cumplieron las condiciones. El propio Settlement nunca verifica el estado del Workflow, así que nada aquí exige el paso 4 de abajo.

4. (Opcional) Definir un Workflow

Si quieres que la propia plataforma modele y siga los estados de tu proceso de negocio en lugar de que tu propia aplicación lo decida sola, crea y publica una Workflow Version que describa las condiciones de liberación, y referencia su id al crear una Transaction. Omite esto por completo si tu propio sistema ya sabe cuándo liquidar — la mayoría de las integraciones lo hace así.

---

Para simular todo el ciclo (Deposit/Withdrawal) sin blockchain real, consulta la guía de integración con el Sandbox.

¿Prefieres código antes que documentación? examples/quickstart-node/ (en la raíz del repositorio de la plataforma) es un script Node.js real, ejecutado en vivo antes de publicarse — cubre login, Application, Environment, API Key, Account, Transaction, Payment Intent y el crédito de saldo vía el Sandbox Faucet, con fetch puro (sin SDK). Para ejemplos equivalentes usando los SDKs oficiales (Java, Node.js, Python, Go), incluyendo el mismo flujo de principio a fin, ver SDKs oficiales — cada uno enlaza al ejemplo completo en su respectivo repositorio de GitHub.

¿Vas a traer tu propia wallet en lugar de mantener fondos en la plataforma? Consulta Self-Custody.