Requisição HTTP

Conecte seu fluxo a qualquer sistema externo

O Nó HTTP permite que o Spaceflow se comunique com sistemas externos durante a execução de um fluxo. Com ele, o ENSPACE pode enviar dados para outro sistema, consultar informações externas ou sincronizar dados entre plataformas — tudo de forma automática, sem sair do fluxo.

Quando usar

• Consultar dados em sistemas externos (ex: buscar certidões de um CNPJ, consultar um CEP, verificar saldo em um ERP).
• Conectar dois workspaces do ENSPACE entre si, criando itens em um workspace a partir de eventos em outro.
• Criar ou atualizar registros em outro sistema a partir de eventos no ENSPACE.
• Enviar notificações via webhook para sistemas que aguardam eventos do ENSPACE.

Antes de começar: conceitos fundamentais

Se você já está familiarizado com APIs e requisições HTTP, pule para a seção Conhecendo o nó. Se não, leia esta introdução — ela explica os termos que aparecem ao longo da configuração.

O que é uma API

Uma API (Interface de Programação de Aplicações) é a forma como dois sistemas conversam entre si. Por exemplo, quando o ENSPACE precisa buscar dados em outro sistema ou enviar informações para ele, ele faz isso por meio de uma API — enviando uma mensagem estruturada e recebendo uma resposta.

O que é uma requisição HTTP

Uma requisição HTTP é essa mensagem estruturada. Ela possui quatro partes:

