BlogPainelAjudaAPI Status
Documentação
Referência da APIDocumentaçãoMundi SDKcustompage

Instalação do App

Entenda o fluxo de instalação de um app interno e externo.

Suggest Edits

Conforme dito anteriormente, um app pode ser instalado de duas formas, visto que pode se tratar de um App Interno ou um App Externo.

No momento da autorização, caso o app possua uma URL de Teste/Validação cadastrada, durante a uma instalação, nós enviaremos uma requisição para esta URL para que seu app faça a validação dos Dados Adicionais antes da instalação ser finalizada.

Veja como funciona a Validação e Teste da Instalação, quais dados o app recebe após uma instalação e como funciona para cada tipo de app.

Validação e Teste da Instalação

No momento da instalação do app, caso exista uma URL de Validação/Teste cadastrada no app na sessão Callbacks, o app receberá uma requisição com os Dados Adicionais preenchidos pelo usuário.

Exemplo

Considerando https://meu-app.com/endpoint-para-teste como a URL como a URL cadastrada para Testes e Validação, veja abaixo o exemplo da requisição de teste.

Lembrando que o corpo da requisição é baseado no resultado do formulário gerado pelo JsonSchema definido em Dados Adicionais que estará dentro do objeto additionalData.

Por segurança, o Hub envia o Header X-Hub-Signature, que é a forma de validarmos quem está enviando a requisição, saiba mais em Validando as Requisições de Callback do Hub.

Headers
X-Hub-Signature : dc229bd348e9a9280302e6dff23cb0cfb1271124264958c342c1a95c1d0f485d
Accept-Language : pt-BR

POST https://meu-app.com/endpoint-para-teste
{
  "accountId":"acc_XXXXXXXXXX",
  "publicAppKey":"XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
  "additionalData":{
    "customStringField": "custom value",
    "customIntegerField": 10,
    "customBoolField": true
  },
  "optionalEvents":["CustomerCreated","CustomerUpdated","ChargePaid","ChargePaymentFailed"],
  "optionalActions":[]}
}

Reconhecendo Sucesso ou Falha no Teste/Validação

Será considerado sucesso se a resposta possuir o Status Code igual à 200 OK, 201 Created, 202 Accepted ou 204 No Content.

Caso algum dado esteja inválido e seu app retorne qualquer Status Code diferente dos citados acima, como 400 Bad Request por exemplo, você pode retornar uma mensagem de erro personalizada usando a seguinte estrutura como base:

{
  "errors": [
    {
        "message" : "Nome não pode conter números",
        "property": "Name"
    },
    {
        "message" : "Email inválido",
        "property": "Email"
    }]
}

Vemos uma lista de errors com os campos message e property para definições individuais. O campo message representa a mensagem que será exibida para o usuário, o campo property representa o nome da propriedade que recebeu o dado inválido.

O Hub buscará esta propriedade no seu JsonSchema para destacá-la para o usuário, caso seu retorno não seja reconhecido, será exibida uma mensagem de erro padrão "Dados complementares inválidos".

Somente após esta validação a instalação do app prosseguirá.

É possível saber em qual idioma o usuário está interagindo com a API através do header Accept-Language para também dar a resposta no idioma solicitado. O header Accept-Language poderá vir com os valores pt-BR, en-US ou es-ES.

App Interno Webhook de Instalação

Um App Interno, quando instalado, notifica o app através da URL de Callback de Instalações e Desinstalações (Veja mais em Callbacks).

Considerando https://meu-app.com/hub-callback como a URL cadastrada para Callback de Instalação e Desinstalação, veja abaixo o exemplo do webhook que será enviado. 

Headers
X-Hub-Signature : dc229bd348e9a9280302e6dff23cb0cfb1271124264958c342c1a95c1d0f485d

POST https://meu-app.com/hub-callback
{
  "command":"Install",
  "accessToken":"879d023588baba7a82da58909a1b662e4e55aa6345c68f0906abe5f600b680ab",
  "accountId":"acc_XXXXXXXXXXXXXXXX",
  "merchantId":"merch_XXXXXXXXXXXXXXXX",
  "installId":"XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
  "accountPublicKey":"pk_test_XXXXXXXXXXXXXX",
  "type":"Sandbox",
  "additionalData": {
      "customStringField": "custom value",
      "customIntegerField": 10,
      "customBoolField": true,
    },
    "events": [
      "OrderPaid",
      "OrderPaymentFailed",
      "OrderCanceled"
    ],
    "actions": [
      "OrderCreate",
      "OrderGet",
      "OrderList"
    ]
}

