Elementos Personalizados: API
Uma interface de API é um formulário cujos valores preenchidos o Skava envia como JSON para um endereço que especifica (o seu servidor). Desta forma, pode ligar o Skava com segurança aos seus próprios sistemas.
Gere interfaces de API na Aplicação Web em Elementos Personalizados → alterne Interfaces de API. A criação e edição é reservada a administradores de empresa; as interfaces lançadas podem então ser acionadas por todos os membros da empresa.
Configurar uma interface de API
Uma interface consiste em campos de entrada (formam o JSON), o endereço alvo e autenticação.
- Crie campos: Cada campo obtém uma chave JSON. À direita vê em tempo real a pré-visualização JSON, que é enviada para o seu servidor exatamente desta forma.
- Endereço (URL): o endereço
https://do seu servidor. Apenas endereços HTTPS e publicamente acessíveis são permitidos (veja Segurança abaixo). - Método:
POST(padrão),PUT,PATCHouGET. ComGETos valores são anexados como parâmetros de consulta em vez de serem enviados no corpo. - Autenticação: Defina o nome do cabeçalho (p.ex.
Authorization) e prefixo de valor (p.ex.Bearer), então guarde o token. Opcionalmente defina uma data de expiração. - Campos de resposta (opcional): Defina por caminho quais valores da resposta do servidor devem ser exibidos — p.ex.
order.idouitems[0].sku. - Verifique com Ping e Pedido de Teste, depois Lançar.
Guarde o token com segurança
O token é guardado encriptado e nunca é devolvido aos clientes — a aplicação apenas mostra se um token é definido e quando expira. Ao enviar, o Skava anexa-o servidor-lado ao cabeçalho configurado. Se definir uma data de expiração, o Skava recusa a chamada após expiração e pede-lhe para renovar o token.
Teste: Ping e Pedido de Teste
- Ping — uma verificação de acessibilidade leve. Apenas verifica se o seu endereço responde, e não envia token ou dados de formulário no processo. Mostra acessibilidade, estado e tempo de resposta. Ideal como primeiro passo.
- Pedido de Teste — o teste real: envia dados de amostra incluindo token para o seu endereço e mostra-lhe a resposta completa bem como os campos de resposta extraídos.
Como admin, pode executar ambos enquanto ainda em modo rascunho para verificar a integração antes do lançamento.
Rascunho e Lançamento
Cada interface começa como um rascunho e pode ser editada livremente. Quando tudo está pronto, lança-a com Lançar.
As interfaces lançadas são imutáveis. Isto é intencional: para que após o lançamento ninguém possa secretamente trocar o endereço alvo ou token. Se quiser alterar algo, crie uma nova versão.
Segurança
Para prevenir o mau uso da interface, regras rigorosas aplicam-se: apenas endereços HTTPS são permitidos, e o endereço deve apontar para um endereço alvo público — endereços internos (p.ex. localhost, redes privadas ou metadados da nuvem) são rejeitados. O Skava verifica isto em cada chamada, liga-se exatamente ao endereço verificado, não segue redirecionamentos e limita o tempo limite e tamanho da resposta.
Relacionado
Quer construir um modelo de documento preenchível? Veja Elementos Personalizados: Documentos.
Perguntas Frequentes
O que é uma interface de API no Skava?
Um formulário cujos valores preenchidos o Skava envia como JSON para um endereço que especifica (o seu servidor) — útil para ligar o Skava aos seus próprios sistemas.
Quem tem permissão para criar e acionar interfaces de API?
A criação e edição é reservada a administradores de empresa. Uma interface lançada pode então ser acionada por todos os membros da empresa.
Qual é a diferença entre "Ping" e "Pedido de Teste"?
Ping apenas verifica se o endereço é acessível — sem token e sem dados. Pedido de Teste envia dados de amostra incluindo token e mostra a resposta completa.
O meu token de API é seguro?
Sim. O token é guardado encriptado e nunca é entregue aos clientes. A aplicação apenas mostra se um token é definido e quando expira.
Que endereços são permitidos como pontos finais?
Apenas endereços https:// publicamente acessíveis. Alvos internos como localhost, redes privadas ou metadados da nuvem são rejeitados — isto protege contra mau uso da interface.
Por que não posso alterar uma interface lançada?
As interfaces lançadas são intencionalmente imutáveis — para que após o lançamento ninguém possa trocar o endereço alvo ou token. Para alterações, cria uma nova versão.