Chamada de API

A Chamada de API deixa a esteira perguntar ao seu sistema no meio da análise ou da formalização, e decidir com a resposta, sem código do seu lado para orquestrar o fluxo. A etapa está disponível para todas as organizações, sem módulo à parte.

​

Como funciona

A chamada sai de dentro da execução, de forma assíncrona. A execução espera a resposta e continua sozinha.

​

A conexão

A conexão guarda o que é fixo e secreto. Ela é cadastrada em Configurações, Integrações, Conexões de API (veja Integrações). Chaves, senhas, certificados e tokens ficam cifrados e nunca voltam para a tela. Nos registros da chamada, os segredos aparecem mascarados.

​

Autenticação

Como validar a assinatura HMAC

A GYRA+ calcula um HMAC em hexadecimal, com SHA-256 ou SHA-512, usando o segredo da conexão, e envia no header que você configurar. Há dois formatos de conteúdo assinado:

• Corpo: assina o corpo cru da requisição (texto vazio quando não há corpo).
• Método, caminho, corpo e horário: assina METODO\n/caminho?query\ncorpo\ntimestamp, com o timestamp em segundos (epoch). O timestamp vai num header próprio, por padrão X-Timestamp.

Do seu lado, recalcule com o mesmo segredo e compare. No segundo formato, recuse timestamps muito antigos para evitar reenvio malicioso.

​

Proteções sempre ligadas

• A URL base da conexão começa com https://: “A URL base precisa ser https://. Chamada sem criptografia não sai da Gyra.”
• Redirecionamentos são seguidos. Se o redirecionamento leva a outro endereço (protocolo, host ou porta diferentes), a GYRA+ não repassa a autenticação nem os headers da conexão.
• A resposta pode ter até 2 MB.
• Segredos mascarados nos registros.

​

O pedido

A etapa define método, caminho, parâmetros, headers e corpo. Quando há corpo JSON e você não define Content-Type, a GYRA+ envia application/json. Sem Accept definido, envia Accept: application/json.

​

Variáveis no pedido

Escreva {{nome}} no caminho, na query, nos headers ou no corpo. No caminho, o valor é codificado para URL. No corpo, entra como valor JSON válido. Além dessas, vale qualquer variável da esteira: dados da proposta, dados de entrada, resultados de etapas anteriores e respostas de chamadas anteriores. Variável sem valor não vira campo vazio. Se uma variável do pedido não tem valor na hora, a GYRA+ não chama o seu sistema e a etapa para com o motivo: “Variável X sem valor”.

​

A resposta

A resposta precisa ser JSON para a etapa extrair campos. Cada campo configurado tem: A conversão aceita formatos comuns: Valor que não converte para o tipo conta como ausente.

​

Onde a resposta é usada

As variáveis api.<apelido> ficam disponíveis para as etapas seguintes: a condição Executar quando, as fórmulas da Decisão, o contrato e outras chamadas de API. Uma etapa não enxerga a resposta de uma chamada que vem depois dela.

​

A decisão da etapa

As regras são opcionais. Sem regra, a etapa só busca os dados e segue. A ordem de avaliação:

1. Seu sistema recusou o pedido (4xx): analista. “O sistema chamado recusou o pedido. Veja a resposta, corrija e reenvie, ou decida.”
2. A chamada não foi concluída: analista. “A chamada de API não foi concluída (tempo esgotado, rede ou erro no sistema chamado). Reenvie ou decida.”
3. Falta um campo obrigatório: analista. “A resposta da API veio sem “X”, que é uma saída obrigatória.”
4. Reprovar se verdadeiro: reprova.
5. Mandar para o analista se verdadeiro: analista.
6. Regra que não pode ser calculada: analista, com o motivo.
7. Nenhuma das anteriores: segue.

​

Tempo, falhas e novas tentativas

• Limite de tempo de cada chamada: de 1 a 30 segundos, padrão 15. A tela oferece 5, 10, 15 ou 30 segundos.
• Se a API falhar: quanto tempo a etapa espera uma resposta final antes de ir ao analista. A tela oferece 1, 4, 24 ou 72 horas (padrão 72, máximo 720).
• Na página da execução, o analista pode Reenviar (“Chamar a API de novo?”) depois de corrigir o que for preciso, ou decidir a etapa.

​

Testar antes de ativar

No construtor, Testar com uma proposta faz a chamada de verdade com a etapa salva e mostra Requisição enviada, Resposta e Variáveis extraídas. Segredos aparecem mascarados e nada é gravado na proposta. Clique numa chave da resposta para criar o campo de saída. Para ativar a esteira, a etapa precisa de conexão, método e caminho.

​

Checklist para o seu endpoint

​

Próximos passos