Guia de expressões

As regras que o iPaaS usa para converter cada campo, com exemplos de origem, expressão e resultado.

---

Cada ligação do mapeamento é uma expressão: uma regra curta que diz como obter o valor de um campo do destino a partir da origem. Na maior parte dos casos você não precisa escrever nenhuma expressão. A IA gera todas elas, e você pode pedir ajustes em português no painel de Transformação ou no Assistente. Este guia explica como o iPaaS mapeia, para que você entenda o que foi gerado, saiba o que pedir e, se quiser, edite a expressão diretamente.

📘 Nota

As expressões do iPaaS usam a sintaxe JSONata. Você não precisa aprender JSONata para usar o iPaaS. Tudo o que é necessário para mapear está descrito aqui, e o iPaaS aceita exatamente as construções deste guia.

Como ler os exemplos

Cada exemplo mostra três partes:

• Origem: o trecho do JSON de origem (o exemplo do ERP no Inbound, o documento do ME no Outbound).
• Expressão: a regra que produz o valor do campo de destino.
• Resultado: o valor que chega ao destino.

Elementos básicos de uma expressão:

Elemento	Como se escreve	Exemplo
Campo da origem	Nomes separados por ponto	PedidoCompra.C7_NUM
Texto fixo	Entre aspas simples	'EMPRESA'
Número fixo	Sem aspas	1
Verdadeiro, falso, nulo	Sem aspas	true, false, null
Função	Começa com $	$uppercase(PedidoCompra.C7_NUM)

---

1. Referenciando campos

Todo caminho começa direto no primeiro nível da origem e desce pelos objetos com ..

Origem

{ "PedidoCompra": { "C7_NUM": "000123", "C7_XNOME": "ACME", "C7_TIPO": "N" } }

Destino	Expressão	Resultado
Header.clientOrderId	PedidoCompra.C7_NUM	"000123"
Header.vendorName	PedidoCompra.C7_XNOME	"ACME"

❗️ Atenção

Não use prefixos antes do primeiro nível, como $.PedidoCompra, source.PedidoCompra ou input.PedidoCompra. O caminho começa sempre no nome do campo de topo, e uma expressão com prefixo é rejeitada.

No Outbound, o documento do ME tem sempre um único campo de topo, com o nome da entidade (por exemplo order para pedidos e preOrder para pré-pedidos). Todas as informações relacionadas ficam dentro dele, então os caminhos começam sempre por esse nome: order.summary, order.items.quantity, order.items.taxInformation.calculationBasis. Um caminho como items.quantity, sem o order., não encontra nada.

2. Cópia direta

É o caso mais comum: o valor da origem vai para o destino sem alteração. Com a origem do item 1:

Destino	Expressão	Resultado
Header.orderType	PedidoCompra.C7_TIPO	"N"

A IA liga campos pelo significado, não só pelo nome: C7_NUM → clientOrderId, CompanyCode → businessOrganizations.code. O percentual de confiança indica o quanto ela tem certeza. Nomes idênticos recebem confiança alta, e sinônimos ou abreviações recebem confiança menor e costumam ficar pendentes de revisão.

3. Objetos e campos aninhados

Você não precisa se preocupar com a estrutura do destino: o iPaaS monta os objetos intermediários sozinho. Cada expressão cuida de um único campo final, e o iPaaS junta todos os campos que compartilham o mesmo objeto.

Com a origem do item 1:

Destino	Expressão
Header.clientOrderId	PedidoCompra.C7_NUM
Header.vendorName	PedidoCompra.C7_XNOME
Header.orderType	PedidoCompra.C7_TIPO

Resultado

{ "Header": { "clientOrderId": "000123", "vendorName": "ACME", "orderType": "N" } }

4. Valores fixos

Use um valor fixo quando o destino exige sempre o mesmo valor, sem correspondência na origem.

Destino	Expressão	Resultado
businessOrganizations.virtualEntityField	'EMPRESA'	"EMPRESA"
Um campo de texto com o tipo do documento	'PurchaseOrder'	"PurchaseOrder"
Um campo numérico	1	1

Não confunda o texto 'null' com o valor nulo, que é null, sem aspas.

📘 Nota

