> ## Documentation Index > Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt > Use this file to discover all available pages before exploring further. # Trabajar con datos de solicitud y respuesta > Mueve valores hacia la solicitud de un nodo executor y desde su respuesta. Declara los mapeos, cambia la forma de los valores en tránsito y revisa la solicitud armada antes de llamar al servicio. Un nodo executor envía datos a un servicio externo y recibe datos de vuelta. El servicio nombra sus propios campos, y tu workflow nombra los suyos. Los mapeos son la forma de mover valores entre ambos. Son una lista de entradas de origen a destino en el nodo. Flowker los aplica a la solicitud antes de la llamada y a la respuesta después de ella. Necesitas esto cuando la forma que lleva tu workflow no es la forma que acepta el servicio. Un ejemplo es un documento que debe viajar sin puntuación. Otro es un monto que pertenece a un objeto anidado, o una puntuación que un nodo posterior lee con un nombre corto. ## Antes de empezar *** * Una configuración de proveedor para el servicio, y un nodo executor que la referencia. Consulta [Referenciar la configuración de proveedor desde un nodo del workflow](/es/products/flowker/integration-guide#step-3-reference-the-provider-configuration-from-a-workflow-node). * Los nombres de campo que espera el servicio. Cuando el documento OpenAPI del servicio está en el registro, [Derivar un esquema de operación](/es/reference/products/flowker/derive-openapi-operation-schema) devuelve `inputSchema` (el cuerpo de la solicitud de la operación) y `outputSchema` (su respuesta de éxito). Ambos te dan los nombres de campo que escribes como destinos y orígenes de mapeo. * Un workflow en estado `draft`. Un workflow activo está bloqueado, así que usa [Pasar un workflow a borrador](/es/reference/products/flowker/move-workflow-to-draft) antes de editar un nodo, y actívalo de nuevo después. No envíes `executorId` en un nodo que llama a una operación de un documento OpenAPI cargado. Ese nodo nombra la operación con `operation_path` y `operation_method`. Flowker completa el `executorId` por ti, a partir de la configuración de proveedor a la que apunta el nodo, antes de validar el workflow. Lo hace cuando creas el workflow y cuando lo actualizas. [Conectar tu propia API](/es/products/flowker/connecting-your-own-api) recorre toda esa vía. Los nodos de esta página nombran `http`, el conector HTTP genérico, que sí necesita un `executorId` explícito. ## Paso 1: conoce qué puede leer un mapeo *** Cada mapeo lee del contexto del workflow, un único objeto JSON que crece a medida que avanza la ejecución: | Ruta | Qué contiene | | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `workflow` | El payload del trigger: el `inputData` de una solicitud de ejecución, o el cuerpo que recibió una ruta de webhook. Una ruta de webhook también agrega `workflow._webhook` con los metadatos de la llamada — consulta [Metadatos de webhook](/es/products/flowker/integration-guide#webhook-metadata). | | `execution.id` | El identificador de la ejecución. | | `execution.startedAt` | Cuándo empezó la ejecución, en UTC. | | `` | La salida de cada nodo que se completó, bajo el id de ese nodo. | Referencia un valor por su ruta desde una de esas claves de nivel superior: | Origen | Qué selecciona | | ------------------------------ | --------------------------------------------------- | | `workflow.customer.document` | Un campo anidado del payload del trigger. | | `workflow.items[0].sku` | Un elemento de un arreglo. | | `workflow.items[*].sku` | El mismo campo en cada elemento, como un arreglo. | | `workflow` | Todo el payload del trigger como un objeto. | | `score-transaction.body.score` | Un campo de la salida del nodo `score-transaction`. | Un `source` de mapeo es una ruta simple. No lo envuelvas en `${...}`. Las llaves pertenecen a los campos de plantilla del nodo (`body`, `headers`, `query`, `path`), y dentro de un mapeo Flowker lee una cadena `${...}` como un nombre de ruta literal que no selecciona nada. ## Paso 2: declara el mapeo de entrada *** Los mapeos de entrada viven en un arreglo `inputMapping` dentro del objeto `data` del nodo executor. Cada entrada mueve un valor al cuerpo de la solicitud saliente. | Campo | Tipo | Obligatorio | Descripción | | ---------------- | ------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `source` | string | Sí | La ruta del contexto del workflow que se lee. | | `target` | string | Sí | La ruta del cuerpo de la solicitud saliente que se escribe. Un destino con puntos crea el objeto anidado — `payment.amount` envía `{"payment":{"amount":…}}`. | | `transformation` | object | No | Un cambio que se aplica al valor después de que aterriza en el destino. Consulta el [Paso 4](#step-4-reshape-a-value-on-its-way-through). | | `required` | boolean | No | Si la ruta de origen debe existir. El valor predeterminado es `false`. Aplica a todo el nodo — mira abajo. | El resultado mapeado **es** el cuerpo de la solicitud. Escribe cada `target` exactamente como el servicio espera recibirlo: no hay objeto envolvente ni prefijo que agregar. ```json theme={null} { "id": "score-transaction", "type": "executor", "name": "Score transaction", "position": { "x": 200, "y": 0 }, "data": { "executorId": "http", "providerConfigId": "019c96a0-0ac0-7de9-9f53-9cf842a2ee5a", "method": "POST", "path": "/score-transaction", "inputMapping": [ { "source": "workflow.transactionId", "target": "reference" }, { "source": "workflow.amount", "target": "payment.amount" }, { "source": "workflow.customer.document", "target": "payment.document" } ] } } ``` Con un payload del trigger de `{"transactionId":"txn-98765","amount":1500.00,"customer":{"document":"12345678900"}}`, el servicio recibe: ```json theme={null} { "reference": "txn-98765", "payment": { "amount": 1500.00, "document": "12345678900" } } ``` ### Cuando un origen no selecciona nada Una ruta de origen ausente del contexto no es un error. Flowker igual escribe el destino, con el valor `null`, y la solicitud sale. Define `required: true` cuando el nodo no debe llamar al servicio sin un valor. Flowker entonces revisa cada ruta de origen de ese nodo antes de armar la solicitud, y hace fallar el paso cuando alguna de ellas está ausente. La ejecución se detiene con `FLK-0504` y el paso informa `input transformation failed`. `required` aplica al nodo, no a la única entrada que lo lleva. Si alguna entrada del `inputMapping` de un nodo define `required: true`, cada ruta de origen de ese arreglo debe resolverse. Para mantener algunos campos opcionales, deja `required` desactivado en todo el nodo. Dale a cada `target` una sola entrada. Cuando dos entradas escriben el mismo destino, gana la última. ## Paso 3: decide qué arma el cuerpo de la solicitud *** Un nodo tiene tres fuentes para el cuerpo de una solicitud. Solo `data.body` es exclusivo: cuando está presente, es todo el cuerpo. Sin él, Flowker compone el cuerpo a partir de las otras dos fuentes, con la superposición del mapeo escrita sobre los literales de `config`: Una plantilla de cuerpo explícita gana de plano. Flowker resuelve sus referencias `${...}` contra el contexto del workflow y envía el resultado. Mientras `data.body` esté presente, `inputMapping`, `transforms` y `config` no aportan nada al cuerpo. Cada referencia `${...}` de aquí debe resolverse. Una que no lo hace hace fallar el nodo con `FLK-0143`, antes de que salga cualquier llamada (lo contrario de un origen de mapeo, que se resuelve como `null`). Usa `data.body` cuando un valor ausente debe detener el workflow, y un mapeo cuando la solicitud debe salir de todos modos. En caso contrario, Flowker arma una superposición a partir de `inputMapping`. Cuando `inputMapping` está vacío, arma la superposición a partir de `transforms`. Los dos son mutuamente excluyentes: un nodo con al menos una entrada de `inputMapping` nunca corre sus `transforms` sobre la entrada. Los valores literales de `data.config` siembran el cuerpo. Con una superposición presente, los literales son la base y la superposición gana en cualquier clave que ambos definan. Por eso un nodo puede combinar valores fijos con valores mapeados. Sin superposición, los literales son el cuerpo por sí solos. El transporte nunca se vuelve contenido del cuerpo. Antes de que `config` pueda sembrar el cuerpo, Flowker le quita estos nombres: `method`, `path`, `url`, `endpointName`, `query`, `headers`, `auth`, `retry`, `timeout`, `timeout_seconds`, `request_format`, `success_status_codes`, `allowedHosts` y `allowedPrivateHosts`. Por eso un nodo que deja el transporte en `config` por error no envía nada de eso al destino. Un bloque `auth` puesto ahí nunca puede viajar como contenido de la solicitud. El nodo lee su propio transporte desde el nivel superior de su objeto `data`: `path`, `endpointName`, `method`, `headers`, `query`, `auth`, `timeout_seconds`, `retry`, `success_status_codes` y `request_format`. Las listas de hosts salientes permitidos no están entre ellos: configuras `allowedHosts` y `allowedPrivateHosts` en la configuración de proveedor, donde cada una aplica a cada nodo que llama a través de ella. ```json theme={null} { "data": { "executorId": "http", "providerConfigId": "019c96a0-0ac0-7de9-9f53-9cf842a2ee5a", "method": "POST", "path": "/score-transaction", "config": { "channel": "web", "payment": { "currency": "BRL" } }, "inputMapping": [ { "source": "workflow.transactionId", "target": "reference" }, { "source": "workflow.amount", "target": "payment.amount" } ] } } ``` Los literales y los valores mapeados se fusionan, y el anidamiento se fusiona con el anidamiento: ```json theme={null} { "channel": "web", "reference": "txn-98765", "payment": { "currency": "BRL", "amount": 1500.00 } } ```

