Saltar al contenido
Empezar gratis
Índice de la documentación

La API de Weldra

La API REST de Weldra hace lo mismo que la app: crear conexiones, proyectos, mapeos y tareas, lanzar runs y consultar el resultado. Es la que usa la propia app, así que valen los mismos permisos, el mismo aislamiento entre cuentas y los mismos topes de tu plan. Todas las llamadas van a https://app.weldra.ai/api/v1, en JSON.

Si vienes de cero, empieza por Empezar con Weldra, que explica los conceptos. Para usar tu cuenta desde un asistente, mira Conectar Weldra a Claude.

Autenticación

Para un script, un ERP o cualquier máquina, se usa una clave API en la cabecera X-API-Key:

curl -s -H "X-API-Key: $WELDRA_API_KEY" https://app.weldra.ai/api/v1/auth/me
  • La clave se crea en la app, en Organización, pestaña API keys, por una persona que administra la cuenta. Ponle una etiqueta y, si puede ser, una caducidad. Su valor se muestra una sola vez: guárdalo en una variable de entorno o en un gestor de contraseñas, no en un fichero del proyecto. Weldra solo guarda su huella.
  • Una clave lleva uno o varios permisos: read (consultar), operate (lanzar, reintentar, parar) y edit (crear y cambiar). Se crea con un preajuste: solo lectura, lanzar y reprocesar, o todo menos administrar. Una clave nunca administra la cuenta ni la facturación.
  • Una petición es de una máquina o de una persona, nunca de las dos: mandar a la vez la cookie de sesión de la app y una clave da un 400.
  • Sin credencial, la respuesta es un 401; con una clave que no vale (inexistente, revocada, caducada o de una cuenta en baja), también.
  • GET /auth/me dice con qué credencial entras y qué permisos tiene.
  • Una persona entra en la app con un código que le llega por correo, no con contraseña.

Cada respuesta lleva la cabecera X-Request-Id. Si abres una incidencia con soporte, da ese valor: con él se encuentra tu petición en el registro de la cuenta.

Las rutas principales

Todas cuelgan de /api/v1. La columna de permiso es el mínimo que pide la clave.

Para qué Ruta Permiso
Quién soy y qué puedo GET /auth/me cualquiera
Los conectores disponibles GET /connectors read
Listar y crear conexiones GET /connections, POST /connections read; edit para crear
Comprobar una conexión POST /connections/{id}/check read
Ver unos registros de un sistema, sin escribir nada POST /connections/{id}/sample, POST /explore read
Proyectos GET /projects, POST /projects read; edit para crear
Mapeos: probar, listar y guardar POST /mappings/preview, GET /mappings, POST /mappings read; edit para guardar
Recetas (tareas prehechas) GET /recipes, POST /recipes/{id}/instantiate read; edit para crear la tarea
Tareas: validar, listar y guardar POST /tasks/validate, GET /tasks, POST /tasks read; edit para guardar
Lanzar una tarea POST /tasks/{id}/run operate
Runs: listar y ver el detalle GET /runs, GET /runs/{id} read
Incidencias (registros que no se pudieron escribir) GET /dead-letters, POST /dead-letters/{id}/retry read; operate para reintentar
El ledger: qué se escribió GET /ledger read
Alertas abiertas de la cuenta GET /alerts read
Registro de actividad GET /logs read
Uso del plan GET /organization/usage read
Suscripciones de avisos GET /webhook-subscriptions, POST /webhook-subscriptions read; edit para crear

Hay muchas más: grupos de tareas, exportaciones, notificaciones, avisos entrantes por conexión… Si necesitas una que no está aquí, escribe a hello@weldra.ai.

Un recorrido corto

Con una clave con permisos read, operate y edit. Las salidas son de una cuenta de pruebas.

1. Crear una conexión. El nombre del conector y los campos de config que pide salen de GET /connectors. Los campos que el conector marca como secretos se guardan cifrados y vuelven tapados:

curl -s -X POST https://app.weldra.ai/api/v1/connections \
  -H "X-API-Key: $WELDRA_API_KEY" -H "Content-Type: application/json" \
  -d '{"label":"erp","connector_name":"<nombre del conector>","environment":"sandbox","config":{"base_url":"<url>","token":"<token>"}}'