Descrição das Propriedades

  • command - Informa se está ocorrendo uma instalação, edição ou desinstalação do app; Possiveis valores: Install, Update e Uninstall;

  • accessToken - Esse token é o identificador único da instalação, deve ser utilizado para fazer as Ações. Veja mais em Utilizando a API como App (Ações);

  • accountId - Identificador único e público da Loja na MundiPagg. Deve ser utilizado para tratar os eventos recebidos da MundiPagg. Veja mais em Interpretando Webhooks (Eventos);

  • merchantId - Identificador único e público de um cliente da MundiPagg. Esse ID pode ser o mesmo para vários accountId. Pode ser utilizado para referenciar Lojas de um mesmo titular ou gerar links para o dashboard da MundiPagg. Veja mais em Criando Links Direto para o Dashboard da MundiPagg;

  • installId - Identificador único e público da instalação. Usado em operações simples como buscar instalação para não expor o accessToken da instalação. Você vai usa-lo apenas se seu app for um App Externo;

  • accountPublicKey - Identificador único e público da Loja na Mundipagg. Serve para seu app fazer a tokenização de cartão de crédito se for necessário. Saiba mais na documentação da API Mundipagg nas sessões Tokenização e Criar Token Cartão;

  • type - Informa se a instalação foi feita no modo Desenvolvimento, ou, se estiver em produção, por uma loja de teste ou não; Possíveis valores: Development, Sandbox e Production;

  • additionalData - Este campo é dinâmico. É o resultado do preenchimento do formulário gerado com o JsonSchema do seu app. Veja mais em Dados Adicionais;

  • events - Informa todos os eventos que foram permitidos para que a sua aplicação receba. Essa coleção é composta por todas as permissões de eventos obrigatórias que o seu app requer, junto com as permissões de eventos opcionais que o usuário que instalou o app permitiu. Veja mais em Permissões e em Lista de Eventos;

  • actions - Informa todas as ações que foram permitidas para a sua aplicação executar na MundiPagg. Essa coleção é composta por todas as permissões de ações obrigatórias que o seu app requer, junto com as permissões de ações opcionais que o usuário que instalou o app permitiu. Veja mais em Permissões.

Retentativa

Caso ocorra Timeout ou o Status Code recebido no envio do callback seja diferente de 200 OK, 201 Created, 202 Accepted ou 204 No Content, o Callback é retentado por mais 4 vezes (total 5 tentativas), com um intervalo de 30 segundos entre cada tentativa.

Caso falhe todas as vezes, a instalação do usuário não terá efeito e será marcada como uma instalação inválida.

Como saber que o Hub é realmente o remetente da requisição?

App Externo Authorization Code

Para iniciar o fluxo de instalação externa, você precisa adicionar o Botão da Mundipagg. Endenda os detalhes na sessão Botão de Instalação de App Externo.

Quando um usuário clicar no botão, ele será redirecionado para o Hub para autorizar o app.

Após finalizar a instalação no Hub, o usuário será redirecionar para a URL escolhida no botão junto com um código de autorização via query string code.

Exemplo: https://meu-app.com/redirect?code=879d023588baba7a82da58909a1b662e4e55aa6345c68f0906abe5f600b680ab

Para finalizar a instalação, é necessário utilizar também a PublicAppKey do App. Veja suas chaves em Chaves de Acesso.

O código de autorização deve ser utilizado em até 180 segundos após a sua criação.

Para utilizá-lo basta enviar uma requisição para a API do Hub com o código de autorização e a PublicAppKey do app no Header.

No exemplo abaixo a chave pública do app (PublicAppKey) é e172302a-a9b8-4a34-a36d-e1d6ec10f59d:

Requisição

Headers
"PublicAppKey" : "e172302a-a9b8-4a34-a36d-e1d6ec10f59d"

