Configuração de API personalizada no Jitterbit API Manager
Introdução
Esta página descreve como criar e configurar uma API personalizada a partir da página APIs do Jitterbit API Manager. APIs personalizadas são um dos três tipos de APIs que você pode configurar no API Manager. Para os outros dois tipos, serviço OData e API proxy, consulte Configuração de serviço OData e Configuração de API proxy.
Alternativamente, crie APIs personalizadas usando o Assistente de IA do APIM ou no Studio usando a opção Publicar como uma API do menu de ações da operação.
Nota
Após publicada, cada API personalizada conta como uma URL de API em relação à sua cota de assinatura do Harmony.
O API Manager exibe APIs personalizadas (publicadas e rascunhos) nesses locais:
- A página APIs do API Manager.
- A guia Resources do painel de projeto do projeto do Studio associado à API personalizada.
Pré-requisitos
Uma API personalizada expõe uma operação do Harmony para consumo. Você deve primeiro criar e implantar essa operação no Harmony antes de configurar a API personalizada. A operação que uma API personalizada dispara pode ser uma operação do Studio ou Design Studio.
Para obter instruções sobre como criar e implantar uma operação, consulte estes recursos:
- Studio
- Design Studio
Criar uma nova API personalizada
Ao acessar a página APIs do API Manager, se nenhuma API personalizada, serviço OData ou API proxy existir na organização selecionada, essa tela estará em branco.
Para criar uma nova API personalizada, clique em New e selecione uma das seguintes opções:
-
Build with AI: 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 Customer Success Manager (CSM) para adicionar essa opção à sua licença.
O API Manager exibe a seguinte opção apenas se uma URL de API correspondente estiver disponível:
- Custom API: Abre a tela de configuração de API personalizada para criar manualmente uma nova API personalizada. Essa opção é habilitada apenas se uma URL de API correspondente estiver disponível.

Nota
Esta página documenta a interface de configuração baseada em abas acessível a partir da exibição de lista e exibição de cartão.
Configurar uma API personalizada
Ao configurar uma API personalizada manualmente, a tela de configuração inclui múltiplas abas. A tela de configuração inclui duas abas obrigatórias e três abas opcionais:
- Aba Profile (obrigatória)
- Aba Settings (opcional)
- Aba Services (obrigatória)
- Aba Security profiles (opcional)
- Aba User roles (opcional)
Aba Profile
Use a aba Profile para inserir informações básicas que identificam a API.

Configure as seguintes definições:
-
API Name: Digite um nome para a API a ser usado para fins de identificação interna. Os seguintes caracteres especiais são permitidos:
()-_. -
Service Root: 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 API Name convertido para camel case. Este campo não permite espaços ou certos caracteres especiais. Não se recomenda usar caracteres especiais além de um sublinhado (
_). Os seguintes caracteres especiais são permitidos:._~()$;/?:@=&'!*,+-. -
Description: Digite uma descrição opcional para a API.
-
Environment: Use o menu para selecionar o ambiente onde a API residirá. Digite 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, não é possível alterar o ambiente. Para mover uma API entre ambientes, clone-a ou exporte e importe a API em outro ambiente. Ao exportar, é possível incluir os projetos do Studio que os serviços da API utilizam.
-
Version number: Digite uma versão opcional para usar como parte da URL de serviço da API. Este campo permite no máximo 48 caracteres e não permite espaços ou certos caracteres especiais. Não se recomenda usar caracteres especiais além de um ponto (
.) ou um hífen (-). As convenções de nomenclatura comuns incluem versões incrementadas comov1.0,v1.1,v1.2, ou usar uma data em que a API foi publicada, como2025-08-28.
Após completar a aba Profile, clique em Next para prosseguir para a aba Settings, ou clique em Save as draft para salvar seu progresso.
Settings tab
A aba Settings é opcional e contém opções de configuração avançada para a API.