environment es production si no lo dices: una tarea que escribe en una conexión de producción no se lanza a mano sin confirmarlo.

2. Un proyecto que ata roles a conexiones:

curl -s -X POST https://app.weldra.ai/api/v1/projects \
  -H "X-API-Key: $WELDRA_API_KEY" -H "Content-Type: application/json" \
  -d '{"name":"ERP a tienda","roles":{"erp":1,"shop":2}}'

3. Probar un mapeo antes de guardarlo, con filas de ejemplo (POST /mappings/preview):

{"spec": {"fields": {"title": {"from": "Nombre"}}}, "rows": [{"Nombre": "Camiseta azul"}]}

y la respuesta es [{"title": "Camiseta azul"}]. Se guarda con POST /mappings, con project_id, name y spec. Un mapeo es del proyecto en el que se creó.

4. Una tarea: un grafo de pasos y flechas. En connection, "$erp" es el rol del proyecto:

{"project_id": 1, "name": "productos", "schedule_seconds": 900,
 "definition": {
   "steps": [
     {"id": "read",  "type": "read",      "connection": "$erp",  "resource": "products"},
     {"id": "map",   "type": "transform", "mapping_ref": {"name": "erp-products"}},
     {"id": "write", "type": "write",     "connection": "$shop", "resource": "products", "mode": "create_update"}],
   "edges": [["read", "map"], ["map", "write"]]}}

Se comprueba sin guardar con POST /tasks/validate ({"ok": true, "problems": []} si está bien) y se guarda con POST /tasks. El horario es uno: o un intervalo (schedule_seconds) o una expresión cron (schedule_cron con su schedule_timezone). Por defecto la lectura es incremental y no reescribe lo que no ha cambiado.

5. Lanzarla y mirar el run:

curl -s -X POST -H "X-API-Key: $WELDRA_API_KEY" https://app.weldra.ai/api/v1/tasks/1/run
# {"run_id": 1}   (202)
curl -s -H "X-API-Key: $WELDRA_API_KEY" https://app.weldra.ai/api/v1/runs/1

GET /runs/{id} da el estado por paso y los contadores: leídos, transformados, creados, actualizados, omitidos y fallidos. Si la tarea ya tiene un run en marcha, la respuesta es un 409 con context.code igual a task_busy y el active_run_id que la ocupa. Si la tarea escribe en una conexión de producción, el 409 es ConfirmationRequired: repite la misma petición con ?confirm_production=true si de verdad quieres escribir ahí.

Paginación

Las listas devuelven un sobre con los elementos y el cursor de la página siguiente:

{ "items": [ ], "next_cursor": "aWQ6NDI" }
  • limit por defecto es 50; si pides más de 200, se recorta a 200; menos de 1 es un 422.
  • Para la página siguiente, reenvía next_cursor tal cual en ?cursor=. El cursor es opaco: no lo construyas ni lo interpretes.
  • next_cursor es null en la última página.
  • El cursor no recuerda los filtros: repite los mismos en cada petición de una misma recorrida.
  • Unas pocas listas devuelven un array sin paginar, como GET /connectors.

Errores

Compara siempre el campo error, no el texto de detail, que está pensado para personas y puede cambiar. Un error de negocio de Weldra tiene esta forma:

{
  "error": "Conflict",
  "detail": "La tarea ya tiene un run en marcha; espera a que termine.",
  "context": {"code": "task_busy", "task_id": 1, "active_run_id": 3},
  "request_id": "req_dc6eed"
}
HTTP error Cuándo
400 BadRequest Lo que se pide no tiene sentido (por ejemplo, cookie y clave a la vez).
401 Unauthorized Credencial que no vale.
403 Forbidden Falta un permiso (detail dice cuál), o la cuenta está en baja.
404 NotFound No existe, o es de otra cuenta: no se distingue.
409 Conflict El estado actual no permite la acción. El código estable va en context.code (no en la raíz del cuerpo).
409 ConfirmationRequired Se puede hacer, pero hace falta confirmarlo: escribir en producción o borrar en el destino.
413 PayloadTooLarge El cuerpo pasa del tope: 2 MiB en la API.
422 InvalidDefinition La petición tiene forma pero no pasa el negocio: una tarea o un mapeo que no valida.
429 TooManyRequests Demasiadas veces en poco tiempo; la cabecera Retry-After dice cuántos segundos esperar.
500 InternalError Un fallo no controlado: anota el request_id y avisa a soporte.

