Configuração de proxy API no Jitterbit API Manager
Introdução
Esta página descreve como criar e configurar um proxy API a partir da página APIs do Jitterbit API Manager. Um proxy API é um dos três tipos de APIs configurados por meio do API Manager. Para os outros dois tipos, API customizada e serviço OData, consulte Configuração de API customizada e Configuração de serviço OData.
Como alternativa, crie proxies de API usando o Assistente de IA do APIM.
Nota
Após publicado, cada proxy API é contado como uma URL de Proxy contra a sua cota de assinatura do Harmony.
Pré-requisitos
Ao contrário de uma API customizada ou de um serviço OData, que expõem uma operação do Harmony para consumo, um proxy API é usado com uma API existente. APIs proxificadas não são roteadas através de agentes Jitterbit. O gateway que processa a API deve ter acesso à API sendo proxificada:
-
Gateway de API em nuvem: Se você usar o gateway de API em nuvem (hospedado pela Jitterbit), a API existente deve estar acessível publicamente, mesmo que esteja protegida. A API que você está tentando proxificar não pode estar atrás de um firewall. Para adicionar os endereços IP do gateway de API em nuvem à lista de permissões e permitir que o gateway acesse a API sendo proxificada, consulte Informações de lista de permissões e acesse
https://services.jitterbitpara sua região. -
Gateway de API privado: Se você usar um gateway de API privado (hospedado em uma rede privada), o gateway de API privado deve ser capaz de acessar a API existente.
Embora cada proxy API permita que vários serviços sejam atribuídos a uma URL única, a URL base do proxy consome o direito.
Nota
O API Manager totaliza acessos em todos os serviços de uma URL de proxy e os conta contra os direitos acessos por mês e acessos por minuto fornecidos no acordo de licença do Jitterbit. Para informações sobre direitos e limitação de taxa com perfis de segurança, consulte Limites de taxa em Conceitos-chave.
Criar um novo proxy API
Para criar um novo proxy API, clique em Novo e selecione uma das seguintes opções:
-
Criar com IA: Abre o Assistente do APIM para criar uma API usando prompts em linguagem natural. Para obter mais informações, consulte Usando o Assistente de IA.
Nota
Para usar o Assistente de IA do APIM, sua licença do Harmony deve incluir a opção Assistente de IA do APIM. Entre em contato com seu Gerente de Sucesso do Cliente (CSM) para adicionar essa opção à sua licença.
-
Proxy API: Abre a tela de configuração do proxy API para criar manualmente um novo proxy API. Esta opção é habilitada apenas se uma URL de API correspondente estiver disponível.

Configurar um proxy API
Ao configurar um proxy API manualmente, a tela de configuração inclui múltiplas abas. A tela de configuração inclui três abas obrigatórias e três abas opcionais:
- Aba Perfil (obrigatória)
- Aba Configurações (opcional)
- Aba API Existente (obrigatória)
- Aba Serviços (obrigatória)
- Aba Perfis de segurança (opcional)
- Aba Cabeçalhos de solicitação (opcional)
Aba Perfil
Use a aba Perfil para inserir informações básicas que identificam a API.

Configure as seguintes configurações:
-
Nome da API: Digite um nome para o proxy API a ser usado para fins de identificação interna. Os seguintes caracteres especiais são permitidos:
()-_. -
Raiz de Serviço: O nome público da API a ser usado como parte da URL de serviço da API. Por padrão, este campo é preenchido com o Nome do Proxy convertido para camel case. Este campo não permite espaços ou certos caracteres especiais. Não é recomendado usar caracteres especiais diferentes de um sublinhado (
_). Os seguintes caracteres especiais são permitidos:._~()$;/?:@=&'!*,+-. -
Descrição: insira uma descrição opcional para a API.
-
Ambiente: use o menu para selecionar o ambiente onde a API será alojada. Você pode digitar qualquer parte do nome do ambiente no menu para filtrar a lista de ambientes. Os resultados do menu são filtrados em tempo real a cada digitação.
Nota
Após a criação da API, você não pode alterar o ambiente. Para mover uma API entre ambientes, você pode clonar a API ou exportar e importar a API em outro ambiente.
-
Número da versão: insira uma versão opcional para usar como parte da URL do serviço da API. Este campo permite um máximo de 48 caracteres e não permite espaços ou certos caracteres especiais. Não se recomenda usar caracteres especiais diferentes de um ponto (
.) ou um hífen (-). As convenções de nomenclatura comuns incluem versões incrementais comov1.0,v1.1,v1.2, ou usar uma data em que a API foi publicada, como2025-08-28.
Após concluir a aba Perfil, clique em Próximo para prosseguir para a aba Configurações, ou clique em Salvar como rascunho para salvar seu progresso.
Aba Configurações
A aba Configurações é opcional e contém opções de configuração avançadas para a API.