Configure as seguintes definições conforme necessário:
-
Timeout: Digite o número de segundos antes da API atingir o tempo limite. O padrão é 30 segundos. O valor máximo permitido é
180segundos.Nota
Esta definição é independente da definição de tempo limite de operação no Studio ou Design Studio. As definições de tempo limite de operação não são usadas a menos que um private agent seja utilizado e a definição
EnableAPITimeoutno arquivo de configuração do private agent esteja habilitada. -
SSL only: Este toggle está habilitado por padrão e requer HTTPS para a API. Quando habilitado, os dados são criptografados via SSL e uma requisição HTTP retorna um erro. Quando desabilitado, tanto requisições HTTP quanto HTTPS são suportadas.
Aviso
Quando desabilitado, os dados transmitidos por meio de requisições e respostas da API não são criptografados e podem ser interceptados e visualizados por outras pessoas. Isso pode expor informações sensíveis.
-
CORS: Habilite este toggle para suportar CORS (Cross-Origin Resource Sharing). CORS é um mecanismo que permite que aplicações web executadas em um navegador web em um domínio acessem recursos de um servidor em um domínio diferente.
Aviso
Habilitar CORS faz com que operações que usam o método
OPTIONSsejam executadas sem autenticação. -
Verbose logging: Habilite este toggle para adicionar dados brutos de requisição e resposta — incluindo headers, parâmetros e bodies — ao log de chamadas quando uma requisição de API é feita. Estes dados aparecem na página API Logs e na página Runtime do Management Console para execuções bem-sucedidas e malsucedidas. O verbose logging 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 Enable debug mode until em seu lugar.
Aviso
O registro detalhado pode incluir dados sensíveis, como credenciais de autenticação ou informações de identificação pessoal. Os valores para cabeçalhos mascarados ficam ocultos, mas parâmetros e corpos são registrados na íntegra. Use esta configuração com cuidado.
-
Ativar modo de depuração até: Ative esta opção para ligar o registro detalhado para solução de problemas e clique no ícone de calendário para selecionar uma data até duas semanas a partir de hoje, quando o modo de depuração se desativa automaticamente. Quando ativado, os dados de solicitação e resposta (mantidos por 30 dias) aparecem na página API Logs, na página Runtime do Management Console e nos registros de operação do Studio para execuções bem-sucedidas e malsucedidas. O registro de depuração no nível de atividade também é ativado, capturando dados de entrada e saída dos componentes na aba Debug Logging. Esta configuração substitui Registro detalhado e Mostrar Payloads de Solicitação e Resposta nos Logs: quando o modo de depuração está ativado, os dados de solicitação e resposta são incluídos nos logs independentemente de essas configurações estarem ativadas.
Aviso
Os registros 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). Com exceção dos valores para cabeçalhos mascarados, esses dados aparecem em texto simples nos registros da nuvem do Harmony por 30 dias.
-
Mostrar Payloads de Solicitação e Resposta nos Logs: Ative esta opção para capturar e exibir os payloads de solicitação e resposta na página API Logs e na página Runtime do Management Console quando uma solicitação de API é feita. Os payloads aparecem em uma visualização formatada com painéis separados para os corpos de solicitação e resposta, para execuções bem-sucedidas e malsucedidas. Esta configuração não gera entradas de registro 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. Esta opção se aplica apenas a APIs personalizadas e serviços OData.
Aviso
Os payloads de solicitação e resposta podem incluir dados sensíveis, como credenciais de autenticação ou informações de identificação pessoal. Use esta configuração com cuidado.
Após configurar a aba Settings, clique em Next para prosseguir para a aba Services ou clique em Prev para voltar à aba Profile.
Aba Services
A aba Services é onde você configura os serviços de API que definem como a API responde às solicitações. É possível configurar múltiplos serviços para uma única API personalizada. Cada serviço deve ter uma combinação única de método HTTP e caminho.