• Método — a ação que você quer realizar. Os mais comuns são GET (consultar dados), POST (criar algo), PUT (atualizar algo) e DELETE (excluir algo).
• URL — o endereço do sistema que você quer acessar. É como a URL de um site, mas aponta para um recurso específico da API (ex: https://api.exemplo.com/certidoes/12345).
• Cabeçalhos (Headers) — informações adicionais enviadas junto com a requisição, como credenciais de autenticação. Pense neles como o "envelope" da mensagem.
• Corpo (Body) — os dados que você envia ao sistema de destino. Usado em requisições POST e PUT. Escrito em formato JSON.

O que é JSON

JSON é o formato de texto que as APIs usam para trocar dados. Ele organiza informações em pares de "nome" e "valor", usando chaves {} e aspas "":

{
  "pessoa": "João Silva",
  "email": "joao@empresa.com",
  "ativo": true
}

O que é autenticação

A maioria das APIs exige que você prove quem é antes de acessar os dados. No ENSPACE, isso é feito por meio de credenciais — tokens de acesso que são enviados automaticamente no cabeçalho da requisição. Você cadastra a credencial uma vez em Configurações > Credenciais e seleciona-a no nó.

O que são variáveis do Spaceflow

Ao configurar o nó HTTP, você encontrará espaços como {{input.data.cnpj}} na URL ou no body. Esses são variáveis — marcadores que o Spaceflow substitui automaticamente pelos dados reais do fluxo no momento da execução. Por exemplo, se o item que disparou o fluxo tem o campo "CNPJ" preenchido com 11.222.333/0001-44, a variável {{input.data.cnpj}} será substituída por esse valor.

O que é um schema de saída

Quando a API retorna dados, você precisa dizer ao ENSPACE quais informações da resposta quer usar nos próximos nós do fluxo. Isso é feito pelo schema de saída — um mapeamento onde você define um nome (chave) para cada dado e indica onde ele está na resposta (caminho de origem). Cada regra do schema cria uma variável que os nós seguintes podem utilizar.

Conhecendo o nó

Para adicionar o nó HTTP ao seu fluxo, clique em Adicionar Nó na edição do Spaceflow, abra a seção Integrações e arraste o nó Requisição HTTP para o canvas. Conecte-o a outro nó clicando no conector (semicírculo) e arrastando a linha.

Ao clicar no nó, suas configurações se abrem em duas abas:

Aba Requisição

Define como o ENSPACE vai se comunicar com o sistema externo. Os campos disponíveis são:

• Método — a ação HTTP: GET (consultar), POST (criar), PUT (atualizar completamente), PATCH (atualizar parcialmente) ou DELETE (excluir). Os demais campos da aba se ajustam conforme o método selecionado.

• URL — o endereço do endpoint da API de destino. Suporta variáveis do Spaceflow (ex: {{input.data.cnpj}}).

• Autenticação — selecione uma credencial cadastrada no workspace. As credenciais são configuradas em Configurações > Credenciais.

• Timeout — tempo máximo de espera pela resposta. Padrão: 30.000 ms (30 segundos).

• Parâmetros de consulta — query parameters adicionados ao final da URL.

• Cabeçalhos (Headers) — o nó já inclui headers predefinidos que podem ser editados. Para adicionar novos, clique em Adicionar.

• Corpo (Body) — disponível para POST, PUT e PATCH. É onde você envia os dados que a API espera receber, em formato JSON com suporte a variáveis.

Aba Resposta

Define o que fazer com os dados que a API retorna. O mapeamento é feito por meio de um Schema de saída — cada regra cria uma variável que pode ser usada nos nós seguintes do fluxo.

Caso de uso guiado

Este exemplo acompanha a configuração completa de um nó HTTP, do início ao fim. O cenário: consultar as certidões de um CNPJ em uma API externa e extrair a situação de cada órgão para uso no restante do fluxo.

O contexto

A Constructa S.A. utiliza o ENSPACE para gerenciar centenas de parceiros em seus canteiros de obras. Para mitigar riscos jurídicos e operacionais, a empresa utiliza a categoria "Fornecedores" como o canal oficial de entrada para novos prestadores de serviço. O objetivo é garantir que nenhuma empresa seja contratada sem estar com suas obrigações fiscais em dia.

O Fluxo

Um item é criado na categoria "Fornecedores". O Spaceflow dispara automaticamente, consulta as certidões do CNPJ informado no item e, com base nas respostas, decide se o cadastro é aprovado ou rejeitado.

A estrutura do fluxo seria: Início (trigger: item criado) → Requisição HTTP (consulta certidões) → Condicional (verifica se todas as situações são "NADA_CONSTA") → próximos passos.

{
  "certidaoPDF": null,
  "certidoes": [
    {
      "dataHoraEmissao": "30/04/2026 20:29",
      "descricao": "Licitantes Inidôneos",
      "emissor": "TCU",
      "linkConsultaManual": "[https://contas.tcu.gov.br/ords/f?p=1660:2:::NO:2](https://contas.tcu.gov.br/ords/f?p=1660:2:::NO:2)",
      "observacao": null,
      "situacao": "NADA_CONSTA",
      "tempoGeracao": 38,
      "tipo": "Inidôneos"
    },
    {
      "dataHoraEmissao": "30/04/2026 20:29",
      "descricao": "CNIA - Cadastro Nacional de Condenações Cíveis por Ato de Improbidade Administrativa e Inelegibilidade",
      "emissor": "CNJ",
      "linkConsultaManual": "[http://www.cnj.jus.br/improbidade_adm/consultar_requerido.php](http://www.cnj.jus.br/improbidade_adm/consultar_requerido.php)",
      "observacao": null,
      "situacao": "NADA_CONSTA",
      "tempoGeracao": 71,
      "tipo": "CNIA"
    },
    {
      "dataHoraEmissao": "30/04/2026 20:29",
      "descricao": "Cadastro Nacional de Empresas Inidôneas e Suspensas",
      "emissor": "Portal da Transparência",
      "linkConsultaManual": "[http://www.portaltransparencia.gov.br/sancoes/ceis](http://www.portaltransparencia.gov.br/sancoes/ceis)",
      "observacao": "Impedimento/proibição de contratar com prazo determinado (09/09/2030)",
      "situacao": "CONSTAM_REGISTROS",
      "tempoGeracao": 91,
      "tipo": "CEIS"
    },
    {
      "dataHoraEmissao": "30/04/2026 20:29",
      "descricao": "CNEP - Cadastro Nacional de Empresas Punidas",
      "emissor": "Portal da Transparência",
      "linkConsultaManual": "[http://www.portaltransparencia.gov.br/sancoes/cnep](http://www.portaltransparencia.gov.br/sancoes/cnep)",
      "observacao": null,
      "situacao": "NADA_CONSTA",
      "tempoGeracao": 91,
      "tipo": "CNEP"
    }
  ],
  "cnpj": "11.222.333/0001-44",
  "dataHoraGeracaoInMillis": 1777591785645,
  "nomeFantasia": null,
  "razaoSocial": "EXEMPLO COMERCIO E SERVICOS LTDA",
  "seCnpjEncontradoNaBaseTcu": true,
  "uf": null
}

Referência técnica

As seções abaixo são material de consulta. Use-as quando precisar verificar uma sintaxe, entender um campo ou resolver um problema.

Métodos HTTP disponíveis

Variáveis do Spaceflow

O nó HTTP aceita variáveis na URL, no body e nos cabeçalhos. A sintaxe é {{variavel}} — sem espaços dentro das chaves.

As variáveis do Spaceflow usam sintaxe própria (ex: {{input.data.nome}}), diferente das variáveis de formatação usadas em outros contextos da plataforma como templates de documento ou e-mail.

Corpo da requisição (Body)

Disponível para POST, PUT e PATCH. Aceita JSON com variáveis.

Cuidados:

• Evite tags HTML no body — use \n para quebras de linha.
• Variáveis vazias são substituídas por vazio.
• Valide o JSON em jsonlint.com antes de salvar.
• Apenas JSON — o nó não suporta upload de arquivos (multipart/form-data).

Schema de saída (aba Resposta)

Autenticação

A credencial cobre apenas o header configurado nela (ex: x-api-key). Se a API exigir headers adicionais (como en-workspace para a API do ENSPACE), adicione-os manualmente em Cabeçalhos.

As credenciais são cadastradas em Configurações > Credenciais.

Configurações adicionais

• Timeout — tempo máximo de espera. Padrão: 30.000 ms (30 segundos).
• Parâmetros de consulta — query parameters adicionados ao final da URL.
• Cabeçalhos — headers customizados enviados com a requisição.

Comportamento em caso de erro

Quando a requisição falha, o fluxo é interrompido. O nó retorna:

Para evitar a interrupção, conecte um nó Condicional ou Rotas após o HTTP e trate o erro por error_type.

Exemplos Práticos

Abaixo, veja como configurar o nó para os cenários mais comuns, incluindo a comunicação entre diferentes ambientes do ENSPACE.

1. Comunicação entre Workspaces (Cross-Workspace)

Você pode usar o Spaceflow para conectar diferentes áreas da sua empresa. Diferente dos nós nativos, o nó HTTP permite que o Workspace A execute ações no Workspace B como se fosse um usuário externo, garantindo independência entre os fluxos.

Cenário A: Criar um item em outro workspace

Ideal para enviar demandas de uma equipe de Vendas para o time de Operações.

Corpo (Body):

{
  "form": "default",
  "data": {
    "titulo": "Nova Demanda: {{input.data.assunto}}",
    "prioridade": "{{input.data.prioridade}}",
    "origem_id": "{{input.reference}}"
  }
}

Cenário B: Notificar outro workspace ("Receber chamada")

Use este modelo quando um workspace precisar "avisar" outro que um item foi criado, disparando uma automação no destino via Webhook.

• No Workspace de Origem: Configure o nó HTTP abaixo:

Corpo (Body):

{
  "mensagem": "Um novo item foi criado e precisa de atenção.",
  "item_referencia": "{{input.reference}}",
  "criado_por": "{{input.created_by}}"
}

2. Consulta de CEP (API Pública)

Ao digitar um CEP no formulário, o fluxo busca o endereço completo automaticamente.

Mapeamento de Saída (Schema): Configure o schema para que os dados apareçam como variáveis nos nós seguintes:

3. Atualizar Status em Sistema Externo

Utilize este cenário para manter sistemas legados ou ERPs sincronizados quando um processo é concluído dentro do ENSPACE.

Corpo (Body):

{
  "status": "concluido",
  "finalizado_em": "{{now}}",
  "observacoes": "Aprovado via fluxo Spaceflow: {{input.reference}}"
}

Tutorial guiado