A IA não cria valores fixos por conta própria para completar o destino. Campos sem origem ficam sem ligação, e você decide o que fazer com eles. A exceção é quando o próprio exemplo deixa claro que o valor é uma constante, como parâmetros fixos da requisição de um provedor.

---

5. Listas

As listas (arrays) são a parte mais importante do mapeamento. O iPaaS tem duas formas de preencher uma lista do destino, e a escolha depende de a origem ter ou não uma lista correspondente.

5.1 Lista para lista: um item de destino para cada item de origem

Quando existe uma lista na origem, o iPaaS percorre essa lista e gera um item no destino para cada item da origem. Dentro da lista, os campos são referenciados a partir do item, e não desde o início.

Origem

{
  "PedidoCompra": {
    "C7_NUM": "000123",
    "C7_EMISSAO": "20250115",
    "Itens": [ { "C7_ITEM": "10", "C7_QTDE": "5", "C7_PRECO": "12.50" } ]
  }
}

Lista percorrida: PedidoCompra.Itens

Destino	Expressão (relativa ao item)
Header.items.itemNumber	$number(C7_ITEM)
Header.items.quantity	$number(C7_QTDE)
Header.items.unitPrice	$number(C7_PRECO)

Resultado

{ "Header": { "items": [ { "itemNumber": 10, "quantity": 5, "unitPrice": 12.5 } ] } }

Com mais itens na origem, o destino recebe um item para cada um. Na notação completa, esta regra fica assim:

[PedidoCompra.Itens.{ 'itemNumber': $number(C7_ITEM), 'quantity': $number(C7_QTDE), 'unitPrice': $number(C7_PRECO) }]

Regras desta forma:

• O destino é sempre uma lista. Mesmo que o ERP envie um único item como objeto, e não como lista, o destino recebe uma lista com um item.
• Todos os campos de uma mesma lista de destino percorrem a mesma lista de origem, escrita exatamente igual. Se um campo usa PedidoCompra.Itens e outro usa Itens, o iPaaS gera listas paralelas em vez de uma só. O quadro avisa quando isso acontece.
• Nunca monte uma lista juntando campos soltos de listas diferentes. Os valores de um item de destino vêm do mesmo item de origem.

5.2 Lista montada a partir de campos únicos

Quando o destino é uma lista, mas a origem não tem uma lista correspondente, o iPaaS monta um único item com valores de qualquer lugar da origem, inclusive de estruturas diferentes, e com valores fixos. Aqui os caminhos são completos, desde o início da origem.

Origem

{
  "PurchaseOrder": { "CompanyCode": "0001" },
  "CompanyCode": { "Description": "Matriz SP" }
}

Destino	Expressão
businessOrganizations.code	PurchaseOrder.CompanyCode
businessOrganizations.description	CompanyCode.Description
businessOrganizations.virtualEntityField	'EMPRESA'

Resultado

{
  "businessOrganizations": [
    { "code": "0001", "description": "Matriz SP", "virtualEntityField": "EMPRESA" }
  ]
}

❗️ Atenção

Em uma mesma lista de destino, use uma forma só: ou todos os campos percorrem a mesma lista de origem (5.1), ou todos vêm de campos únicos (5.2). Misturar as duas formas na mesma lista gera conflito na montagem do documento.

5.3 Usando dentro do item um valor que está fora da lista

Dentro de uma lista percorrida, os caminhos são relativos ao item. Para trazer um valor que está fora da lista, como um campo do cabeçalho, comece o caminho com $$.. O $$ representa o início da origem.

Origem

{ "notaDe": "minha anotação", "itens": [ { "orderId": 1 }, { "orderId": 2 } ] }

Lista percorrida: itens

Destino	Expressão (relativa ao item)
items.orderId	orderId
items.note	$$.notaDe

Resultado

{
  "items": [
    { "orderId": 1, "note": "minha anotação" },
    { "orderId": 2, "note": "minha anotação" }
  ]
}

Sem o $$., o iPaaS procuraria notaDe dentro de cada item, não encontraria nada, e o campo ficaria vazio sem nenhum erro.

No Outbound, a regra é a mesma: $$.order.summary traz o resumo do pedido para dentro de cada item.

5.4 Informações dentro de itens

