Elementos personalizados: API

Uma interface de API é um formulário cujos valores preenchidos o Skava envia como JSON para um endereço que você especifica (seu backend). Dessa forma, você pode conectar o Skava com segurança aos seus próprios sistemas.

Configurar uma interface de API

Uma interface consiste em campos de entrada (que formam o JSON), o endereço de destino e a autenticação.

1. Criar campos: Cada campo recebe uma chave JSON. À direita, você vê ao vivo a pré-visualização JSON, que é enviada para o seu backend exatamente desta forma.
2. Endereço (URL): o endereço https:// do seu backend. Apenas endereços HTTPS e acessíveis publicamente são permitidos (veja Segurança abaixo).
3. Método: POST (padrão), PUT, PATCH ou GET. Com GET, os valores são adicionados como parâmetros de consulta em vez de serem enviados no corpo.
4. Autenticação: Defina o nome do cabeçalho (ex.: Authorization) e o prefixo do valor (ex.: Bearer ), depois salve o token. Opcionalmente, defina uma data de expiração.
5. Campos de resposta (opcional): Defina por caminho quais valores da resposta do backend devem ser exibidos: ex.: order.id ou items[0].sku.
6. Verifique com Ping e Test Request, depois Release.

Armazenar token com segurança

O token é armazenado criptografado e nunca é retornado aos clientes: o app mostra apenas se um token está definido e quando expira. Ao enviar, a Skava o anexa no servidor ao cabeçalho configurado. Se você definir uma data de expiração, a Skava recusa a chamada após o vencimento e pede que você renove o token.

Testes: Ping e Requisição de Teste

• Ping : verificação leve de acessibilidade. Verifica apenas se o seu endereço responde, sem enviar token ou dados de formulário no processo. Exibe acessibilidade, status e tempo de resposta. Ideal como primeiro passo.
• Test Request : o teste real: envia dados de exemplo incluindo token para o seu endereço e exibe a resposta completa, bem como os campos de resposta extraídos.

Como administrador, você pode executar ambos ainda em modo rascunho para verificar a integração antes da liberação.

Rascunho e Publicação

Cada interface começa como um rascunho e pode ser editada livremente. Quando tudo estiver pronto, você a publica com Publicar.

Segurança

Como a equipe utiliza uma interface publicada

Assim que uma interface é publicada, todos os membros da empresa podem ativá-la diretamente de um chat, sem necessidade de editor. Não há entrada coletiva nem diálogo intermediário: cada elemento publicado aparece no menu de adição com seu próprio nome, acompanhado do logotipo da empresa que o oferece.

1. No chat, toque em Adicionar na parte inferior e toque no elemento desejado, por exemplo Pedido de material.
2. Preencha o formulário e toque em Enviar.
3. O resultado aparece como um cartão no chat, visível para todos os participantes da conversa.

Deixe a IA criar um elemento

Como administrador da empresa, você não precisa usar o editor diretamente. Diga ao assistente Skava no chat, por exemplo, "crie um formulário de pedido para meu catálogo com quantidade e endereço de entrega". Ele cria um rascunho a partir disso, pode alterar campos um a um depois e conhece o catálogo de artigos que você enviou: para pedidos, ele sugere o seletor de produtos em vez de um campo de texto para o número do artigo.

O que ele também pode configurar: ponto de extremidade e método, bem como o público ("apenas membros da empresa" ou "também pessoas externas no mesmo chat"). Para o público, ele pergunta primeiro em vez de apenas definir, porque isso decide quem pode executar algo de fora.

O que ele explicitamente não toca: o token de acesso. Ele nunca pede um e nunca aceita um, porque as mensagens do chat são armazenadas. Você insere o token você mesmo no editor, caso contrário nenhuma chamada é feita. E ele não pode publicar: o último passo fica com você, para que nada fique visível para os clientes sem verificação.

Quem pode executar

A aba "Ponto de Extremidade" indica quem pode usar um elemento. O padrão são os membros da sua empresa. A segunda configuração abre para pessoas externas, mas apenas em um chat onde alguém da sua empresa também está presente: exatamente o caso para o qual foi criado, o cliente fazendo um pedido para você. Quando sua empresa sai do chat, a permissão termina automaticamente.

Produtos do seu próprio catálogo

Depois de carregar o seu catálogo de artigos, o construtor oferece um bloco de seleção de produto. Não há opções para manter: a lista é o seu catálogo. A pessoa que faz o pedido pesquisa nela, vê a imagem, o nome e o número do artigo, e o seu backend recebe o número do artigo. A Skava rejeita um número que não esteja no seu catálogo. Para a quantidade, coloque um campo numérico normal ao lado.

Defina o cartão por si

O seu backend decide o que o cartão diz. A Skava apenas verifica a forma, o tamanho e a segurança, nunca o significado: não conhece estados de pedido nem nomes de campos. Para isso, responda com um objeto card:

{"card": {"v": 1, "title": "Order 10001", "state": "pending", "status_text": "Being picked", "fields": [{"label": "Tracking number", "value": "DPD123456789"}]}}

• v deve ser o inteiro 1. Sem ele, a resposta não conta como cartão e aplica-se o mapeamento de resposta configurado no elemento.
• state é apenas cor e ícone: ok, pending, warn ou error. Tudo que carrega significado vai para status_text como texto livre.
• fields é uma lista de rótulos e valores, com no máximo 20 entradas. Valores muito longos são encurtados em vez de rejeitados, para que um pedido nunca falhe por um detalhe.

As entradas do usuário pertencem ao servidor: permanecem intactas, independentemente do que seu backend enviar. Elas são o registro no chat do que foi efetivamente submetido.

Relatando o status posteriormente

Quando o elemento é executado, o Skava envia dois valores extras: callback_url e callback_token. Relate um novo estado lá mais tarde e um novo cartão aparecerá no chat, também no celular, enquanto alguém estiver olhando. O anterior permanece, para que seja legível qual estado foi relatado. Envie o mesmo objeto card acima, via POST com o cabeçalho Authorization: Bearer <callback_token>. Três valores opcionais vão ao lado do cartão:

• seq: seu contador. Um relatório com valor menor ou igual é descartado, para que dois relatórios não se sobreponham.
• final: encerra a interação. O token fica inválido e o cartão é final.
• notify: defina como false para publicar o cartão em silêncio, sem contador de não lidos e sem notificação. Para etapas intermediárias que não devem acordar ninguém. Sem isso, o cartão é uma mensagem perfeitamente normal.

Uma interação pode publicar no máximo 50 cartões. O mesmo relatório duas vezes não gera um segundo cartão.

A Skava responde com 200 e uma lista de hints se algo foi encurtado ou descartado, e com 422 se o cartão foi inutilizável. Uma interação aceita relatórios por 90 dias.

Os cartões são publicados pelo remetente do sistema da Skava, não pela pessoa que executou o elemento nem por uma conta da sua empresa. O título do cartão indica de qual sistema a mensagem foi enviada.

Um exemplo completo para copiar está no repositório em example_order_server/ e é executado em api.skava.io.

Relacionados

Você quer criar um modelo de documento preenchível? Veja Elementos Personalizados: Documentos.

Perguntas Frequentes