POST https://hubapi.mundipagg.com/auth/apps/access-tokens
{
    "code": "879d023588baba7a82da58909a1b662e4e55aa6345c68f0906abe5f600b680ab"
}

📘

Observação importante

Se você precisar, pode sobrescrever as URLs de callback de Instalação e Desinstalação" e/ou a de Eventos* para cada instalação. Essa funcionalidade só é permitida se o seu aplicativo permite apenas uma instalação por loja. Na modalidade que permite múltiplas instalações do mesmo aplicativo na mesma loja, essa funcionalidade não está disponível.

Headers
PublicAppKey : e172302a-a9b8-4a34-a36d-e1d6ec10f59d

POST https://hubapi.mundipagg.com/auth/apps/access-tokens
{
    "code": "879d023588baba7a82da58909a1b662e4e55aa6345c68f0906abe5f600b680ab",
    "webhookUrl" : "https://sub-dominio-customizado.meuapp.com/api-callback",
    "hubCallbackUrl" : "https://sub-dominio-customizado.meuapp.com/hub-callback"
}

Resposta

{
  "command":"Install",
  "accessToken":"879d023588baba7a82da58909a1b662e4e55aa6345c68f0906abe5f600b680ab",
  "accountId":"acc_XXXXXXXXXXXXXXXX",
  "merchantId":"merch_XXXXXXXXXXXXXXXX",
  "installId":"XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
  "accountPublicKey":"pk_test_XXXXXXXXXXXXXX",
  "type":"Sandbox",
  "additionalData": {
      "customStringField": "custom value",
      "customIntegerField": 10,
      "customBoolField": true,
  },
  "events": [
    "OrderPaid",
    "OrderPaymentFailed",
    "OrderCanceled"
  ],
  "actions": [
    "OrderCreate",
    "OrderGet",
    "OrderList"
  ]
}

Se o header PublicAppKey ou o código de autorização forem inválidos, a resposta será 401 Unauthorized.

Descrição das Propriedades

  • command - Informa se está ocorrendo uma instalação, edição ou desinstalação do app; Possiveis valores: Install, Update e Uninstall;

  • accessToken - Esse token é o identificador único da instalação, deve ser utilizado para fazer as Ações. Veja mais em Utilizando a API como App (Ações);

  • accountId - Identificador único e público da Loja na MundiPagg. Deve ser utilizado para tratar os eventos recebidos da MundiPagg. Veja mais em Interpretando Webhooks (Eventos);

  • merchantId - Identificador único e público de um cliente da MundiPagg. Esse ID pode ser o mesmo para vários accountId. Pode ser utilizado para referenciar Lojas de um mesmo titular ou gerar links para o dashboard da MundiPagg. Veja mais em Criando Links Direto para o Dashboard da MundiPagg;

  • installId - Identificador único e público da instalação. Usado em operações simples como buscar instalação para não expor o accessToken da instalação. Você vai usa-lo apenas se seu app for um App Externo;

  • accountPublicKey - Identificador único e público da Loja na Mundipagg. Serve para seu app fazer tokenização de cartão de crédito se for necessário. Saiba mais na documentação da API da Mundipagg nas sessões Tokenização e Criar Token Cartão;

  • type - Informa se a instalação foi feita no modo Desenvolvimento, ou, se estiver em produção, por uma loja de teste ou não; Possíveis valores: Development, Sandbox e Production;

  • additionalData - Este campo é dinâmico. É o resultado do preenchimento do formulário gerado com o JsonSchema do seu app. Veja mais em Dados Adicionais;

  • events - Informa todos os eventos que foram permitidos para que a sua aplicação receba. Essa coleção é composta por todas as permissões de eventos obrigatórias que o seu app requer, junto com as permissões de eventos opcionais que o usuário que instalou o app permitiu. Veja mais em Permissões e em Lista de Eventos;

  • actions - Informa todas as ações que foram permitidas para a sua aplicação executar na MundiPagg. Essa coleção é composta por todas as permissões de ações obrigatórias que o seu app requer, junto com as permissões de ações opcionais que o usuário que instalou o app permitiu. Veja mais em Permissões.

Como saber que o Hub é realmente o remetente da requisição?

Updated almost 6 years ago