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) yedit(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/medice 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" }
limitpor defecto es 50; si pides más de 200, se recorta a 200; menos de 1 es un422.- Para la página siguiente, reenvía
next_cursortal cual en?cursor=. El cursor es opaco: no lo construyas ni lo interpretes. next_cursoresnullen 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. Uneventsvacío escucha todos los eventos que salen. - Firma. Con secreto, cada aviso lleva
X-Weldra-Timestamp(segundos Unix del envío) yX-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 firmasv1separadas 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.