Clique em New Service para adicionar um novo serviço de API. Configure as seguintes definições para cada serviço:
-
Service Name: Insira um nome descritivo para este serviço de API.
-
Method: Selecione o método HTTP para este serviço no menu suspenso. Os métodos disponíveis incluem GET, POST, PUT, DELETE e ALL. Para usar um método não listado, insira o nome do método na caixa de texto Type a new method e pressione Enter.
-
Path: Insira o caminho da URL que dispara este serviço. O caminho é anexado à raiz do serviço na URL de serviço da API.
-
Project: Selecione o projeto Harmony que contém a operação que este serviço dispara. Para migrar uma API personalizada junto com seus projetos do Studio, consulte Include linked Studio projects.
- Go to project: Clique para abrir um projeto do Studio em uma nova aba do navegador. Esta opção está desativada para projetos do Design Studio.
-
Operação a Disparar: Selecione a operação específica do projeto escolhido que este serviço executa quando acionado.
Para informações sobre o que aparece nos logs de operação para operações acionadas por API e como ativar logs adicionais, consulte Dados de solicitação e resposta de API em Logs de operação.
-
Tipo de Resposta: Selecione como a API retorna a resposta da operação. As opções disponíveis incluem Alvo Final, Variável do Sistema e Sem Resposta.
-
Alvo Final: A resposta da API é o alvo final da cadeia de operações. Ao selecionar este tipo de resposta, a operação selecionada deve ter, como alvo final da cadeia de operações, uma atividade Resposta de API do Studio ou uma atividade Gravação de Variável, ou um alvo Resposta de API do Design Studio ou um alvo Variável Global. Se a operação usar qualquer outro alvo final, a resposta da API ficará vazia.
-
Variável do Sistema: A resposta da API é definida em uma variável Jitterbit na cadeia de operações. Ao selecionar este tipo de resposta, a operação selecionada deve ter, como parte da cadeia de operações, um script que defina a variável Jitterbit
jitterbit.api.responseigual à resposta que você deseja que a API retorne. Se o script não definir esta variável, a resposta da API ficará vazia. -
Sem Resposta: A resposta da API fica em branco. Se a solicitação para executar a operação selecionada for aceita, a API retornará uma resposta vazia imediata com código HTTP 202.
-
-
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 da API.
- Ir para operação: Clique para abrir o projeto do Studio em uma nova aba do navegador. A operação no campo Operação a Disparar é realçada na tela de design do Studio. Esta ação está desativada para operações do Design Studio.
- Duplicar: Clique para duplicar o serviço de API.
- Excluir: Clique para excluir o serviço de API.
Após configurar as definições básicas do serviço, você pode configurar parâmetros adicionais usando as abas abaixo da configuração do serviço:
Aba Parâmetros de Caminho
Quando parâmetros de solicitação são incluídos no Caminho, esta aba exibe os parâmetros definidos no caminho:

-
Parâmetro: Exibe cada parâmetro de solicitação definido no Caminho.
-
Descrição: Opcionalmente, insira uma descrição para o parâmetro de solicitação.
Aba Parâmetros de Consulta
Esta aba permite adicionar parâmetros de consulta ao serviço de API:

-
Adicionar Parâmetro: Clique para adicionar um parâmetro de consulta ao serviço de API. Os campos a seguir ficam disponíveis:
-
Parâmetro: Insira o nome do parâmetro de consulta.
-
Descrição: Opcionalmente, insira a descrição do parâmetro de consulta.
-
Excluir: Clique no ícone de exclusão ao lado de um parâmetro de consulta para excluir esse parâmetro.
-
Aba Cabeçalhos
Esta aba permite adicionar cabeçalhos de solicitação ao serviço de API:

-
Adicionar Cabeçalho: Clique para adicionar um cabeçalho de solicitação ao serviço de API. Os campos a seguir ficam disponíveis:
- Parâmetro: Insira o nome do cabeçalho de solicitação.
-
Descrição: Opcionalmente, insira uma descrição para o cabeçalho da solicitação.
-
Obrigatório: Marque a caixa de seleção para tornar este cabeçalho obrigatório para solicitações de API.
-
Excluir: Clique no ícone de exclusão ao lado de um cabeçalho de solicitação para excluir esse cabeçalho.
É possível configurar múltiplos serviços para uma única API personalizada. Cada serviço deve ter uma combinação única de método HTTP e caminho.
Use a coluna Ações para editar ou excluir serviços existentes.
Após configurar a guia Serviços, clique em Próximo para ir para a guia Perfis de segurança, ou clique em Anterior para voltar à guia Configurações.
Guia Perfis de segurança
A guia Perfis de segurança é opcional e permite restringir o acesso para consumo da API.

