Construa integrações

Alguns dos apps mais valiosos conectam um app SOIS existente a um serviço externo. Um exemplo comum: sincronizar faturas do app de contabilidade da SOIS com o QuickBooks. Este guia explica como um app de integração lê os dados da SOIS com segurança e se conecta a um serviço externo.

Os apps de integração são uma categoria de primeira classe. Eles leem os dados de outro app por um contrato governado, nunca o banco de dados dele diretamente, e somente com o consentimento do tenant.

Dois lados de uma integração

Um app de integração fala com duas coisas:

  1. Um app SOIS (por exemplo contabilidade, armazém ou contatos). Você lê ou escreve os dados dele pelo contrato publicado.
  2. Um serviço externo (por exemplo QuickBooks). Você o chama com as próprias credenciais do tenant.

Declare com o que você se integra

Seu projeto declara os apps SOIS dos quais depende. Essa declaração faz duas coisas: informa à SOIS quais contratos seu app pode usar, e permite que o tenant veja e aprove o acesso quando instala seu app.

Leia os dados da SOIS pelo contrato

Seu app não toca nas tabelas de outro app. Ele lê pelo contrato daquele app, um conjunto estável de operações e formatos de dados. Seu agente constrói seu mapeamento contra esses formatos. Durante o desenvolvimento, você trabalha com dados de exemplo representativos, então pode construir e visualizar todo o fluxo sem uma conexão ao vivo.

Em tempo de execução, o acesso é governado:

  • O tenant aprova o acesso entre apps quando instala seu app. Faz parte dos scopes que seu app solicita.
  • O contrato impõe o que seu app pode ler ou escrever. O isolamento do tenant nunca é enfraquecido.

Conecte o serviço externo

As credenciais externas pertencem ao tenant, não a você. Seu app declara as credenciais de que precisa (por exemplo uma conexão OAuth), e cada tenant que instala fornece as suas. Você nunca retém as credenciais de outro tenant.

Exemplo: sincronizar faturas com o QuickBooks

  1. Declare que seu app se integra com o app de contabilidade.
  2. Peça ao seu agente que leia o formato da fatura de contabilidade e construa um mapeamento de uma fatura SOIS para uma fatura QuickBooks. Construa e visualize contra faturas de exemplo.
  3. Declare as credenciais OAuth do QuickBooks de que seu app precisa.
  4. Quando um tenant instala seu app, ele aprova o acesso à contabilidade e conecta a própria conta do QuickBooks.
  5. Em tempo de execução, seu app lê as faturas pelo contrato de contabilidade e as envia ao QuickBooks com as credenciais do tenant, normalmente por agendamento ou gatilho.

Boas práticas

  • Mapeie os campos de forma explícita e trate os casos em que um serviço externo espera dados que sua fonte não tem.
  • Falhe com suavidade. Se o serviço externo estiver indisponível, tente novamente em vez de perder dados.
  • Solicite apenas os scopes de que você precisa. Os tenants aprovam um acesso restrito mais rápido e confiam mais nele.

Próximos passos