Uma informação dentro de um item é acessada a partir do item, com o caminho completo até ela.

Origem (Outbound)

{
  "order": {
    "id": "39581903",
    "summary": "Compra de material",
    "items": [
      { "id": "6", "code": "ITM-01", "quantity": 33.0, "taxInformation": { "calculationBasis": 100.0 } }
    ]
  }
}

Lista percorrida: order.items

Destino	Expressão (relativa ao item)	Resultado
PurchaseOrderItem.OrderQuantity	$string(quantity)	"33"
PurchaseOrderItem.TaxBasis	$string(taxInformation.calculationBasis)	"100"

Se a informação aninhada for ela mesma uma lista, por exemplo vários impostos por item (order.items.taxInformation.taxes), ela é percorrida dentro do item da mesma forma da seção 5.1. O destino recebe então uma lista de impostos em cada item.

5.5 Instâncias fixas: businessOrganizations e attributes

No ME, as listas businessOrganizations (organizações: empresa, organização de compras, centro, filial...) e attributes (atributos) costumam ser preenchidas a partir de vários campos únicos do ERP, e cada campo representa um item diferente. Para esses casos, o iPaaS monta uma instância por entidade, identificada pela posição [0], [1], [2]...

Origem

{
  "CompanyCode": "M001",
  "CompanyName": "MD ENGENHARIA",
  "PurchasingOrganization": "01",
  "Attr2": "atributo"
}

Destino	Expressão
businessOrganizations[0].code	CompanyCode
businessOrganizations[0].description	CompanyName
businessOrganizations[0].virtualEntityField	'EMPRESA'
businessOrganizations[1].code	PurchasingOrganization
businessOrganizations[1].virtualEntityField	'ORGANIZACAO_COMPRAS'
attributes[0].name	'Atributo fixo'
attributes[1].name	Attr2

No exemplo, attributes[0] recebe um valor fixo ('Atributo fixo'), e attributes[1] vem do campo Attr2 da origem.

Resultado

{
  "businessOrganizations": [
    { "code": "M001", "description": "MD ENGENHARIA", "virtualEntityField": "EMPRESA" },
    { "code": "01", "virtualEntityField": "ORGANIZACAO_COMPRAS" }
  ],
  "attributes": [ { "name": "Atributo fixo" }, { "name": "atributo" } ]
}

Regras das instâncias:

• Valem para businessOrganizations e attributes no primeiro nível do documento e também para as listas aninhadas items.attributes, items.businessOrganizations, locations.businessOrganizations, requestItems.attributes e requestItems.businessOrganizations. Elas não se aplicam a outras listas, como items.
• Em uma lista aninhada, as mesmas instâncias se repetem em cada item da lista pai, cada uma com os valores daquele item. Veja o exemplo abaixo.
• Com uma única entidade na origem, não há instâncias: vale a forma 5.2.
• Todos os campos da mesma entidade usam a mesma posição: CompanyCode e CompanyName descrevem a mesma empresa, então ambos vão para [0].
• As posições são sequenciais a partir de [0], na ordem em que os campos aparecem na origem.
• Quando uma lista usa instâncias, todos os campos dela usam posição. Não misture businessOrganizations.code com businessOrganizations[1].code.
• Campos de classificação, como virtualEntityField e entityType, são códigos configurados para a sua organização no ME. A IA só os preenche quando o nome do campo de origem deixa a entidade inequívoca. Na dúvida, o campo fica para você completar. As sugestões com instâncias têm confiança limitada e aparecem como pendentes de revisão.

No quadro de mapeamento, use Adicionar instância para criar uma nova posição e Remover instância para excluí-la. As posições seguintes são renumeradas.

Exemplo com lista aninhada (items.attributes)

Origem:

{
  "itens": [
    { "codigo": "A1", "cor": "azul", "material": "aco" },
    { "codigo": "B2", "cor": "verde", "material": "plastico" }
  ]
}

Lista percorrida: itens

Destino	Expressão (relativa ao item)
items.code	codigo
items.attributes[0].name	'Cor'
items.attributes[0].value	cor
items.attributes[1].name	'Material'
items.attributes[1].value	material

Resultado: as duas instâncias aparecem em cada item, com os valores daquele item.

