Perguntas frequentes
Dúvidas comuns e soluções para os problemas mais frequentes no iPaaS.
Geral
Preciso saber programar para usar o iPaaS?
Não para configurar. A integração é criada pelo Partner's Portal, e o mapeamento é sugerido pela IA. O seu sistema só precisa fazer uma chamada HTTP autenticada para a Endpoint URL da integração.
Posso atualizar ou cancelar documentos pelo template Criação de Documentos (Inbound)?
Ainda não. O template só cria documentos (POST). Atualização (PUT/PATCH), cancelamento e exclusão ainda não estão disponíveis.
O template Busca de Documentos (Outbound) envia o documento para o meu ERP?
Não. Ele devolve o documento convertido na resposta da chamada. Quem chama, normalmente o seu middleware ou o próprio ERP, grava o resultado no destino.
Qual a diferença entre uma integração e um conector?
A integração é o fluxo configurado a partir de um template, com mapeamento, credencial e Endpoint URL. O conector é o cadastro de uma API externa (URL, autenticação e recursos) que uma integração de Busca de Produtos usa para chamar o provedor. Um mesmo conector pode ser usado por várias integrações.
Posso usar uma integração para mais de um tipo de documento?
Não. Cada integração trata um único tipo de documento. Crie uma integração para cada tipo.
Credencial e autenticação
Perdi a Secret da integração. Como recupero?
A Secret completa só fica disponível enquanto o assistente de criação está aberto, na mesma aba: na etapa Parâmetros e na tela Integração ativada com sucesso. Depois que você sai do assistente, ela não pode ser recuperada. Crie uma nova integração, que terá uma nova credencial.
Editar a integração muda a Chave ou a Secret?
Não. Editar e publicar novamente uma integração mantém a mesma Chave e Secret. O seu sistema não precisa trocar a credencial.
Recebo 401 Unauthorized ao executar.
O token está ausente, inválido ou expirado. Gere um novo token com a Chave e a Secret. Veja Autenticação.
Recebo 403 Forbidden ao executar.
O token foi gerado com a credencial de outra integração. Cada credencial só executa a própria integração: confira se o {flowId} da URL corresponde à Chave usada (integrationhub-{flowId}).
Execução
Recebo 422 dizendo que a integração não pode ser executada.
A integração não está em um status que permite execução: ela está Suspensa, em Rascunho ou Validada (ainda não publicada; só a Busca de Produtos pode ser testada nesse status). Confira o status em Integrações > Minhas Integrações. Veja Minhas Integrações.
A chamada Inbound devolveu 202, mas o documento não apareceu no ME.
O 202 confirma apenas a entrega. O processamento no ME é assíncrono. Em Monitoramento > Execuções, filtre pelo ID de Correlação:
- Em andamento: o ME ainda está processando. Se a execução continuar Em andamento por muito tempo, o ME não devolveu o resultado: abra um chamado informando o ID de Correlação.
- Erro: abra a timeline. A etapa
DOCUMENT_PROCESSINGmostra o motivo da recusa informado pelo ME.
Recebo 400 com erros de validação do documento.
O documento convertido não passou na validação da API do ME. A lista errors traz os campos e as mensagens. Normalmente falta um campo obrigatório no mapeamento, ou um valor está no formato errado (data, número). Ajuste o mapeamento: suspenda, edite, teste e publique novamente.
Enviei o mesmo documento duas vezes e ele foi criado duas vezes.
O iPaaS não faz deduplicação, e o x-me-correlation-id não impede reenvios. Controle os reenvios no seu sistema.
Recebo 400 na Entrega de pedido.
O tipo Entrega de pedido exige o parâmetro orderId na query string: .../execute?orderId={id do pedido}.
Recebo 400 por chave duplicada no JSON.
O corpo tem a mesma chave repetida no mesmo objeto, por exemplo dois campos "C7_NUM". Corrija o JSON gerado pelo seu sistema.
Como encontro uma execução específica?
Envie sempre o header x-me-correlation-id com um identificador do seu sistema e use o filtro ID de Correlação em Monitoramento > Execuções. Veja ID de Correlação.
Mapeamento
A IA não mapeou alguns campos obrigatórios.
A IA só liga campos que têm correspondente na origem e não inventa valores. Ligue manualmente, informe um valor fixo ou use o Assistente ("o campo X é o Y"). Se o campo existe no seu sistema mas não estava no exemplo, use Trocar payload com um exemplo mais completo.
Aparece "Origem não encontrada no payload de exemplo".
A ligação aponta para um campo que não existe no exemplo atual, o que é comum depois de Trocar payload. Religue o campo ou remova a ligação.
Aparece "Tipos incompatíveis".
Origem e destino têm tipos diferentes, por exemplo texto e número. Clique no aviso e aplique uma transformação de conversão. Veja Conversão de tipos.
Os itens do documento saíram "misturados" ou em listas separadas.
Os campos da mesma lista de destino devem percorrer a mesma lista de origem, escrita exatamente da mesma forma. Veja Lista para lista.
Um campo único do ERP recebe o valor errado de uma lista do ME.
A ligação provavelmente escolhe o item pela posição, e a ordem da lista mudou. Escolha o item por um campo que o identifique, como virtualEntityField = 'EMPRESA'. Veja Escolhendo um item de uma lista.
O mapeamento funcionou no teste, mas falha com alguns documentos em produção.
Normalmente um campo que estava preenchido no exemplo chega vazio (null) em outros documentos. Garanta que os campos usados em funções de texto estejam protegidos. Veja Proteção contra campos vazios.
A análise da IA não terminou.
Exemplos muito grandes podem exceder o tempo da análise. Use Tentar novamente ou reduza o exemplo, mantendo todos os campos, mas com poucos itens em cada lista.
Conectores e Busca de Produtos
O teste de autenticação do conector falha.
Confira a URL base, as credenciais e, no OAuth 2.0, a URL do token, o escopo e a forma de envio das credenciais (Avançado > Enviar credenciais via). Se você trocou o host da URL, informe todas as credenciais novamente.
A busca de produtos retorna erro do provedor.
A resposta repassa o status e os detalhes devolvidos pelo provedor, com failedAtStep = API_REQUEST. Confira se o recurso (método e caminho) está correto e se o mapeamento de requisição envia os parâmetros no formato que o provedor espera.
Não consigo excluir um conector.
O iPaaS bloqueia a exclusão de um conector que ainda é usado por alguma integração, em qualquer status (inclusive rascunho ou suspensa), para que essas integrações não parem de funcionar. Troque o conector nessas integrações (suspenda, edite, teste e publique) ou exclua as integrações que não usa mais. Depois, exclua o conector.