Deja que un agente aprovisione todo el pipeline

Un agente no hace nada aquí hasta que le das una clave. Crear la cuenta, verificar el correo del propietario y generar esa clave son pasos en el navegador, y mantenerlo así es justo la idea: quien es titular de la relación de facturación decide lo que puede alcanzar el agente, y el agente tiene una sola credencial que puedes ver en una lista y revocar con un clic.

También significa que no hay que hacer malabares con tokens. El agente nunca toca un endpoint de cuenta, nunca tiene una sesión y no puede ampliar su propio acceso. Todo lo que hace se ejecuta en /v1/* con la clave que le diste.

En el panel, en Organización → Claves de API, Nueva clave te pide un nombre, una caducidad opcional y Acceso a proyectos. Si lo dejas en Todos los proyectos, la clave alcanza todo lo de la organización. Si eliges uno, la clave queda vinculada a él, que es como mantienes una ejecución sin supervisión dentro de un radio de impacto que tú has elegido. El valor aparece una sola vez, así que cópialo directamente en el entorno del agente.

El panel crea y revoca claves, pero no cambia su alcance, así que ampliar o reducir una vinculación más adelante supone generar una clave nueva y retirar la anterior. Los permisos de acción por clave están previstos. Hasta entonces, una clave tiene permisos de miembro: lee todo lo que está en su alcance y crea, actualiza, activa o desactiva, reintenta y repite libremente, mientras que eliminar, revelar y rotar el secreto de firma, rotar la máscara, aprovisionar conectores y cambiar la facturación quedan en manos de un administrador o propietario desde el panel.

Tres llamadas: un origen para recibir, un destino al que enviar y una conexión que los une. La respuesta del origen incluye la ingestUrl, que es lo único que necesita tu proveedor.

# Source. The ingestUrl is what your provider gets.curl -s "$API/v1/sources" -H "authorization: Bearer $SDHK_KEY" \  -H 'content-type: application/json' \  -d '{ "name": "Stripe", "provider": "stripe", "verifierConfig": { "secret": "whsec_..." } }'→ { "id": "src_...", "ingestUrl": "https://sdhk.events/<maskId>", ... } # Destination, then a connection joining the two.curl -s "$API/v1/destinations" -H "authorization: Bearer $SDHK_KEY" \  -H 'content-type: application/json' \  -d '{ "name": "Billing", "type": "http", "url": "https://acme.example/hooks" }' curl -s "$API/v1/connections" -H "authorization: Bearer $SDHK_KEY" \  -H 'content-type: application/json' \  -d '{ "name": "Stripe → Billing", "sourceId": "src_...", "destinationId": "dest_..." }'

Indicar un proveedor conocido trae consigo su esquema de firma, así que el agente aporta un secreto en lugar de investigar un formato de firma. Los orígenes también aceptan correo entrante, que se explica en la guía de correo.

Un agente que solo puede escribir está adivinando. La misma API devuelve cada evento con su resultado de verificación y cada entrega con sus intentos, y eso es lo que permite depurar una ejecución sin supervisión.

Un fallo de firma devuelve al emisor un 401 deliberadamente vago, porque explicarle a un emisor no autenticado qué comprobación falló convertiría la respuesta en un oráculo. En su lugar, el motivo se registra en el evento, donde un agente autenticado puede leerlo.

# Why did nothing arrive?curl -s "$API/v1/events?status=rejected" -H "authorization: Bearer $SDHK_KEY"→ rejectionReason: "signature_mismatch" | "timestamp_out_of_tolerance" | ... # Re-send one failed delivery. Free, creates nothing new.curl -s -X POST "$API/v1/deliveries/dlv_.../retry" -H "authorization: Bearer $SDHK_KEY" # Run an event through its connections again. Billable.curl -s -X POST "$API/v1/events/evt_.../replay" -H "authorization: Bearer $SDHK_KEY"

• /v1/spec.json es el esquema OpenAPI 3 de cada endpoint, y /v1 es la referencia interactiva sobre la misma especificación.
• /llms.txt orienta rápidamente a un modelo. /llms-full.txt es la guía completa, incluida la semántica de los errores y los límites que importan.
• Los errores tienen tipo en lugar de ser prosa. QUOTA_EXCEEDED y RATE_LIMITED son códigos distintos con los que ramificar directamente. Los errores de límite del plan, como el tope de conectores, siguen en FORBIDDEN, con un payload data (limit, current) que lleva los detalles.

• Dale a cada agente su propia clave. Así, revocar una no te cuesta nada más, y la columna de último uso te dice qué agente ha dejado de actuar.
• Vincula la clave a un proyecto salvo que el agente gestione proyectos de verdad. Es el único alcance disponible hoy y no se puede cambiar una vez generada la clave.
• Ramifica según el código de error, nunca según el texto del mensaje. Los mensajes están escritos para personas y el 401 de la ingesta no da información a propósito.
• Consulta ?status=rejected antes de reenviar nada. Una firma que nunca se verificó tampoco se verificará en el segundo intento.
• Si falló un solo consumidor, mejor reintentar la entrega que repetir el evento. El reintento es gratis y la repetición se factura.