Hacer un conector propio
Un conector es el código que habla con un sistema (un ERP, una tienda, una logística). Weldra publica los suyos con este mismo formato: si tu sistema tiene una API REST con autenticación estándar, basta un manifiesto declarativo, un fichero YAML sin una línea de código. Si no encaja, se escribe un conector en Python con el SDK. En los dos casos el conector es siempre origen y destino: lee y escribe.
Antes de empezar, conviene conocer los conceptos de Empezar con Weldra (conexión, mapeo, tarea, run).
Qué hace Weldra con tu conector
- Lo valida al cargarlo. Un manifiesto con opciones incoherentes no se registra, y falla en el momento, no la primera vez que alguien lo usa.
- Lo identifica por nombre y versión. Una conexión guarda con qué versión del conector se creó.
- Lo publica Weldra. El código de un conector no se sube por la API: un conector de un socio llega como paquete, pasa la suite de pruebas, se revisa y lo publica Weldra. Escribe a hello@weldra.ai para ponerlo en marcha.
¿Declarativo o Python?
Casi nunca hace falta Python. El manifiesto declarativo sabe hacer, entre otras cosas:
- Autenticación sin autenticar,
basic,bearer,api_key(en cabecera o en la query) ysession(un login que devuelve una sesión que caduca). - Paginación por
offset, porpage, porcursory siguiendo un enlace (link), y paginar por clave para no perder registros si el origen borra mientras se lee. - Lectura incremental con un campo de fecha o de versión como cursor, y lectura de registros sueltos por su id.
- Escritura por alta, cambio y borrado, con la versión que devuelve el sistema.
- Avisos entrantes (webhooks) con firma HMAC-SHA256 en hexadecimal o en base64.
- Limitación de ritmo (
rate_limit_rps) y tiempo de espera (timeout).
Hace falta Python cuando el sistema no encaja en eso: el token se calcula con una fórmula, la cuota es una tabla o se mide en coste, lo que se escribe no es JSON (SOAP, XML), los errores llegan con un 200, medio registro vive en otra llamada, o no es una API (por ejemplo, la lectura directa de una base de datos). La regla de la casa es ampliar el formato declarativo antes que escribir Python por pereza.
Un manifiesto completo
Este ejemplo lee y escribe productos de un ERP REST con un token. Está comprobado con el SDK (hub-sdk validate).
name: mi_erp
version: 0.1.0
requires_sdk: ">=0.33,<1"
kind: declarative
label: Mi ERP
config_schema:
properties:
base_url: { type: string, format: uri, title: URL base }
token: { type: string, secret: true, title: Token de la API }
required: [base_url, token]
capabilities: { read: true, write: true, incremental: true }
resources: [products]
spec:
base_url: https://erp.example.com
auth: { type: bearer, token_field: token }
pagination: { type: offset, page_size: 100, limit_param: limit, offset_param: offset }
rate_limit_rps: 5
check_path: /api/ping
resources:
products:
read:
path: /api/products
items_path: data
id_field: sku
revision_field: updated_at
cursor_field: updated_at
cursor_param: modified_after
write:
create: { method: POST, path: /api/products, id_path: sku, revision_path: updated_at }
update: { method: PUT, path: "/api/products/{id}", revision_path: updated_at }
Cabecera del manifiesto
| Campo | Qué es |
|---|---|
name |
El nombre del conector, en minúsculas y con guiones bajos (mi_erp). |
version |
La versión del conector (semver). Un cambio que se publica sube la versión. |
requires_sdk |
Las versiones del SDK que admite, por ejemplo ">=0.33,<1". Si el manifiesto usa una opción que es de una versión posterior a la que admite el rango, no carga. |
kind |
declarative para este formato. |
label |
El nombre que ve la persona en la app. |
config_schema |
Los campos que la persona rellena al crear la conexión: la URL, el token… Es un esquema JSON con properties y required. |
capabilities |
Qué hace: read, write, incremental, webhooks, read_by_ids. Declara solo lo que hayas visto funcionar contra el sistema real. |
resources |
Los nombres de los recursos (productos, pedidos, clientes…). |
spec |
Cómo habla el conector con la API: todo lo que sigue. |
Los secretos: secret: true
En config_schema, un campo con secret: true (el token, la contraseña, un secreto de webhook) se guarda cifrado y la app y la API lo enseñan siempre tapado. Todo campo que sea una credencial lleva secret: true, y las credenciales se leen siempre de la configuración de la conexión por el nombre del campo (token_field, password_field…): nunca van escritas en el manifiesto.
El bloque spec
Autenticación (auth)
type |
Qué manda | Campos |
|---|---|---|
none |
Nada. | — |
basic |
Authorization: Basic |
username_field (por defecto username), password_field (password) |
bearer |
Authorization: Bearer <token> |
token_field (token) |
api_key |
La clave en una cabecera o en la query | key_field (api_key), location (header o query), name (X-API-Key), prefix |
session |
Un login que devuelve una sesión que caduca | login_path, login_method, login_body, session_token_path, session_header, session_prefix, relogin_status, logout_path |
Los campos *_field dicen qué campo de la configuración de la conexión contiene el valor. Con session, el login se hace la primera vez que hace falta y se reutiliza; si el sistema contesta que la sesión caducó (relogin_status, por defecto 401), se vuelve a entrar y se repite la petición una sola vez. Con logout_path, al cerrar el conector se cierra la sesión: importante en sistemas que cobran licencia por sesión abierta. Un ejemplo con sesión, también comprobado:
name: mi_erp_sesion
version: 0.1.0
requires_sdk: ">=0.39,<1"
kind: declarative
label: Mi ERP con sesión
config_schema:
properties:
base_url: { type: string, format: uri }
company_db: { type: string }
username: { type: string }
password: { type: string, secret: true }
required: [base_url, company_db, username, password]
capabilities: { read: true }
resources: [items]
spec:
base_url: https://erp.example.com
auth:
type: session
login_path: /Login
login_body:
CompanyDB: company_db
UserName: username
Password: password
logout_path: /Logout
resources:
items:
read: { path: /Items, items_path: value, id_field: ItemCode }
login_body asocia la clave que espera la API con el campo de la configuración de la conexión. Si el login devuelve la sesión en una cookie, no hace falta session_token_path; si la devuelve en el cuerpo, session_token_path dice dónde y session_header con session_prefix cómo se manda.
Paginación (pagination)
type |
Cómo pide las páginas |
|---|---|
none |
Una sola. |
offset |
limit_param con page_size y offset_param con la posición. |
page |
limit_param con page_size y page_param desde first_page. |
cursor |
cursor_param con el cursor que la API devuelve en next_cursor_path. |
link |
Sigue la URL de la página siguiente, que sale de la cabecera Link o de otra cabecera (next_url_from, next_url_header) o del cuerpo (next_url_path). Se comprueba que apunte al mismo origen que la conexión antes de pedirla. |
Los valores por defecto son page_size: 100, limit_param: limit, offset_param: offset, page_param: page, first_page: 1. Con in: body los parámetros van en el cuerpo, y wrap los anida bajo una clave, para las API que lo exigen. Si la API no aplica la paginación (ignora el offset y repite la misma página), el conector falla con un error claro en vez de dar vueltas.
Lectura (resources.<recurso>.read)
| Campo | Qué dice |
|---|---|
path |
La ruta del listado (obligatorio). Con method: POST si la API lee con POST. |
items_path |
Dónde está la lista en la respuesta, con puntos (data, value, result.items). Si la respuesta no lo trae, es un error, no «cero registros». |
id_field |
El campo con el id del registro (por defecto id). Es la identidad con la que el ledger enlaza el registro. |
revision_field |
La versión del registro en el sistema (updated_at, un ETag): con ella Weldra reconoce su propia escritura cuando el registro vuelve. |
cursor_field y cursor_param |
El campo de cada fila con la marca y el parámetro de la API donde se manda: así cada pasada lee solo lo nuevo. |
cursor_type |
text (por defecto) o datetime: la marca como fecha, con un tope en la hora del sistema para no perder lo editado mientras se leía. Pide source_timezone en spec si el sistema escribe fechas sin zona. |
verify_cursor_filter |
Si la API devuelve algo anterior a lo pedido, no ha aplicado el filtro: error, en vez de leer la tabla entera creyendo que es un delta. |
ids_param |
El parámetro donde se mandan ids sueltos, separados por comas: para relanzar unos registros o reprocesar una incidencia. Con él se declara read_by_ids. |
keyset_param |
Pagina por clave (since_id) en vez de por posición, para que un borrado a mitad de lectura no se salte un registro. La API debe devolver las filas ordenadas por esa clave. |
filter_style y filter_param |
Pasan los filtros del paso como condición OData ($filter). |
path_params |
Una ruta con un trozo variable (/U_{table}) cuyo valor sale de los filtros del paso. |
Escritura (resources.<recurso>.write)
Cada operación (create, update, delete) lleva method (POST, PUT, PATCH o DELETE) y path; el id del registro entra en la ruta como {id}. Para que Weldra enlace el registro creado con su origen, id_path dice dónde viene el id del nuevo registro en la respuesta y revision_path dónde viene su versión. wrap anida el cuerpo bajo una clave ({"product": {...}}). En create, notices_if_missing avisa cuando al destino le puede faltar algo que debe saber el operador (por ejemplo, el impuesto) sin que sea un fallo.
Un recurso puede llevar además un schema con las propiedades que acepta al escribir: el editor de mapeo lo enseña y Weldra comprueba cada cuerpo antes de mandarlo.
Avisos entrantes (webhook)
Si el sistema puede avisar cuando cambia algo, el bloque webhook dice cómo se firma y de dónde sale cada dato:
webhook:
signature: hmac_sha256
header: X-Erp-Signature
secret_field: webhook_secret
event_id_header: X-Erp-Event-Id
resource_header: X-Erp-Resource
action_header: X-Erp-Action
id_path: sku
revision_path: updated_at
La firma se verifica antes de leer el aviso. El secreto sale del campo secret_field de la configuración de la conexión (con secret: true), y se declara webhooks: true en capabilities.
Otros ajustes
base_url, headers (cabeceras fijas), rate_limit_rps (peticiones por segundo como máximo), timeout (30 segundos por defecto), check_path (la ruta con la que se comprueba la conexión), require_https y source_timezone.
Probarlo
Con el SDK (repositorio integrationHub-sdk):
hub-sdk validate manifest.yaml
carga el manifiesto como lo hará Weldra y dice OK o por qué no vale. Para empezar de cero:
hub-sdk new mi_erp --declarative
genera un conector declarativo con su servidor de pruebas falso y sus tests, que ya pasan la suite de contrato. Esa suite es obligatoria: comprueba, sin tocar ningún sistema real, que el conector lee y escribe como Weldra espera.
Si hace falta Python
Un conector en Python implementa tres métodos obligatorios, check(), discover() y read(), y los demás según lo que declare: write() si escribe, verify_webhook() y parse_webhook() si recibe avisos, subscribe() y unsubscribe() para darse de alta en la plataforma. Todo lo que cruza entre Weldra y el conector es JSON puro, y los errores son los del SDK, todos hijos de HubError: Retryable, RateLimited, Fatal, AuthError, NotSupported y FileTooLarge. El SDK trae un cliente HTTP con reintentos y límite de ritmo, la caducidad de tokens OAuth2 y el tapado de claves en errores y registros.
Reglas que cuestan caro
- Pagina sin perder registros: si el origen borra mientras se lee, la paginación por posición se salta uno. Usa
keyset_paramsi la API lo permite. - Fechas sin zona: si el sistema escribe fechas sin zona, di cuál es con
source_timezoney usacursor_type: datetime. - No fíes de los filtros: hay API que ignoran en silencio un filtro de fecha.
verify_cursor_filterlo convierte en un error. - Declara solo lo que hayas visto funcionar: una escritura o un recurso declarados y nunca probados son una promesa falsa.
- Una credencial, siempre
secret: true: y nunca en el manifiesto ni en una URL.
Para integrar sin escribir conectores, mira la API de Weldra o Conectar Weldra a Claude.