{
  "items": [
    { "code": "A1", "attributes": [ { "name": "Cor", "value": "azul" }, { "name": "Material", "value": "aco" } ] },
    { "code": "B2", "attributes": [ { "name": "Cor", "value": "verde" }, { "name": "Material", "value": "plastico" } ] }
  ]
}

5.6 Escolhendo um item de uma lista para um campo único

Às vezes a origem é uma lista e o destino aceita um valor só. Por exemplo, no Outbound, o ERP quer um único campo CompanyCode, mas o documento do ME tem uma lista businessOrganizations com a empresa, o centro e outras organizações. Nesses casos o iPaaS precisa saber qual item usar.

A forma recomendada é escolher o item por um campo que o identifica.

Origem (Outbound, pré-pedido)

{
  "preOrder": {
    "businessOrganizations": [
      { "code": "111111", "description": "MATRIZ", "virtualEntityField": "EMPRESA" },
      { "code": "131313", "description": "Demonstração 2", "virtualEntityField": "CENTRO" }
    ]
  }
}

Destino	Expressão	Resultado
CompanyCode	preOrder.businessOrganizations[virtualEntityField = 'EMPRESA'].code	"111111"
Plant	preOrder.businessOrganizations[virtualEntityField = 'CENTRO'].code	"131313"

No fluxo de demonstração da figura, o pedido do ME tem a organização com virtualEntityField = MATRIZ, e a IA gerou order.businessOrganizations[virtualEntityField = 'MATRIZ'].code para o CompanyCode do SAP. O quadro mostra a escolha aplicada no próprio traço da ligação (virtualEntityField = MATRIZ); clique nele para rever ou trocar o campo e o valor.

No quadro, essas ligações aparecem com o aviso Escolher item. Clique no aviso e informe o Campo e o Valor que identificam o item (no exemplo, virtualEntityField = EMPRESA).

Escolher pela posição ([0], [1]) só deve ser usado quando nenhum campo identifica os itens:

Destino	Expressão	Resultado com a origem acima
PurchasingOrganization	preOrder.businessOrganizations[1].code	"131313"

❗️ Atenção

A ordem dos itens de uma lista não é garantida. Se em outro documento a lista vier em outra ordem, a posição [1] passa a trazer outro item, e o valor errado vai para o ERP sem nenhum erro. Por isso, a IA só sugere escolha por posição quando não há alternativa, e sempre com confiança baixa, para que você revise.

---

6. Conversão de tipos

Quando o tipo da origem é diferente do tipo exigido pelo destino, o valor precisa ser convertido. O quadro sinaliza essas ligações como Tipos incompatíveis, e a IA aplica a conversão automaticamente sempre que identifica a diferença.

Conversão	Origem	Expressão	Resultado
Texto → número	{ "C7_ITEM": "10" }	$number(C7_ITEM)	10
Número → texto	{ "quantity": 33.0 }	$string(quantity)	"33"
Texto 'true'/'false' → verdadeiro/falso	{ "ativo": "false" }	$lowercase(ativo) = "true"	false
Remover zeros à esquerda (número)	{ "C7_NUM": "000123" }	$number(C7_NUM)	123
Remover zeros à esquerda (texto)	{ "C7_NUM": "000123" }	$string($number(C7_NUM))	"123"

Se a origem já tem o tipo exigido, nenhuma conversão é aplicada.

❗️ Atenção

Não use $boolean() para converter os textos "true"/"false": ele devolve true para qualquer texto não vazio, inclusive "false". Compare o texto, como em $lowercase(campo) = "true".

7. Textos

O que fazer	Origem	Expressão	Resultado
Concatenar com separador	{ "C7_XNOME": "MARCIA", "C7_XSOBRENOME": "SOUZA" }	C7_XNOME & '-' & C7_XSOBRENOME	"MARCIA-SOUZA"
Concatenar com espaço	(a mesma)	C7_XNOME & ' ' & C7_XSOBRENOME	"MARCIA SOUZA"
Minúsculas	{ "C7_XNOME": "MARCIA" }	$lowercase(C7_XNOME)	"marcia"
Maiúsculas	{ "C7_XNOME": "marcia" }	$uppercase(C7_XNOME)	"MARCIA"
Parte do texto	{ "C7_EMISSAO": "20250115" }	$substring(C7_EMISSAO, 0, 4)	"2025"
Substituir trechos	{ "data": "2025-01-15" }	$replace(data, '-', '')	"20250115"