Configure as seguintes configurações conforme necessário:
-
Tempo limite: insira o número de segundos antes do tempo limite da API. O padrão é 30 segundos. O valor máximo permitido é
180segundos.Nota
Esta configuração é independente da configuração de tempo limite de operação no Studio ou Design Studio. As configurações de tempo limite de operação não são usadas a menos que a configuração
EnableAPITimeoutno arquivo de configuração do agente privado esteja ativada. -
Apenas SSL: este controle está ativado por padrão e requer HTTPS para a API. Quando ativado, os dados são criptografados por SSL e uma solicitação HTTP retorna um erro. Quando desativado, são suportadas solicitações HTTP e HTTPS.
Aviso
Quando desativado, os dados passados por meio de solicitações e respostas de API não são criptografados e podem ser interceptados e visualizados por outras pessoas. Isso pode expor potencialmente informações sensíveis.
-
CORS: ative este controle para suportar CORS (Compartilhamento de recursos de origem cruzada). CORS é um mecanismo que permite que aplicações Web em execução em um navegador Web em um domínio acessem recursos de um servidor em um domínio diferente.
Aviso
Ativar CORS faz com que operações que usam o método
OPTIONSsejam executadas sem autenticação. -
Log detalhado: ative este controle para adicionar dados brutos de solicitação e resposta — incluindo cabeçalhos, parâmetros e corpos — ao log de chamadas quando uma solicitação de API é feita. Esses dados aparecem na página Logs de API e na página Tempo de execução do Console de Gerenciamento para execuções bem-sucedidas e malsucedidas. O log detalhado não gera entradas de log de operação do Studio para execuções bem-sucedidas. Para registrar execuções de operação bem-sucedidas no Studio, use Ativar modo de depuração até em vez disso.
Aviso
O log detalhado pode incluir dados sensíveis, como credenciais de autenticação ou informações pessoais identificáveis. Os valores dos cabeçalhos mascarados ficam ocultos, mas os parâmetros e corpos são registrados na íntegra. Use esta configuração com cuidado.
-
Ativar modo de depuração até: ative este controle para ativar o log detalhado para solução de problemas, em seguida, clique no ícone de calendário para selecionar uma data até duas semanas a partir de hoje quando o modo de depuração desativa automaticamente. Quando ativado, os dados de solicitação e resposta (mantidos por 30 dias) aparecem na página Logs de API, na página Tempo de execução do Console de Gerenciamento e nos logs de operação do Studio para execuções bem-sucedidas e malsucedidas. O log de depuração em nível de atividade também é ativado, capturando dados de entrada e saída de componentes na aba Log de depuração. Esta configuração substitui o Log detalhado: quando o modo de depuração está ativado, os dados de solicitação e resposta são incluídos nos logs independentemente de o Log detalhado estar ativado.
Aviso
Os logs de depuração contêm todos os dados de solicitação e resposta, incluindo informações sensíveis como senhas e informações de identificação pessoal (PII). Além dos valores para cabeçalhos mascarados, esses dados aparecem em texto limpo nos logs do Harmony cloud por 30 dias.
- Mostrar Payloads de Solicitação e Resposta nos Logs: Este alternador fica visível nas configurações da API proxy, mas não tem efeito. O log de payload de solicitação e resposta não é suportado para APIs proxy.
Depois de configurar a aba Settings, clique em Next para prosseguir para a aba Existing API, ou clique em Prev para retornar à aba Profile.
Aba Existing API
Use a aba Existing API para especificar a URL base da API que você deseja fazer proxy e, opcionalmente, forneça um documento OpenAPI para descoberta automática de serviços.

Configure as seguintes configurações:
-
Base API URL: Insira a URL base da API para fazer proxy.
Nota
Se a API fornece um único serviço, você pode inserir a URL completa da API, incluindo o caminho do serviço. Caminhos de serviço adicionais são definidos na aba Services.
-
Provide OpenAPI document: Se você fornecer um documento OpenAPI, o API Manager o utilizará para descobrir automaticamente os serviços da API. Selecione No para pular ou Yes para expandir uma área adicional para fornecer o documento OpenAPI:

