Saltar al contenido principal

​
Ejecutar con el SDK de PHP

Usa el paquete oficial de Composer fetch-hive/sdk cuando quieras invocar un deployment de flujo de trabajo desde PHP. El SDK envuelve el endpoint público POST /v1/workflow/invoke, maneja la autenticación y admite tanto respuestas directas como entrega por callback.

​
Instalación

composer require fetch-hive/sdk
El SDK requiere PHP 8.1+ y usa Guzzle como su cliente HTTP.

​
Autenticación

Configura la variable de entorno FETCH_HIVE_API_KEY con tu clave de API del workspace (el cliente la lee automáticamente): 
export FETCH_HIVE_API_KEY=fhk_...

<?php
require_once 'vendor/autoload.php';

use FetchHive\Sdk\FetchHive;

$client = new FetchHive();
O pasa la clave explícitamente: 
$client = new FetchHive(['api_key' => 'fhk_...']);
Consulta 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: 
<?php
require_once 'vendor/autoload.php';

use FetchHive\Sdk\FetchHive;

$client = new FetchHive();

$run = $client->invokeWorkflow([
    'deployment' => 'YOUR_DEPLOYMENT_NAME',
    'variant'    => 'YOUR_VARIANT_NAME',
    'inputs'     => ['topic' => 'State of enterprise AI in 2026'],
]);

echo $run['run_status'] . PHP_EOL;
echo $run['output'];
Consulta la forma de respuesta directa.

​
Referencia del método

ClaveTipoRequeridoDescripción
deploymentstringSíEl nombre del deployment del flujo de trabajo
variantstringNoEl nombre de la variante del deployment
inputsarrayNoPares clave-valor para las variables definidas en el paso Start
async_modeboolNoCuando es true, devuelve respuesta inmediatamente y entrega el resultado mediante callback firmado
callback_urlstringNoRequerido cuando async_mode: true - la URL HTTPS de callback a la que llamar cuando la ejecución termine
userstringNoIdentificador opaco de quien llama, expuesto en User Tracking
metadataarrayNoMetadata plana definida por quien llama, para auditoría y filtrado de registros. Consulta Metadata de invoke
invokeWorkflow construye el cuerpo de la solicitud por ti. Cuando pasas async_mode: true, el SDK envía: 
{
  "async": { "enabled": true, "callback_url": "https://example.com/webhook" }
}

​
Manejo de la respuesta

$run = $client->invokeWorkflow([
    'deployment' => 'my-workflow',
    'variant'    => 'default',
]);

echo $run['run_status'];      // "completed" | "failed" | "running" | "queued"
echo $run['output'];          // final workflow output
echo $run['request_id'];      // use this to look up the run in Logs

​
Entrega por callback

Pasa async_mode: true para devolver respuesta inmediatamente y hacer que Fetch Hive llame a tu URL de callback cuando la ejecución termine: 
$run = $client->invokeWorkflow([
    'deployment'   => 'YOUR_DEPLOYMENT_NAME',
    'variant'      => 'YOUR_VARIANT_NAME',
    'inputs'       => ['topic' => 'State of enterprise AI in 2026'],
    'async_mode'   => true,
    'callback_url' => 'https://example.com/callback',
]);

echo 'Queued: ' . $run['run_status'] . PHP_EOL;
echo '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 para el flujo de verificación y la forma del payload firmado.

​
Configuración

OpciónPredeterminadoDescripción
api_keyvariable de entorno FETCH_HIVE_API_KEYToken bearer del dashboard
base_urlhttps://api.fetchhive.com/v1Sobrescribe la URL base de la API
timeout120Timeout de la solicitud en segundos - aumenta para solicitudes directas de flujos de trabajo de larga duración
$client = new FetchHive([
    'api_key'  => 'fhk_...',
    'base_url' => 'https://api.fetchhive.com/v1',
    'timeout'  => 600.0,
]);

​
Errores

Las respuestas distintas a 2xx lanzan FetchHive\Sdk\Exception\ApiException con el código de estado y el cuerpo de la respuesta: 
use FetchHive\Sdk\Exception\ApiException;

try {
    $run = $client->invokeWorkflow([
        'deployment' => 'my-workflow',
        'variant'    => 'default',
    ]);
} catch (ApiException $e) {
    error_log('Fetch Hive error: ' . $e->getMessage());
}
Consulta Manejo de errores para los casos de fallo específicos del flujo de trabajo y Errors and Rate Limits para el significado de los códigos de estado HTTP.

​
Enlaces

​
Siguientes pasos