> ## Documentation Index
> Fetch the complete documentation index at: https://finzaria.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> De cero a tu primera llamada exitosa a la API de Finzaria en menos de 5 minutos.

En 3 pasos vas a autenticarte y hacer tu primera llamada real.

<Steps>
  <Step title="Crea tu API key">
    Entra a la app en [app.finzaria.com](https://app.finzaria.com) → menú de tu perfil →
    **Developers** → **Crear API key**.

    Copia el valor (empieza con `bxm_`) **en el momento**: por seguridad se muestra una sola vez.
    Guárdalo en tu gestor de secretos, nunca en el código ni en el navegador.

    <Note>Elige el scope **`read_write`** si vas a crear/editar, o **`read_only`** si solo vas a leer.</Note>
  </Step>

  <Step title="Guarda tu key como variable de entorno">
    ```bash theme={null}
    export FINZARIA_API_KEY="bxm_tu_key_aqui"
    ```
  </Step>

  <Step title="Haz tu primera llamada">
    Pide tu workspace — confirma que la autenticación funciona y siempre devuelve algo:

    <CodeGroup>
      ```bash curl theme={null}
      curl https://api.finzaria.com/v1/workspace \
        -H "Authorization: Bearer $FINZARIA_API_KEY"
      ```

      ```javascript Node.js theme={null}
      const res = await fetch("https://api.finzaria.com/v1/workspace", {
        headers: { Authorization: `Bearer ${process.env.FINZARIA_API_KEY}` },
      })
      const workspace = await res.json()
      console.log(workspace)
      ```

      ```python Python theme={null}
      import os, requests

      res = requests.get(
          "https://api.finzaria.com/v1/workspace",
          headers={"Authorization": f"Bearer {os.environ['FINZARIA_API_KEY']}"},
      )
      print(res.json())
      ```
    </CodeGroup>

    Deberías ver algo así (`200 OK`):

    ```json theme={null}
    {
      "id": "9f8c…",
      "name": "Personal",
      "baseCurrency": "MXN"
    }
    ```
  </Step>
</Steps>

## Crea tu primera transacción

Ya autenticado, registra un gasto. Los montos van como **string decimal** y la fecha como `YYYY-MM-DD`:

<CodeGroup>
  ```bash curl theme={null}
  curl https://api.finzaria.com/v1/transactions \
    -H "Authorization: Bearer $FINZARIA_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "type": "expense",
      "amount": "150.50",
      "date": "2026-07-14",
      "description": "Café",
      "accountId": "ACCOUNT_ID"
    }'
  ```

  ```javascript Node.js theme={null}
  const res = await fetch("https://api.finzaria.com/v1/transactions", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.FINZARIA_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      type: "expense",
      amount: "150.50",
      date: "2026-07-14",
      description: "Café",
      accountId: "ACCOUNT_ID",
    }),
  })
  console.log(await res.json())
  ```
</CodeGroup>

<Tip>
  ¿No tienes un `accountId`? Lístalas con `GET /v1/accounts` o crea una con `POST /v1/accounts`.
  Para no duplicar transacciones si reintentas, usa el header
  [`Idempotency-Key`](/guias/referencia-transversal/idempotencia).
</Tip>

## Siguientes pasos

<CardGroup cols={2}>
  <Card title="Autenticación a fondo" icon="key" href="/guias/autenticacion/api-keys">
    API keys, OAuth y buenas prácticas de seguridad.
  </Card>

  <Card title="Explora la API" icon="code" href="/referencia/overview">
    Todos los endpoints con playground para probarlos aquí mismo.
  </Card>

  <Card title="Maneja errores" icon="triangle-exclamation" href="/guias/referencia-transversal/errores">
    Formato `problem+json` y tabla de códigos estables.
  </Card>

  <Card title="Conecta un agente" icon="robot" href="/mcp/overview">
    Usa Finzaria desde Claude o ChatGPT vía MCP.
  </Card>
</CardGroup>