$substring(texto, início, tamanho) conta a partir de 0. Pelo painel de Transformação, basta descrever o que você quer, por exemplo "concatena os dois campos com hífen e deixa tudo maiúsculo".

8. Datas

AAAAMMDD → data ISO 8601

Origem	Expressão	Resultado
{ "C7_EMISSAO": "20250115" }	( $d := C7_EMISSAO; $substring($d,0,4) & '-' & $substring($d,4,2) & '-' & $substring($d,6,2) & 'T00:00:00Z' )	"2025-01-15T00:00:00Z"

A expressão guarda o valor em $d e depois monta a data em partes. Blocos entre parênteses, com ; separando os passos, são usados para dar nome a um valor intermediário e deixar a regra mais legível.

Data ISO 8601 → AAAAMMDD

C7_DATPRF ? $replace($substring(C7_DATPRF, 0, 10), '-', '') : null

Pega os 10 primeiros caracteres (AAAA-MM-DD), remove os hífens e só aplica a regra se o campo tiver valor. Veja Proteção contra campos vazios.

9. Números e cálculos

Operadores disponíveis: +, -, *, /. Use parênteses para definir a ordem das operações.

O que fazer	Expressão
Dividir e arredondar para 2 casas	$round(PedidoCompra.VALOR / 10, 2)
Multiplicar quantidade pelo preço, convertendo os textos em número	$number(C7_QTDE) * $number(C7_PRECO)

Com a origem da seção 5.1 ("C7_QTDE": "5" e "C7_PRECO": "12.50"), a multiplicação resulta em 62.5.

10. Condicionais

Use condição ? valor-se-verdadeiro : valor-se-falso.

Expressão	Origem	Resultado
PedidoCompra.TIPO = 'NB' ? 'STANDARD' : 'OUTROS'	TIPO = "NB"	"STANDARD"
(a mesma)	TIPO com qualquer outro valor	"OUTROS"

Para mais de duas opções, encadeie condicionais ou, melhor ainda, use uma tabela de-para.

11. Valor padrão e campos vazios

Valor padrão

Quando o campo pode vir vazio ou ausente e o destino precisa de um valor, use o próprio campo como condição:

Expressão	Origem	Resultado
PedidoCompra.C7_XNOME ? PedidoCompra.C7_XNOME : 'SEM_NOME'	{ "PedidoCompra": { "C7_XNOME": "ACME" } }	"ACME"
(a mesma)	{ "PedidoCompra": { } }	"SEM_NOME"

Proteção contra campos vazios

O exemplo usado no mapeamento é um único registro, e o fato de um campo estar preenchido nele não garante que ele venha preenchido sempre. Quando um campo chega com valor null em uma função de texto ($substring, $replace, $uppercase, $lowercase...), a conversão do documento inteiro falha, e não só a daquele campo.

Por isso, o iPaaS protege por padrão todo campo que passa por uma dessas funções, verificando se ele tem valor antes de aplicar a função:

PedidoCompra.Itens.C7_DATPRF ? $replace($substring(PedidoCompra.Itens.C7_DATPRF, 0, 10), '-', '') : null

em vez de:

$replace($substring(PedidoCompra.Itens.C7_DATPRF, 0, 10), '-', '')

Com a proteção, um C7_DATPRF com null resulta em null e o restante do documento é convertido normalmente. Sem ela, a conversão inteira falha.

Se você editar uma expressão manualmente, mantenha essa proteção. Um campo ausente (que nem aparece no JSON) não causa erro, ele simplesmente não é preenchido. O risco está no campo presente com null.

12. Tabelas de-para

Para converter códigos de um sistema para outro, declare uma tabela e consulte-a com $lookup:

( $moeda := { 'USD': 'DOLAR', 'BRL': 'REAL' }; $lookup($moeda, PedidoCompra.MOEDA) )

PedidoCompra.MOEDA	Resultado
"USD"	"DOLAR"
"BRL"	"REAL"

