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 de forma segura 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ê em tempo real a visualização JSON, que é enviada ao seu backend exatamente assim.
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 anexados como parâmetros de consulta em vez de serem enviados no corpo.
4. Autenticação: Defina o nome do cabeçalho (por exemplo, Authorization) e o prefixo do valor (por exemplo, Bearer ), em seguida, salve o token. Opcionalmente, defina uma data de expiração.
5. Campos de resposta (opcional): Defina pelo caminho quais valores da resposta do backend devem ser exibidos: por exemplo, order.id ou items[0].sku.
6. Verifique com Ping e Test Request, depois Release.

Armazenar o token com segurança

O token é armazenado criptografado e nunca retornado aos clientes: o aplicativo mostra apenas se um token está definido e quando expira. Ao enviar, o Skava o anexa no lado do servidor ao cabeçalho configurado. Se você definir uma data de expiração, o Skava recusará a chamada após a expiração e solicitará a renovação do token.

Testes: Ping e Test Request

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

Como administrador, você pode executar ambos enquanto ainda estiver no modo de 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 lançada

Uma vez que uma interface é lançada, todos os membros da empresa podem ativá-la diretamente de um chat: sem necessidade de editor. O fluxo é o mesmo que com modelos de documentos: selecionar, preencher, enviar.

1. No chat, toque em Mais na parte inferior e escolha Elemento Personalizado.
2. Selecione o modelo ou interface desejado na lista.
3. Preencha o formulário e Envie.
4. O resultado aparece como um cartão no chat: visível para todos no chat.

Deixe a IA criar um elemento

Como administrador da empresa, você não precisa usar o editor. Peça ao assistente do 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 com base nisso, pode alterar campos um por um depois e conhece seu catálogo de artigos carregado: 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 definir: 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, pois 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, pois as mensagens do chat são armazenadas. Você o insere você mesmo no editor, caso contrário nenhuma chamada é enviada. E ele não pode publicar: o último passo fica com você, para que nada fique visível aos clientes sem verificação.

Quem pode executá-lo

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 o abre para pessoas externas, mas apenas em um chat onde alguém da sua empresa também esteja presente: exatamente o caso para o qual foi projetado, o cliente fazendo um pedido com você. Quando sua empresa sai do chat, a permissão termina automaticamente.

Produtos do seu próprio catálogo

Depois de fazer o upload do seu catálogo de artigos, o construtor oferece um bloco de seleção de produtos. 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. O 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 você mesmo

O seu backend decide o que o cartão diz. O Skava verifica apenas a forma, o tamanho e a segurança, nunca o significado: ele não conhece estados de pedido nem nomes de campo. Para fazer 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 um cartão e o mapeamento de resposta configurado no elemento é aplicado.
• state é apenas cor e ícone: ok, pending, warn ou error. Tudo o que carrega significado vai para status_text como texto livre.
• fields é uma lista de rótulo e valor, com no máximo 20 entradas. Valores muito longos são encurtados em vez de rejeitados, para que um pedido nunca falhe por causa de um detalhe.

As entradas do usuário pertencem ao servidor: permanecem inalteradas, independentemente do que seu backend envie. Elas são o registro no chat do que foi realmente enviado.

Relatar o status posteriormente

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

• seq: seu próprio contador. Um relatório com um valor menor ou igual é descartado, para que dois relatórios não possam se ultrapassar.
• final: encerra a interação. O token torna-se inválido e o cartão fica finalizado.
• notify: defina como false para publicar o cartão silenciosamente, sem contagem 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 produz um segundo cartão.

O 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 e não por uma conta da sua própria empresa. O título do cartão indica qual sistema está escrevendo.

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

Relacionado

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

Perguntas Frequentes