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

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) y session (un login que devuelve una sesión que caduca).
  • Paginación por offset, por page, por cursor y 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_param si la API lo permite.
  • Fechas sin zona: si el sistema escribe fechas sin zona, di cuál es con source_timezone y usa cursor_type: datetime.
  • No fíes de los filtros: hay API que ignoran en silencio un filtro de fecha. verify_cursor_filter lo 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.