-
Load URL: Abre um diálogo para carregar um documento OpenAPI em formato YAML ou JSON de uma URL:

-
Upload file: Abre um diálogo para fazer upload de um documento OpenAPI em formato YAML ou JSON depois que você usa Browse para selecionar o arquivo:

-
Clear: Limpa um documento OpenAPI que já foi fornecido e altera a seleção Provide OpenAPI document para No. Um diálogo de confirmação Clear editor contents aparece, pedindo que você confirme antes de o documento ser removido. Limpar o documento também remove qualquer serviço que tenha sido descoberto automaticamente a partir dele (veja Descoberta automática de documento OpenAPI), mas não afeta os serviços adicionados manualmente ou outras configurações de API. Limpar o documento é tratado como uma alteração não salva até que você salve a configuração da API.
-
Document editor: Permite a visualização e edição de um documento OpenAPI fornecido. Você também pode fornecer um documento OpenAPI inserindo-o aqui diretamente. Para visualizar e editar o documento OpenAPI em uma área maior, clique no ícone de expansão. Depois de abrir essa área, clique no ícone de retorno para voltar a esta tela.
-
Depois de configurar a aba Existing API, clique em Next para prosseguir para a aba Services, ou clique em Prev para retornar à aba Settings.
Aba Services
Use a aba Services para definir os serviços e métodos HTTP que a API proxy irá expor. A maneira como você define os serviços depende de você ter fornecido um documento OpenAPI na aba Existing API.
Definição manual de serviço
Se você não forneceu um documento OpenAPI, será necessário definir serviços e métodos manualmente:

Clique em New Service para adicionar um serviço. Configure as seguintes configurações:
-
Service Name: Insira um nome para identificar o serviço.
-
Path: Insira um caminho para o serviço. Se a API não tem um caminho de serviço, insira uma barra (
/). Para definir um parâmetro de caminho, coloque seu nome entre chaves (por exemplo,/pets/{petId}). Para os caracteres e limites que um caminho aceita, veja Regras de caminho de serviço. -
Métodos: Selecione cada método a ser criado para o serviço. Os métodos disponíveis incluem GET, PUT, POST e DELETE. Para usar um método não listado, digite o nome do método na caixa de texto Digite um novo método e pressione Enter.
-
Ações: Passe o mouse sobre uma linha de serviço para revelar ações adicionais.
- Copiar URL do serviço de API: Clique para copiar a URL do serviço de API.
- Duplicar: Clique para duplicar o serviço.
- Deletar: Clique para deletar o serviço.
É necessário adicionar pelo menos um serviço para prosseguir para a próxima aba.
Descoberta automática de documento OpenAPI
Se você forneceu um documento OpenAPI na aba API Existente, o API Manager descobre e lista automaticamente os serviços em uma tabela:

- Atribuir: Use o alternador para adicionar os serviços à API proxy.
- Nome do Serviço: O nome usado para identificar o serviço. Quando o documento define mais de um método para o mesmo caminho, o nome inclui o método (por exemplo,
GET /petsePOST /pets) para que cada nome seja único. Um caminho com um único método usa o caminho como nome. - Métodos: O método HTTP que se aplica ao serviço. Este campo é somente leitura porque os métodos vêm do documento OpenAPI.
- Caminho: O caminho do serviço.
-
Ações: Passe o mouse sobre uma linha de serviço para revelar ações adicionais.
- Copiar URL do serviço de API: Clique para copiar a URL do serviço de API.
O API Manager também detecta os parâmetros de caminho, consulta e cabeçalho que o documento define para cada caminho e método, e os lista nas abas de parâmetro do serviço.
Parâmetros do serviço
Selecione uma linha de serviço para expandi-la e visualizar os parâmetros desse serviço. Os parâmetros são armazenados para cada combinação de caminho e método HTTP. Se um serviço tiver mais de um método, uma aba para cada método (por exemplo, GET e POST) aparece acima das abas de parâmetro, e cada aba de método tem seus próprios parâmetros.
A configuração Obrigatório em parâmetros de consulta e cabeçalhos marca um parâmetro como obrigatório no API Manager e no Portal de API. O Portal de API impede que você teste uma solicitação que omita um parâmetro obrigatório. O gateway de API não verifica parâmetros obrigatórios ao encaminhar solicitações para a API existente, portanto, a API existente deve validá-los.
Aba de parâmetros de caminho
Esta aba lista os parâmetros de caminho do serviço:

