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

# Ejecutar con el SDK de Node.js

> Invoca un deployment de flujo de trabajo desde Node.js o TypeScript con el paquete @fetch-hive/sdk

# Ejecutar con el SDK de Node.js

Usa el paquete oficial `@fetch-hive/sdk` cuando quieras invocar un deployment de flujo de trabajo desde Node.js o TypeScript. El SDK envuelve el endpoint público [`POST /v1/workflow/invoke`](../api-reference/workflows/invoke), maneja la autenticación y admite tanto respuestas directas como entrega por callback.

## Instalación

```bash theme={null}
npm install @fetch-hive/sdk
# or
yarn add @fetch-hive/sdk
# or
pnpm add @fetch-hive/sdk
```

El SDK está dirigido a Node.js 18+ (usa el `fetch` global) y viene con tipos TypeScript.

## Autenticación

Configura la variable de entorno `FETCH_HIVE_API_KEY` con tu clave de API del workspace:

```bash theme={null}
export FETCH_HIVE_API_KEY=fhk_...
```

```typescript theme={null}
import { FetchHive } from '@fetch-hive/sdk';

const client = new FetchHive();
```

O pasa la clave explícitamente:

```typescript theme={null}
const client = new FetchHive({ apiKey: 'fhk_...' });
```

Consulta [API Keys](../workspace/api-keys) para saber cómo crear y rotar claves.

## Ejemplo básico

Ejecuta un deployment de flujo de trabajo directamente. La llamada se bloquea hasta que el flujo de trabajo termina:

```typescript theme={null}
import { FetchHive } from '@fetch-hive/sdk';

const client = new FetchHive();

const run = await client.invokeWorkflow({
  deployment: 'YOUR_DEPLOYMENT_NAME',
  variant: 'YOUR_VARIANT_NAME',
  inputs: { topic: 'State of enterprise AI in 2026' },
});

console.log(run.status);
console.log(run.output);
```

Consulta la [forma de respuesta directa](../api-reference/workflows/invoke#response).

## Referencia del método

| Campo        | Tipo                                                  | Requerido | Descripción                                                                                                                                      |
| ------------ | ----------------------------------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `deployment` | `string`                                              | Sí        | El nombre del deployment del flujo de trabajo                                                                                                    |
| `variant`    | `string`                                              | No        | El nombre de la variante del deployment                                                                                                          |
| `inputs`     | `Record<string, unknown>`                             | No        | Pares clave-valor para las variables definidas en el paso **Start**                                                                              |
| `async`      | `{ enabled: boolean, callback_url?: string }`         | No        | Ajustes de entrega por callback                                                                                                                  |
| `user`       | `string`                                              | No        | Identificador opaco de quien llama, expuesto en [User Tracking](../user-tracking/overview)                                                       |
| `metadata`   | `Record<string, string \| number \| boolean \| null>` | No        | Metadata plana definida por quien llama, para auditoría y filtrado de registros. Consulta [Metadata de invoke](../user-tracking/invoke-metadata) |

## Manejo de la respuesta

```typescript theme={null}
const run = await client.invokeWorkflow({
  deployment: 'my-workflow',
  variant: 'default',
});

console.log(run.status);       // "completed" | "failed" | "running" | "queued"
console.log(run.output);       // final workflow output
console.log(run.request_id);   // use this to look up the run in Logs
```

## Entrega por callback

Pasa un bloque `async` para devolver respuesta inmediatamente y hacer que Fetch Hive llame a tu URL de callback cuando la ejecución termine:

```typescript theme={null}
const run = await client.invokeWorkflow({
  deployment: 'YOUR_DEPLOYMENT_NAME',
  variant: 'YOUR_VARIANT_NAME',
  inputs: { topic: 'State of enterprise AI in 2026' },
  async: { enabled: true, callback_url: 'https://example.com/callback' },
});

console.log('Queued:', run.status);
console.log('Webhook secret:', run.webhook_secret);
```

Almacena el `webhook_secret` para que puedas verificar la firma en el callback entrante. Consulta [Entrega por callback y disparadores de webhook](./async-and-webhooks) para el flujo de verificación y la forma del payload firmado.

## Configuración

| Opción    | Predeterminado                   | Descripción                       |
| --------- | -------------------------------- | --------------------------------- |
| `apiKey`  | `process.env.FETCH_HIVE_API_KEY` | Token bearer del dashboard        |
| `baseURL` | `https://api.fetchhive.com/v1`   | Sobrescribe la URL base de la API |

```typescript theme={null}
const client = new FetchHive({
  apiKey: 'fhk_...',
  baseURL: 'https://api.fetchhive.com/v1',
});
```

Para solicitudes directas de flujos de trabajo de larga duración, prefiere `async: { enabled: true, ... }` en lugar de aumentar los timeouts del cliente.

## Errores

Las respuestas distintas a 2xx lanzan un `Error` cuyo mensaje incluye el código de estado y el cuerpo de la respuesta:

```typescript theme={null}
try {
  const run = await client.invokeWorkflow({
    deployment: 'my-workflow',
    variant: 'default',
  });
} catch (err) {
  console.error('Fetch Hive error:', err);
}
```

Consulta [Manejo de errores](./error-handling) para los casos de fallo específicos del flujo de trabajo y [Errors and Rate Limits](../api-reference/errors-and-rate-limits) para el significado de los códigos de estado HTTP.

## Enlaces

* [Package on npm](https://www.npmjs.com/package/@fetch-hive/sdk)
* [Source on GitHub](https://github.com/Fetch-Hive/nodejs-sdk)

## Siguientes pasos

* [Entrega por callback y disparadores de webhook](./async-and-webhooks) - Verifica las firmas de callback
* [Ejecutar con API](./run-with-api) - El mismo flujo con cURL
* [Ejecutar con el SDK de Python](./run-with-python-sdk)
* [Ejecutar con el SDK de Ruby](./run-with-ruby-sdk)
* [Ejecutar con el SDK de PHP](./run-with-php-sdk)
* [Invoke Workflow](../api-reference/workflows/invoke) - Referencia completa del endpoint