Configure as seguintes opçõ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ásico, OAuth 2.0 ou Chave de API.
-
Nome de usuário: Para autenticação básica, exibe o nome de usuário. Para outros tipos de autenticação, 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.
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.
Dica
As alterações nas atribuições de perfis de segurança são salvas como rascunhos. É necessário publicar a API usando Salvar e publicar para aplicar as alterações e permitir a exclusão de perfis atribuídos anteriormente. Perfis de segurança não podem ser excluídos enquanto aparecem na configuração publicada de qualquer API, mesmo se tiver desatribuído em uma versão de rascunho.
Após configurar a guia Perfis de segurança, clique em Próximo para ir para a guia Funções de usuário, ou clique em Anterior para voltar à guia Serviços.
Guia Funções de usuário
A guia Funções de usuário é opcional e determina quais funções da organização têm acesso à API no API Manager.

Configure as seguintes opções:
-
Função de usuário: O nome da função da organização conforme definido na guia Funções da página Gerenciamento de usuários.
-
Permissões: As permissões atribuídas a esta função, como Leitura ou Admin.
-
Status: Indica se a função está atribuída a esta API. Alterne o status para atribuir ou desatribuir funções.
-
Ações: Passe o mouse sobre uma linha de função de usuário para revelar ações adicionais.
- Ir para função de usuário: Clique para abrir a configuração da função de usuário.
As funções que você seleciona aqui determinam o acesso a esta API específica a partir destas páginas:
- APIs
- Gerenciador de Portal, incluindo a geração de documentação de API
- Portal de API
- Logs de API
- Análise
O acesso à página Perfis de segurança e o acesso para consumir a API não são afetados por esta seleção. O acesso para consumir uma API é controlado pelos perfis de segurança.
Qualquer função de usuário definida com a permissão Admin sempre tem acesso total a todas as APIs e, portanto, não pode ser removida da seleção.
Clique em Nova função de usuário para criar uma nova função de usuário. Para obter instruções, consulte Funções em Gerenciamento de usuários.
Após configurar a aba Funções de usuário, clique em Publicar para publicar a API ou clique em Salvar como rascunho para salvar o progresso.
Opções de salvar e publicar
Após configurar todas as abas obrigatórias, você pode salvar ou publicar a API:
-
Salvar como rascunho: Salva a API com o status Rascunho ou Publicado com Rascunho. APIs de rascunho não contam contra o limite de assinatura da URL da API. 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 da URL da API, mesmo que seu rascunho não seja acessível.
-
Publicar: Salva a API com o status Publicado. A API fica ativa e acessível em até cinco minutos. Uma API publicada conta contra o limite de assinatura da URL da API. Um diálogo indica que a API está ativa:

O diálogo oferece estas opções:
- Copiar URL: Copia a URL de serviço da API para a área de transferência.
- Gerar documento OpenAPI: Abre a página do Portal Manager, onde você pode gerar documentação de API para todas as APIs em um ambiente. Para gerar documentação de APIs individuais, use a aba Documentação ao editar a API na página APIs.
- Fechar: Fecha o diálogo.
Editar a API
Após salvar a API, você pode editá-la nestas localizações:
- Usando a visualização de cartão na página APIs, clique no cartão.
- Usando a visualização de lista na página APIs, clique em Editar na coluna Ações.
Ao editar uma API publicada a partir da visualização de lista, uma aba Documentação também fica disponível. Use essa aba para visualizar, editar e publicar documentação OpenAPI de APIs individuais. Para obter detalhes, consulte aba Documentação na página APIs.