-
Parâmetro: O nome de cada parâmetro de caminho. O API Manager adiciona um parâmetro automaticamente para cada nome que você coloca entre chaves no Caminho, seguindo as Regras de caminho do serviço. Este campo é somente leitura. Um consumidor deve fornecer um valor para cada parâmetro de caminho ao chamar o serviço.
-
Descrição: Um campo somente leitura. O API Manager não armazena descrições de parâmetros de caminho.
Aba de parâmetros de consulta
Esta aba lista os parâmetros de consulta do serviço. Os parâmetros de consulta são detectados a partir de um documento OpenAPI ou adicionados manualmente:

-
Adicionar Parâmetro: Clique para adicionar um parâmetro de consulta ao serviço. Os seguintes campos ficam disponíveis:
-
Parâmetro: Digite o nome do parâmetro de consulta. Para os caracteres e comprimento permitidos, consulte Regras de nome de parâmetro.
-
Descrição: Opcionalmente, digite uma descrição do parâmetro de consulta.
-
Obrigatório: Use o alternador para marcar o parâmetro de consulta como obrigatório. O padrão é desabilitado.
-
Deletar: Clique no ícone de exclusão ao lado de um parâmetro de consulta para deletar esse parâmetro.
-
Aba de cabeçalhos
Esta aba lista os cabeçalhos de solicitação que os consumidores podem enviar para o serviço. Esses cabeçalhos descrevem o que a API existente aceita. Para definir valores de cabeçalho que o API Manager envia para a API existente, use a aba Cabeçalhos de solicitação.