Paso 4: cambia la forma de un valor en tránsito

*** Cuando el servicio necesita un valor en otra forma, adjunta una `transformation` a la entrada del mapeo. Se aplica al valor después de que aterriza en el destino. | Tipo | Qué hace | Config | | ------------------- | ----------------------------------------- | -------------------------------------------- | | `remove_characters` | Quita del texto los caracteres indicados. | `characters` — los caracteres que se quitan. | | `add_prefix` | Pone texto delante del valor. | `prefix` — el texto que se agrega. | | `add_suffix` | Pone texto después del valor. | `suffix` — el texto que se agrega. | | `to_uppercase` | Convierte el texto a mayúsculas. | — | | `to_lowercase` | Convierte el texto a minúsculas. | — | Estas cinco son el conjunto completo. Un `type` fuera de él falla cuando guardas el workflow, con `FLK-0140`. Dos reglas para escribirlas: * Actúan sobre texto. Un valor que no es texto llega al destino sin cambios. * Los valores `prefix` y `suffix` necesitan al menos un carácter cada uno, y un solo espacio cuenta. El valor `characters` necesita al menos un carácter que no sea un espacio, una tabulación ni un salto de línea. Un valor que no cumple esto hace fallar el paso en tiempo de ejecución con `FLK-0504`. ```json theme={null} { "inputMapping": [ { "source": "workflow.customer.document", "target": "payer.document", "transformation": { "type": "remove_characters", "config": { "characters": ".-/" } } }, { "source": "workflow.customer.name", "target": "payer.name", "transformation": { "type": "to_uppercase" } }, { "source": "workflow.transactionId", "target": "payer.reference", "transformation": { "type": "add_prefix", "config": { "prefix": "BR-" } } } ] } ``` Desde `{"customer":{"document":"123.456.789-00","name":"ada lovelace"},"transactionId":"txn-98765"}`, el nodo envía: ```json theme={null} { "payer": { "document": "12345678900", "name": "ADA LOVELACE", "reference": "BR-txn-98765" } } ``` ### Transformaciones de documento completo Para el trabajo que el mapeo entrada por entrada no expresa (combinar dos campos, elegir el primer valor presente, rellenar un valor predeterminado), declara en su lugar un arreglo `transforms`. Cada operación lee todo el contexto del workflow y escribe toda la superposición. Flowker acepta `shift` (mover o renombrar), `concat` (unir valores), `coalesce` (primer valor presente), `default` (rellenar una clave ausente), `extract` (subir un subárbol a la raíz), `delete` (quitar una clave), `timestamp`, `uuid` y `pass`. Los cinco tipos de transformación de arriba también están disponibles aquí. Como operaciones, toman la ruta de destino de la especificación en `path`. ```json theme={null} { "data": { "executorId": "http", "providerConfigId": "019c96a0-0ac0-7de9-9f53-9cf842a2ee5a", "transforms": [ { "operation": "shift", "spec": { "reference": "workflow.transactionId", "payment.amount": "workflow.amount" } }, { "operation": "default", "spec": { "channel": "web" } } ] } } ``` El nodo envía: ```json theme={null} { "reference": "txn-98765", "payment": { "amount": 1500.00 }, "channel": "web" } ``` Una operación puede definir `require: true` para exigir que exista cada ruta que su `spec` nombra, igual que funciona `required` en una entrada de mapeo. `transforms` corre solo cuando el nodo no tiene `inputMapping`. Usa uno u otro en un nodo dado, nunca ambos. ## Paso 5: lee de vuelta la respuesta *** Los mapeos de salida extraen campos de la respuesta y los guardan en el contexto del workflow bajo el id del nodo, para que los nodos posteriores lean nombres cortos y estables. Decláralos en un arreglo `outputMapping` dentro del `data` del nodo, con los mismos cuatro campos de entrada que un mapeo de entrada. Un `source` de salida es una ruta hacia el envelope de la respuesta, no hacia el cuerpo de la respuesta: | Ruta | Qué contiene | | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `status` | El código de estado HTTP. | | `status_text` | La línea de estado HTTP, como `200 OK`. | | `url` | La URL que solicitó Flowker, con la query string que armó. | | `headers` | Los headers de la respuesta, como un objeto clave-valor bajo sus nombres canónicos, como `Content-Type`. Un header que el servicio envió más de una vez llega como un único valor separado por comas. | | `body` | El cuerpo de la respuesta, parseado cuando la respuesta es `application/json` o un tipo XML — `application/xml`, `text/xml`, o un tipo cuyo nombre termina en `+xml`. | | `raw_body` | La respuesta tal como llegó, como texto. Presente para una respuesta XML. | | `body_format` | Vale `xml` cuando se decodificó un cuerpo XML. | | `body_parse_error` | Presente en lugar de `body` cuando no se pudo decodificar un cuerpo XML, para que el workflow pueda ramificar según eso. | Por eso los campos de la respuesta quedan bajo `body`: ```json theme={null} { "outputMapping": [ { "source": "body.score", "target": "score" }, { "source": "body.decision", "target": "decision" }, { "source": "status", "target": "httpStatus" } ] } ``` En un nodo con el id `score-transaction`, eso guarda: ```json theme={null} { "score": 42, "decision": "review", "httpStatus": 200 } ``` Los nodos posteriores leen entonces `${score-transaction.score}` y `${score-transaction.httpStatus}`. Un nodo que no declara `outputMapping` guarda en su lugar el envelope completo bajo su id, y los nodos posteriores leen la ruta del envelope directamente: `${score-transaction.body.score}`. Agrega un mapeo de salida cuando quieras el nombre más corto. Omítelo cuando la ruta del envelope sea suficientemente clara. Un origen de salida que no selecciona nada se comporta como uno de entrada. Flowker guarda el destino como `null` a menos que una entrada de ese nodo defina `required: true`. ## Paso 6: revisa el mapeo antes de llamar al servicio *** [Previsualizar una solicitud de executor](/es/reference/products/flowker/preview-executor-request) usa las vías de mapeo, transformación y armado de la solicitud sin hacer una llamada de red al servicio. No lee el vault ni obtiene un token de autenticación. Enmascara los valores secretos suministrados y usa el catálogo de Flowker para resolver el proveedor y el executor. Ninguna credencial aparece en nada de lo que devuelve, incluido el `curl`. Envía el nodo, la configuración de proveedor a la que apunta y un payload de ejemplo. La configuración de proveedor va en la solicitud misma, así que la previsualización no necesita una configuración de proveedor guardada ni una lectura del vault. El catálogo del lado del servidor igual debe resolver el proveedor y el executor: ```json theme={null} POST /v1/workflows/preview-request { "node": { "executorId": "http", "method": "POST", "path": "/score-transaction", "inputMapping": [ { "source": "workflow.customer.document", "target": "payer.document", "transformation": { "type": "remove_characters", "config": { "characters": ".-/" } } }, { "source": "workflow.customer.name", "target": "payer.name", "transformation": { "type": "to_uppercase" } }, { "source": "workflow.transactionId", "target": "payer.reference", "transformation": { "type": "add_prefix", "config": { "prefix": "BR-" } } } ] }, "providerConfig": { "providerId": "http", "config": { "base_url": "https://api.fraudshield.example.com" }, "allowedHosts": ["api.fraudshield.example.com"] }, "sampleInput": { "transactionId": "txn-98765", "customer": { "document": "123.456.789-00", "name": "ada lovelace" } } } ``` Tu `sampleInput` se convierte en el payload del trigger, así que los orígenes del mapeo lo leen como `workflow.*`, exactamente como lo harán en tiempo de ejecución. La respuesta es la solicitud armada: ```json theme={null} { "method": "POST", "url": "https://api.fraudshield.example.com/score-transaction", "headers": { "Content-Type": "application/json" }, "body": "{\"payer\":{\"document\":\"12345678900\",\"name\":\"ADA LOVELACE\",\"reference\":\"BR-txn-98765\"}}", "curl": "curl -X POST -H 'Content-Type: application/json' --data '{\"payer\":{\"document\":\"12345678900\",\"name\":\"ADA LOVELACE\",\"reference\":\"BR-txn-98765\"}}' 'https://api.fraudshield.example.com/score-transaction'", "unresolved": [] } ``` Cada transformación se resolvió: la puntuación desapareció del documento, el nombre está en mayúsculas y la referencia lleva su prefijo. Ninguna llamada llegó al servicio. Léelo en este orden: Es la URL base de la configuración de proveedor más el `path` del nodo. Una ruta que no esperabas es un campo del nodo que hay que corregir, no un mapeo. Se recomienda que cada `target` aparezca donde el servicio lo quiere. Un campo que lleva `null` es una ruta `source` que no selecciona nada. Lista las referencias `${...}` de los campos de plantilla del nodo que tu payload de ejemplo no resolvió. Flowker las deja literales en la solicitud renderizada. Un arreglo vacío significa que cada referencia encontró un valor. Para revisar además los campos fijos de un nodo contra el esquema del executor del catálogo, llama a [Validar la configuración de un nodo](/es/reference/products/flowker/validate-executor-config). Envía la configuración del nodo en `config` y, en `mappedTargets`, las rutas de destino que suministra tu `inputMapping`. Flowker las cuenta como satisfechas, así que un nodo que mapea un campo obligatorio desde el trigger pasa la verificación. ## Qué sale mal *** | Síntoma | Causa | Corrección | | -------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | | El servicio recibe un campo con el valor `null`. | La ruta `source` está ausente del contexto del workflow. | Compara la ruta con el cuerpo renderizado de una previsualización. Define `required: true` en el nodo cuando no debe correr sin el valor. | | El servicio recibe un objeto anidado que no pidió. | El `target` lleva un prefijo. | Escribe el destino exactamente como lo espera el servicio. Un destino `executor.accountId` envía un objeto `executor`. | | El cuerpo de la solicitud está vacío. | El nodo no tiene `data.body`, ni mapeo, ni `transforms`, y su `config` contiene solo nombres de transporte. | Agrega los valores como literales de `config` o como entradas de mapeo. | | Los mapeos parecen ignorarse. | El nodo también lleva `data.body`, que es la única fuente del cuerpo mientras está presente. | Quita `data.body` para dejar que los mapeos armen el cuerpo. | | `transforms` parece ignorarse. | El nodo tiene al menos una entrada de `inputMapping`. | Quita las entradas de `inputMapping`, o mueve la lógica dentro de ellas. | | Un nodo posterior no lee nada. | La referencia no nombra al nodo que produce el valor. | Lee `${.}`. No hay un espacio de nombres compartido de nivel superior. | | Un mapeo de salida guarda `null`. | El `source` omite el prefijo del envelope. | Mapea `body.score`, no `score`. | | Código de error | Cuándo | Qué significa | | --------------- | ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `FLK-0140` | Creación, actualización o activación | El `inputMapping` del nodo no forma una especificación válida — casi siempre un `transformation.type` fuera de los cinco tipos admitidos. | | `FLK-0141` | Creación, actualización o activación | Lo mismo, para el `outputMapping` del nodo. | | `FLK-0142` | Creación, actualización o activación | Lo mismo, para los `transforms` del nodo. | | `FLK-0143` | Tiempo de ejecución | Una referencia `${...}` del `data.body` del nodo no se resuelve contra el contexto del workflow. El nodo falla sin llamar al servicio. | | `FLK-0504` | Tiempo de ejecución | El nodo falló. El mensaje del paso nombra la etapa: `input transformation failed` para un origen obligatorio ausente o una transformación que no pudo correr, `output transformation failed` para el lado de la respuesta. | Consulta la [lista de errores de Flowker](/es/reference/products/flowker/flowker-error-list) para conocer todos los códigos. ## Qué sigue *** Crea la configuración de proveedor a través de la cual llama un nodo, y define su autenticación. Elige el contrato de payload que llena el espacio de nombres `workflow` que leen tus mapeos.