Se o código não existir na tabela, o campo fica vazio. Para ter um valor padrão, combine com a regra de valor padrão.

13. Totais e contagens

O que fazer	Expressão
Somar um campo de todos os itens de uma lista	$sum(PedidoCompra.Itens.C7_VALOR)
Contar os itens de uma lista	$count(PedidoCompra.Itens)

Com a origem da seção 5.1, que tem um único item, $count(PedidoCompra.Itens) resulta em 1.

---

14. Mapeamento de requisição do conector

No mapeamento de requisição de um conector, a origem é sempre um objeto simples com os parâmetros de busca do ME, sem listas:

Operação	Origem
getAll	{ "searchTerm": "...", "pageNumber": 1, "pageSize": 20 }
getById e getOffers	{ "productId": "..." }

Por isso:

• as expressões são sempre diretas ou com as funções de conversão e texto acima;
• se o provedor exige uma lista com um único código, basta ligar o productId. O iPaaS coloca o valor dentro da lista automaticamente;
• quando o exemplo é uma query string, cada parâmetro vira um campo de primeiro nível;
• parâmetros fixos do provedor, como região e idioma, entram como valor fixo quando aparecem no exemplo colado.

Exemplo com corpo JSON (recurso POST). Exemplo colado:

{ "clientDetails": { "clientId": "192533129MEP", "accountNumber": "800014904" }, "searchQuery": "drill" }

Destino (provedor)	Expressão
searchQuery	searchTerm

Exemplo com query string (recurso GET). Exemplo colado: ?productRegion=US&locale=en_US&keyword=drill&pageNumber=1

Destino (provedor)	Expressão
keyword	searchTerm
pageNumber	pageNumber
productRegion	'US'
locale	'en_US'

Exemplo com lista de um único código (getById). Exemplo colado: { "productCodes": ["3EB46"], "clientDetails": { ... } }

Destino (provedor)	Expressão	Enviado ao provedor
productCodes	productId	["<productId>"]

15. O que não é suportado

Para garantir que o mapeamento funcione igual no teste e em produção, o iPaaS aceita apenas as construções descritas neste guia. Não são aceitos:

Construção	Alternativa no iPaaS
Filtrar os itens de uma lista por condição, como Itens[C7_QTDE > 0]	Não disponível. Todos os itens da lista de origem são levados para o destino. A única seleção por condição aceita é a escolha de um item para um campo único, no Outbound.
Curingas * e **	Use o caminho completo do campo.
Encadeamento com ~>	Aninhe as funções: $uppercase($substring(C7_EMISSAO, 0, 4)).
Funções de ordem superior ($map, $filter, $reduce...)	Use a lista para lista.
Funções fora da referência rápida	Combine as funções disponíveis ou use uma tabela de-para.
Prefixos $., source. e input. no caminho	Comece o caminho no campo de topo.

Referência rápida de funções

Função	O que faz	Exemplo
$number(x)	Converte texto em número	$number('000123') → 123
$string(x)	Converte em texto	$string(33) → "33"
$boolean(x)	Converte em verdadeiro/falso. Atenção: todo texto não vazio vira true, inclusive 'false'; só o texto vazio vira false	$boolean('false') → true
$uppercase(x)	Letras maiúsculas	$uppercase('marcia') → "MARCIA"
$lowercase(x)	Letras minúsculas	$lowercase('MARCIA') → "marcia"
$substring(x, início, tamanho)	Parte de um texto	$substring('20250115', 0, 4) → "2025"
$replace(x, de, para)	Substitui trechos	$replace('2025-01-15', '-', '') → "20250115"
$round(x, casas)	Arredonda	$round(62.456, 2) → 62.46
$sum(lista)	Soma os valores	$sum([5, 12.5]) → 17.5
$count(lista)	Conta os itens	$count([1, 2]) → 2
$lookup(tabela, chave)	Consulta uma tabela de-para	$lookup({'USD': 'DOLAR'}, 'USD') → "DOLAR"
&	Concatena textos	'MARCIA' & '-' & 'SOUZA' → "MARCIA-SOUZA"
? :	Condicional	TIPO = 'NB' ? 'STANDARD' : 'OUTROS'
$$	Início da origem, usado dentro de listas	$$.notaDe