No todos los errores llevan ese sobre. Un 401 por falta de credencial, un 404 de una ruta que no existe y los errores de la puerta de avisos entrantes llevan solo {"detail": "texto"}; y un 422 de validación de la forma de la petición lleva {"detail": [ ... ]}, con loc para cada campo. Si el cuerpo tiene la clave error, es un error de Weldra. Un campo que parece un secreto sale como *** en la validación.

Un cliente que reintente después de un 429 debe esperar esos segundos: reintentar antes puede contar como otro intento.

Avisos de Weldra a tu servidor

Si prefieres que Weldra te avise en vez de preguntar, crea una suscripción:

POST /api/v1/webhook-subscriptions
{"url": "https://tu-servidor.example.com/hooks/weldra", "events": ["run.finished", "run.failed"], "secret": "<secreto largo y aleatorio>"}

Cuando pasa algo de lo que escuchas (un run termina, falla un registro…), Weldra manda un POST con cuerpo JSON a tu URL. Lo que conviene saber:

  • Pon siempre secret. Sin él, Weldra no firma el aviso y no hay otra forma de saber que viene de Weldra. El secreto se guarda cifrado y no se puede leer de vuelta. Un events vacío escucha todos los eventos que salen.
  • Firma. Con secreto, cada aviso lleva X-Weldra-Timestamp (segundos Unix del envío) y X-Weldra-Signature: v1=<HMAC-SHA256>, calculado con tu secreto sobre "<marca>." seguido de los bytes exactos del cuerpo. Durante una rotación de secreto, la cabecera lleva dos firmas v1 separadas por coma: basta que case una.
  • Reintentos y cortacircuitos. Cada entrega se intenta hasta 8 veces en total (el envío y sus reintentos) con una espera creciente, y una suscripción que falla muchas veces seguidas se desactiva.
  • Sin garantía de entrega única. Un aviso puede llegar repetido y sin orden garantizado: deduplica por X-Hub-Delivery. Contesta rápido con un 2xx y procesa después.

Un verificador mínimo, con solo la librería estándar de Python:

import hashlib
import hmac


def verificar(secreto: bytes, cabeceras: dict[str, str], cuerpo: bytes, ahora: int, tolerancia: int = 300) -> bool:
    try:
        h = {k.lower(): v for k, v in cabeceras.items()}
        marca = h["x-weldra-timestamp"]
        if not (marca.isascii() and marca.isdigit()) or abs(ahora - int(marca)) > tolerancia:
            return False
        esperada = hmac.new(secreto, f"{marca}.".encode() + cuerpo, hashlib.sha256).hexdigest().encode()
        return any(p.strip().startswith("v1=") and hmac.compare_digest(p.strip()[3:].encode(), esperada)
                   for p in h["x-weldra-signature"].split(","))
    except Exception:
        return False

Lee el cuerpo como bytes, tal como llegó, y comprueba la firma antes de interpretar el JSON. Si no casa, contesta 401.

Avisos de tu sistema a Weldra

Si el sistema que lees puede avisar cuando cambia algo, Weldra tiene una puerta para recibir ese aviso: cada conexión que lo admite tiene su propia dirección, con un token dentro, que se enciende y se copia en la app (pantalla Webhooks). Esa dirección es un secreto: no la compartas ni la pegues en un correo.

Qué más

  • Una cuenta se puede exportar entera, en un fichero, desde la app (Organización).
  • Un socio (por ejemplo una plataforma de comercio) tiene su propia clave y su propia puerta, con otras rutas; si es tu caso, escribe a hello@weldra.ai.
  • Para hacer un conector para un sistema que no está, mira Hacer un conector propio.