Saltearse al contenido
Celestín

Inicio rápido

Este documento te lleva desde cero hasta tu primera conciliación funcional. Tiempo estimado: 5 minutos.

1. Instala el SDK

import Tabs from ‘@astrojs/starlight/components/Tabs.astro’; import TabItem from ‘@astrojs/starlight/components/TabItem.astro’;

Node.js (requiere ≥ 18):

Ventana de terminal
npm install @celestin/sdk

Python (requiere ≥ 3.9):

Ventana de terminal
pip install celestin

2. Configura las variables de entorno

El SDK lee las credenciales desde el entorno. Crea un archivo .env en la raíz de tu proyecto:

# Obligatorio — API key obtenida en el panel de Celestín
CELESTIN_API_KEY=sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx


# Opcional — clave maestra para BYOK (bring-your-own-key)
# Si se omite, la anonimización usa la clave gestionada por Celestín
CELESTIN_MASTER_KEY=tu_clave_maestra_32_bytes_en_hex

Las API keys tienen el prefijo sk_live_ en producción y sk_test_ en el entorno de pruebas. Las claves de test no consumen cuota ni generan cargos.

3. Primera conciliación

El punto de entrada principal es POST /v1/reconciliations. El SDK construye el payload, aplica anonimización si está habilitada y gestiona reintentos automáticos.

import { CelestinClient } from "@celestin/sdk";


const client = new CelestinClient({
  apiKey: process.env.CELESTIN_API_KEY!,
});


const result = await client.reconciliations.create({
  tenantId: "mi-empresa-sl",
  bankTransactions: [
    {
      date: "2026-03-01",
      description: "TRANSFERENCIA CLIENTE ACME",
      amount: 1210.00,
      reference: "TRF-2026-0301",
    },
    {
      date: "2026-03-05",
      description: "CUOTA SEGURO ALLIANZ",
      amount: -450.00,
      reference: "REC-ALLIANZ-MAR",
    },
  ],
  ledgerEntries: [
    {
      date: "2026-03-01",
      description: "Factura 2026/031 — ACME S.L.",
      debit: 1210.00,
      credit: 0,
      account: "430",
      reference: "TRF-2026-0301",
    },
    {
      date: "2026-03-05",
      description: "Prima seguro multirriesgo",
      debit: 450.00,
      credit: 0,
      account: "625",
      reference: "REC-ALLIANZ-MAR",
    },
  ],
});

El equivalente en Python:

from celestin import CelestinClient
import os


client = CelestinClient(api_key=os.environ["CELESTIN_API_KEY"])


result = client.reconciliations.create(
    tenant_id="mi-empresa-sl",
    bank_transactions=[
        {
            "date": "2026-03-01",
            "description": "TRANSFERENCIA CLIENTE ACME",
            "amount": 1210.00,
            "reference": "TRF-2026-0301",
        },
        {
            "date": "2026-03-05",
            "description": "CUOTA SEGURO ALLIANZ",
            "amount": -450.00,
            "reference": "REC-ALLIANZ-MAR",
        },
    ],
    ledger_entries=[
        {
            "date": "2026-03-01",
            "description": "Factura 2026/031 — ACME S.L.",
            "debit": 1210.00,
            "credit": 0.0,
            "account": "430",
            "reference": "TRF-2026-0301",
        },
        {
            "date": "2026-03-05",
            "description": "Prima seguro multirriesgo",
            "debit": 450.00,
            "credit": 0.0,
            "account": "625",
            "reference": "REC-ALLIANZ-MAR",
        },
    ],
)

4. Interpreta la respuesta

{
  "id": "rec_01HXYZ123ABC",
  "status": "completed",
  "created_at": "2026-03-15T09:12:34Z",
  "expires_at": "2026-03-16T09:12:34Z",
  "summary": {
    "bank_count": 2,
    "ledger_count": 2,
    "matched_count": 2,
    "exception_count": 0,
    "match_rate": 1.0
  },
  "matches": [
    {
      "bank_transaction_id": "bt_0",
      "ledger_entry_id": "le_0",
      "level": 1,
      "confidence": 1.0,
      "method": "exact"
    },
    {
      "bank_transaction_id": "bt_1",
      "ledger_entry_id": "le_1",
      "level": 1,
      "confidence": 1.0,
      "method": "exact"
    }
  ],
  "exceptions": []
}

Los campos clave:

  • status — pending | processing | completed | failed
  • summary.match_rate — fracción de movimientos bancarios con match (0.0–1.0)
  • matches[].level — nivel del algoritmo que encontró el match (1=exacto, 11=ref parcial, 2=fuzzy, 4=agregado, 5=memoria, 3=LLM)
  • matches[].confidence — confianza del match (0.0–1.0)
  • exceptions — movimientos sin match; cada excepción incluye reason y suggested_account cuando el PGC permite clasificación automática
  • expires_at — los resultados se conservan 24 h; pasado ese tiempo el endpoint devuelve 404

5. Próximos pasos

  • Anonimización: aprende cómo el SDK anonimiza IBANs, NIFs y emails antes de enviarlos → Anonimización
  • Webhooks: recibe notificaciones cuando una conciliación termina en lugar de hacer polling → POST /v1/webhooks
  • BYOK: usa tu propia clave maestra para que ni Celestín pueda ver los tokens → Seguridad
  • Multi-tenant: gestiona varias sociedades desde una única API key → Tenants