Pular para o conteúdo principal

Nó admin-api

O nó admin-api fornece acesso direto à API interna do OneEntry. Com ele, é possível ler e modificar pedidos, páginas, produtos, usuários, coleções e sessões de pagamento diretamente do fluxo de integração — sem a necessidade de escrever requisições HTTP manualmente.

Configurações do nó admin-api​

IMG2

1. Nome​

Campo para especificar o nome do nó.
O nome é exibido na área de trabalho e ajuda a identificar facilmente o nó.
Se deixado em branco, o nó será chamado de admin-api.

Exemplo:

  • Nome do nó: Criar Sessão de Pagamento

2. Tipo​

Seleção da operação da API que será chamada ao passar uma mensagem pelo nó. Esta é uma lista suspensa com pesquisa: as operações são agrupadas por seções da API, e seus nomes são retirados da descrição da API do nó no idioma da interface. Se não houver tradução para esse idioma, os nomes são exibidos no idioma original.

O conjunto de operações depende da versão do OneEntry, portanto, consulte a lista exata na lista suspensa Tipo. As operações abrangem:

  • páginas e produtos — por exemplo, "Atualização do objeto da página", "Buscando todos os objetos de página de produto com paginação e filtros.", obtendo vários produtos por identificadores;
  • usuários — incluindo a busca de usuários;
  • valores de atributos — incluindo a atualização de valores de atributos de várias entidades ao mesmo tempo;
  • pedidos — alteração do status do pedido, aplicação de gatilho de status, devoluções;
  • sessões de pagamento — por exemplo, "Criação de sessão de pagamento" e "Atualização de sessão de pagamento";
  • saldo de bônus — ajuste manual do saldo do usuário;
  • registros de coleções — por exemplo, "Recuperando todos os registros pertencentes a uma coleção.".

Após selecionar a operação, os campos Parâmetros de consulta e Corpo da requisição são preenchidos com um exemplo da descrição da API — basta inserir seus próprios valores.

3. Parâmetros de consulta​

Parâmetros da requisição. O caminho e o método HTTP do nó são automaticamente retirados da operação selecionada, não podendo ser editados no formulário. Os valores dos parâmetros de caminho (por exemplo, o identificador do registro) são definidos neste mesmo campo junto com os parâmetros da URL da requisição.

O campo utiliza a sintaxe Mustache — os valores de msg podem ser inseridos através de {{variável}}.

Exemplo (para a operação "Recuperando todos os registros pertencentes a uma coleção."):

{
  "entityType": "orders",
  "entityId": "{{orderId}}",
  "langCode": "pt_BR",
  "offset": 0,
  "limit": 1,
  "marker": "delivery"
}

4. Corpo da requisição​

Corpo da requisição no formato JSON. O campo é exibido apenas para operações com métodos POST, PUT e PATCH. Suporta Mustache para inserção de dados de msg.

Exemplo (para a operação "Criação de sessão de pagamento"):

{
  "orderId": {{orderId}},
  "type": "session"
}

5. Esquema de Entrada​

O bloco Esquema de Entrada é exibido nas configurações do nó e mostra a estrutura dos dados que vêm do nó anterior no fluxo. O esquema é apresentado na forma de pares "chave — tipo", considerando a profundidade dos objetos.

Se os campos do esquema estiverem na descrição da API, descrições textuais são exibidas ao lado deles. Essas mesmas descrições são capturadas pelo editor de código como dicas ao escrever templates Mustache.

Exemplo de exibição do Esquema de Entrada:

payload
  └── order
        ├── id           (integer)  — Identificador do pedido
        ├── status       (string)   — Status atual
        └── totalPrice   (number)   — Valor total

6. Botão Executar​

O botão Executar permite chamar a requisição da API diretamente do formulário de edição do nó, sem precisar executar todo o fluxo.

Como funciona:

  • O servidor executa todo o fluxo desde o início até este nó, passando os dados pela cadeia de acordo com o último estado publicado do fluxo.
  • Se algum nó function ao longo do caminho não passar dados adiante, mas tiver o campo Exemplo de Saída (JSON) preenchido, esses dados são usados como teste.
  • Em caso de resposta bem-sucedida, a resposta da API é passada para o próximo nó como esquema.
  • Se a requisição retornar um erro — o esquema não é passado para o próximo nó.
info

Antes de usar o botão Executar, certifique-se de que o fluxo está publicado. O servidor executa a cadeia com base no estado da última publicação.

Impacto no esquema:

O nó admin-api inicialmente possui um esquema de resposta da descrição da API. Ao clicar em Executar, o esquema é sobrescrito pela resposta real da API. Nesse processo, os campos que coincidem com a descrição da API mantêm suas descrições textuais.

7. Chamada automática de requisições somente leitura​

Todos os nós admin-api que realizam requisições apenas de leitura (GET) são chamados automaticamente:

  • ao abrir a página de Integrações,
  • ao atualizar o fluxo através do botão Publicar.

Isso garante que sempre haja um esquema de dados atualizado no próximo nó sem a necessidade de execução manual.

Exemplos de uso​

Exemplo 1: Criação de sessão de pagamento​

Configurações do nó:

  • Tipo: Criação de sessão de pagamento
  • Corpo da requisição: 
    {
      "orderId": {{orderEvent.order.id}},
      "type": "session"
    }

Resultado:
O nó cria uma sessão de pagamento, utilizando orderId da mensagem de entrada, e passa os dados da nova sessão para o próximo nó.

Exemplo 2: Atualização do status do pedido​

Configurações do nó:

  • Tipo: Atualizando o status de um pedido pertencente ao objeto de armazenamento de pedidos
  • Parâmetros de consulta: 
    {
      "id": {{orderId}}
    }
  • Corpo da requisição: 
    {
      "status": "{{newStatus}}"
    }

Resultado:
O nó atualiza o status do pedido, utilizando os dados da mensagem de entrada.

Exemplo 3: Recuperação de registros de coleção​

Configurações do nó:

  • Tipo: Recuperando todos os registros pertencentes a uma coleção.
  • Parâmetros de consulta: 
    {
      "entityType": "delivery",
      "entityId": "{{payload.id}}",
      "langCode": "pt_BR",
      "offset": 0,
      "limit": 10
    }

Resultado:
O nó retorna uma lista de registros da coleção. Como esta é uma requisição somente leitura, ao abrir a página, o esquema de resposta é carregado automaticamente.