A integração com a Appmax permite processar pagamentos por cartão de crédito, boleto e Pix no checkout da sua loja Uappi.
A configuração é realizada nos painéis da Appmax e da Uappi. Durante o procedimento, será necessário copiar credenciais e outras informações de uma plataforma para a outra.
Antes de começar
Tenha em mãos:
● Acesso a uma conta ativa na Appmax;
● Acesso ao Painel Administrativo da Uappi;
● Permissão para acessar as configurações da Uappi;
● URL da loja;
● CNPJ da empresa que será vinculada à integração.
A página de vendas informada na Appmax deve estar vinculada ao mesmo CNPJ selecionado durante a configuração.
Instalando a integração na Appmax
Acesse o Painel Administrativo da Appmax e siga os passos:
1. No menu lateral, clique em Aplicativos;
2. Localize a opção Uappi;
3. Clique em + Instalar.
A configuração será dividida em três etapas: Dados Gerais, Afiliação Appmax e Credenciais Uappi.
Preenchendo os Dados Gerais
Na etapa Dados Gerais, preencha as informações da loja:
● Nome da Loja: nome utilizado para identificar a loja dentro da Appmax; ● Empresa: empresa à qual a loja será vinculada;
● Domínio: subdomínio que será utilizado pela Appmax, com o limite de 16 caracteres;
● Página de Vendas: endereço do site ou da página de vendas vinculada ao CNPJ da empresa;
● Modelo de Negócio: modelo correspondente à operação da loja. Caso não encontre uma opção adequada, selecione Outros;
● E-mail de suporte: endereço disponibilizado para o atendimento aos consumidores; ● Telefone de suporte: telefone disponibilizado para o atendimento aos consumidores.
O domínio informado não precisa ser igual ao domínio principal do seu site. Após a configuração, os links gerados pela Appmax poderão utilizar o endereço sualoja.app.com.br.
Configurando a Afiliação Appmax
Na etapa Afiliação Appmax, copie o token exibido na tela. Esse código será utilizado na configuração do conector dentro da Uappi.
Tokens e senhas são informações confidenciais. Oculte os valores
apresentados nos prints.
Inserindo o token na Uappi
Acesse o Painel Administrativo da Uappi e siga o caminho:
Configurações > Pagamentos > Pagamento/Gerenciamento
Na seção de conectores:
1. Localize a opção Appmax;
2. Acesse a edição do conector;
3. Insira o token copiado anteriormente;
4. Configure a opção Alterar status do pedido quando a transação for cancelada, de acordo com a operação da loja;
5. Configure a opção Considerar status aprovado como pago, conforme a regra utilizada pela loja;
6. Salve as alterações.
Caso a opção Homologação esteja visível no conector, ela poderá ser utilizada para definir o ambiente de testes. Essa opção é restrita e está disponível para usuários com perfil Admin Master. Para os demais perfis, o campo pode não ser exibido.
Informando a URL de callback
Retorne à etapa Afiliação Appmax.
No campo URL de callback Uappi, informe a URL principal da loja seguida de: /api/v2/thirdparty/appmax/callback
Exemplo:
https://www.sualoja.com.br/api/v2/thirdparty/appmax/callback
Utilize somente a URL principal da loja seguida do caminho informado.
Configurando as credenciais da Uappi na Appmax
Na última etapa da instalação, a Appmax precisa das credenciais de API da Uappi para estabelecer a comunicação entre as plataformas.
Criando a integração de API na Uappi
Acesse o Painel Administrativo da Uappi e siga o caminho:
Configurações > Integrações > API
Na tela de APIs, verifique se já existe uma integração chamada AppMax.
● Caso a integração já exista, clique no botão de edição;
● Caso ainda não exista, clique em Nova integração e realize o cadastro.
Ao criar uma nova integração, ela é cadastrada inicialmente como inativa. Após preencher os dados, será necessário ativá-la e configurar as permissões de acesso aos recursos da API utilizados pela integração.
As credenciais são disponibilizadas após salvar a integração. Para consultá-las, acesse novamente a integração cadastrada e utilize a opção Visualizar credenciais.
Configurando as permissões da API
Para que a Appmax consiga consultar e enviar informações pela API da Uappi, a integração precisa possuir acesso aos recursos necessários da API v2.
Na configuração da integração, verifique as permissões de acesso aos endpoints. Caso essas permissões não estejam configuradas, as requisições realizadas pela Appmax poderão retornar erro 403 (acesso não autorizado ao recurso).
Na seção Endpoints permitidos na integração, adicione os métodos e os endpoints da API v2 usados pela Appmax.
Integrações novas são criadas sem permissões de endpoints; sem essa configuração, as chamadas podem retornar erro 403.
Depois de configurar as permissões necessárias, salve as alterações.
Copiando as credenciais da API
Na edição da integração AppMax:
1. Confira se o campo Nome está preenchido como AppMax;
2. Marque Sim em Ativo;
3. Configure as permissões de acesso aos recursos da API necessários para a integração;
4. Salve as alterações;
5. Acesse a opção Visualizar credenciais;
6. Copie a Chave de API (Api Key);
7. Copie a Chave de Segurança (Secret Key).
Essas credenciais serão utilizadas na configuração da Appmax.
Importante: a Chave de API e a Chave de Segurança são informações confidenciais. Ao utilizar prints em documentos ou atendimentos, oculte completamente esses valores.
Inserindo as credenciais na Appmax
Retorne ao painel da Appmax e acesse a etapa Credenciais Uappi. Preencha os campos da seguinte forma:
● Em API Key, insira a Chave de API (Api Key) copiada da Uappi; ● Em Secret Key, insira a Chave de Segurança (Secret Key) copiada da Uappi.
Informando a URL da loja
No campo URL da loja Uappi, informe a URL principal da loja seguida de /api. Exemplo:
https://www.sualoja.com.br/api
Informando o ID do vendedor interno
Na Uappi, siga o caminho:
Configurações > Módulos > Usuários
Localize o usuário que será utilizado como vendedor interno pela integração Appmax e clique em Editar. Caso ainda não exista um usuário destinado à integração, será necessário cadastrá-lo antes de continuar.
Na página de edição, verifique a URL apresentada no navegador. O código exibido no final da URL corresponde ao ID do vendedor interno.
Por exemplo:
https://painel.sualoja.com.br/configuracao/usuario/editar/123
Nesse exemplo, o ID do vendedor interno é 123.
Retorne à Appmax e insira o código no campo ID vendedor interno.
Salvando a integração
Confira se as três etapas foram preenchidas corretamente:
● Dados Gerais;
● Afiliação Appmax;
● Credenciais Uappi.
Depois, clique em Salvar para concluir a configuração da loja na Appmax.
Habilitando as formas de pagamento na Uappi Depois de salvar a integração na Appmax, acesse novamente:
Configurações > Pagamentos > Pagamento/Gerenciamento
Localize as formas de pagamento desejadas, acesse a edição e selecione a Appmax como conector.
A integração oferece suporte a:
● Cartão de crédito;
● Boleto;
● Pix.
Depois de realizar as configurações, clique em Salvar.
Repita o procedimento para cada forma de pagamento que será processada pela Appmax.
Configurações complementares
Cadastro dos produtos
Os produtos devem ser cadastrados manualmente na Appmax.
Quando o preço de um produto for alterado na Uappi, o mesmo valor também deverá ser atualizado na Appmax, pois essa informação não é sincronizada automaticamente.
Juros e parcelamento
Os juros configurados na Uappi devem ser iguais aos cadastrados na Appmax. Isso evita que o valor parcelado apresentado no checkout seja diferente do valor processado.
Descrição na fatura
Nas credenciais da Appmax na Uappi, o campo de descrição na fatura permite definir o nome que será apresentado na fatura do cartão do consumidor.
O campo é opcional e aceita até 13 caracteres.
Testando a integração
Depois de concluir as configurações, realize um pedido de teste e verifique se:
● A forma de pagamento está disponível no checkout;
● O pagamento é processado pela Appmax;
● O pedido é criado na Uappi;
● O status do pagamento é atualizado;
● Os juros e valores estão corretos.
Caso a opção Homologação esteja disponível no conector Appmax, ela poderá ser utilizada nos testes. O campo é restrito a usuários com perfil Admin Master e pode não aparecer para outros perfis.
Antes de iniciar a operação em produção, confirme que o conector está utilizando o ambiente correto.
Perguntas frequentes
Onde encontro as credenciais da API da Uappi?
No Painel Administrativo da Uappi, acesse Configurações > Integrações > API. Localize a integração AppMax, acesse a edição e utilize a opção Visualizar credenciais para consultar a Chave de API (Api Key) e a Chave de Segurança (Secret Key).
O que fazer se a integração AppMax não estiver cadastrada na API?
Na tela Configurações > Integrações > API, clique em Nova integração e cadastre a integração AppMax. Após salvar, ative a integração, configure as permissões necessárias e utilize a opção Visualizar credenciais para consultar a Chave de API (Api Key) e a Chave de Segurança (Secret Key).
As credenciais são copiadas da Appmax para a Uappi?
Não. As credenciais da API são geradas na Uappi e inseridas na Appmax. A Chave de API (Api Key) deve ser informada no campo API Key, e a Chave de Segurança (Secret Key) no campo Secret Key. O token de afiliação segue o fluxo contrário: é gerado pela Appmax e inserido no campo Token de acesso do conector Appmax na Uappi.
Onde devo inserir as credenciais da Uappi na Appmax?
Durante a instalação do aplicativo Uappi na Appmax, acesse a etapa Credenciais Uappi e preencha:
● API Key: insira a Chave de API (Api Key) da Uappi;
● Secret Key: insira a Chave de Segurança (Secret Key) da Uappi. A credencial da API precisa estar ativa?
Sim. Na edição da integração AppMax na Uappi, mantenha a opção Ativo habilitada.
Além disso, verifique se a integração possui as permissões necessárias para acessar os recursos da API utilizados pela Appmax.
O que informar no campo “URL da loja Uappi”?
Informe a URL principal da loja acrescentando /api ao final.
Exemplo:
https://www.sualoja.com.br/api
Posso compartilhar as credenciais de API?
Não. A Chave de API (Api Key) e a Chave de Segurança (Secret Key) são credenciais confidenciais e devem ser acessadas somente por pessoas autorizadas. Ao utilizar prints em documentos ou atendimentos, oculte completamente esses valores.
O que verificar se ocorrer um erro de autenticação?
Confira se:
● A Chave de API (Api Key) da Uappi foi inserida corretamente no campo API Key da Appmax;
● A Chave de Segurança (Secret Key) foi inserida corretamente no campo Secret Key;
● Não existem espaços antes ou depois das credenciais;
● A integração está ativa na Uappi;
● As permissões necessárias da API estão configuradas;
● A URL da loja termina em /api;
● O ambiente configurado no conector Appmax (Homologação ou produção) corresponde ao ambiente utilizado no teste.
Caso a comunicação retorne erro 403, verifique principalmente as permissões de acesso aos recursos da API.
Leave a Reply