-
Adicionar parâmetro: Clique para adicionar um cabeçalho de solicitação ao serviço. Os seguintes campos ficam disponíveis:
-
Parâmetro: Digite o nome do cabeçalho de solicitação. Para os caracteres e comprimento permitidos, consulte Regras de nome de parâmetro.
-
Descrição: Opcionalmente, digite uma descrição do cabeçalho de solicitação.
-
Obrigatório: Use a alternância para indicar que os consumidores devem enviar o cabeçalho. O padrão é desabilitado.
-
Excluir: Clique no ícone de exclusão ao lado de um cabeçalho de solicitação para excluir esse cabeçalho.
-
Regras de nome de parâmetro
O API Manager valida nomes e descrições de parâmetros quando você os edita. Você deve resolver todos os erros antes de publicar a API:
- Nomes de parâmetros não podem estar vazios ou duplicados na mesma aba.
- Nomes de parâmetros não podem exceder 64 caracteres, e descrições não podem exceder 256 caracteres.
- Nomes de parâmetros de consulta podem conter apenas letras, números e os caracteres
-,.e_. - Nomes de parâmetros de cabeçalho podem conter apenas letras em inglês, números e os caracteres
!,#,$,%,&,',*,+,-,.,^,_,`,|e~.
Regras de caminho de serviço
O API Manager valida o Caminho de cada serviço, independentemente de você digitá-lo manualmente ou se ele for proveniente de um documento OpenAPI. Um erro aparece no campo Caminho, e você deve resolvê-lo antes de publicar a API. Um caminho deve seguir estas regras:
- O caminho começa com uma barra (
/). O API Manager adiciona a barra automaticamente. - O caminho não pode exceder 2000 caracteres.
- Cada segmento de texto do caminho (as partes fora de chaves) pode conter apenas letras, números e os caracteres
-,_e.. Letras e números podem ser de qualquer idioma. - Um caminho não pode conter segmentos vazios (
//). - Chaves devem ser emparelhadas e não podem ser aninhadas ou vazias. Um nome de parâmetro de caminho dentro das chaves segue as mesmas regras de caracteres que os segmentos de texto e não pode exceder 64 caracteres. Um caminho não pode usar o mesmo nome de parâmetro duas vezes.
- Um caminho pode terminar com uma barra, e texto e parâmetros podem compartilhar um segmento (por exemplo,
/report.{format}). - Um serviço pode usar o caminho base (
/) sem segmento adicional, e o caminho base pode ter vários métodos.
Depois de configurar a aba Serviços, clique em Próximo para prosseguir para a aba Perfis de segurança, ou clique em Anterior para voltar à aba API existente.
Aba Perfis de segurança
A aba Perfis de segurança é opcional e permite restringir o acesso ao consumo da API.

Configure as seguintes configurações:
-
Atribuir: Use a alternância para atribuir ou desatribuir perfis de segurança para a API.
-
Nome do Perfil: O nome do perfil de segurança conforme configurado em Perfis de Segurança.
-
Tipo: O tipo de autenticação do perfil de segurança, como Básica, OAuth 2.0 ou Chave de API.
-
Nome de Usuário: Para autenticação básica, isto exibe o nome de usuário. Para outros tipos de autenticação, isto exibe o mesmo valor da coluna Tipo.
-
Ações: Passe o mouse sobre uma linha de perfil de segurança para revelar ações adicionais.
- Ir para perfil de segurança: Clique para abrir a configuração do perfil de segurança.
Dependendo das políticas da organização Harmony, você pode ser obrigado a atribuir um perfil de segurança para salvar a API.
Dica
Alterações nas atribuições de perfis de segurança são salvas como rascunhos. Você deve publicar a API usando Salvar e Publicar para aplicar as alterações e permitir a exclusão de perfis previamente atribuídos. Perfis de segurança não podem ser excluídos enquanto aparecerem em qualquer configuração publicada de uma API, mesmo que você os tenha desatribuído em uma versão de rascunho.
Clique em Novo perfil de segurança para criar um novo perfil de segurança. Para obter instruções, consulte Configurar perfis de segurança.
Após configurar a guia Perfis de segurança, clique em Próximo para prosseguir para a guia Cabeçalhos de solicitação, ou clique em Anterior para voltar à guia Serviços.
Guia Cabeçalhos de solicitação
A guia Cabeçalhos de solicitação é opcional e permite adicionar novos cabeçalhos de solicitação ou substituir cabeçalhos de solicitação existentes.

Nota
Por padrão, o cabeçalho de solicitação disable-hyphen-replacement é definido como true para todas as novas APIs de proxy. Após publicar a API de proxy, é possível definir o cabeçalho de solicitação como false para substituir hífens (-) por underscores (_) nos cabeçalhos de solicitação (exceto para os cabeçalhos de solicitação Content-Type, Content-Length, Accept-Encoding e Transfer-Encoding).
Clique em Novo cabeçalho para adicionar um cabeçalho de solicitação. Configure as seguintes opções:
-
Chave: insira uma chave para o cabeçalho de solicitação. A chave pode conter apenas letras, números, hífens (
-) e underscores (_). Espaços, caracteres multibyte e outros caracteres especiais não são permitidos. -
Valor: insira um valor para o cabeçalho de solicitação. O valor pode conter apenas caracteres ASCII imprimíveis (letras, números e pontuação padrão), sem espaços iniciais ou finais, e não pode exceder 8192 caracteres. Caracteres multibyte e de controle não são permitidos. Isso é adequado para valores como JSON Web Tokens (JWTs), que exigem pontos (
.) como parte de seu formato. -
Substituir entrada: ative este botão para substituir um cabeçalho de solicitação existente que use a mesma Chave. O padrão é desativado.
-
Ações: passe o mouse sobre uma linha de cabeçalho para revelar ações adicionais.
- Excluir: clique para excluir o cabeçalho de solicitação.
Após configurar a guia Cabeçalhos de solicitação, clique em Publicar para publicar a API ou clique em Salvar como rascunho para salvar seu progresso.
Opções de salvar e publicar
Após configurar todas as guias obrigatórias, é possível salvar ou publicar a API:
-
Salvar como rascunho: salva a API com status Rascunho ou Publicado com Rascunho. APIs de rascunho não contam contra o limite de assinatura de URL de proxy. Uma API cujo status era Publicado no momento em que você usa Salvar como rascunho é salva como Publicado com Rascunho. Uma API publicada conta contra o limite de assinatura de URL de proxy, mesmo que seu rascunho não esteja acessível.
-
Publicar: salva a API com status Publicado. A API está ativa e acessível em até cinco minutos. Uma API publicada conta contra o limite de assinatura de URL de proxy. Uma caixa de diálogo indica que a API está ativa:

A caixa de diálogo oferece estas opções:
- Copiar URL: copia a URL de serviço da API para a área de transferência.
- Fechar: fecha a caixa de diálogo.
Editar a API
Após salvar a API, é possível editá-la de:
- Usando visualização de cartões na página APIs, clique no cartão.
- Usando visualização de lista na página APIs, clique em Editar na coluna Ações.
Ao editar uma API publicada da visualização de lista, uma guia Documentação também está disponível. Use essa guia para visualizar, editar e publicar a documentação OpenAPI para APIs individuais. Para obter detalhes, consulte guia Documentação na página APIs.
Solução de problemas
Para solução de problemas relacionada, consulte o seguinte no guia de solução de problemas do API Manager: