Integrações

O Scolah Compass se conecta a sistemas externos em quatro categorias: intercâmbio de dados (ETL), gateways de pagamento, canais de mensagens e orçamentos com o Scolah Compass Resources. As integrações são configuradas em Configurações → Integrações.

Intercâmbio de Dados (ETL)

As integrações de ETL importam ou exportam dados de beneficiários, casos e programas entre o Scolah Compass e sistemas externos, como registros governamentais, plataformas de MIS nacionais e data warehouses.

Tipos de conexão suportados

Tipo	Descrição
API REST	Conecta-se a qualquer API HTTP/REST. Suporta GET/POST com cabeçalhos personalizados, autenticação (chave de API, token Bearer, autenticação básica) e mapeamento de campos.
Arquivo CSV (SFTP)	Importa ou exporta arquivos CSV entregues de/para um servidor SFTP em um cronograma. Comum para intercâmbio de dados em massa com MIS governamentais.
Arquivo Excel	Importa dados de beneficiários ou domicílios de arquivos Excel (.xlsx) enviados manualmente ou via SFTP.

Além de uma conexão de API REST genérica, o Scolah Compass também oferece conectores pré-configurados para os padrões de saúde e proteção social já utilizados pelos registros do mundo real — veja Padrões e plataformas suportados abaixo.

Padrões e plataformas suportados

Padrão / Plataforma	Categoria	Notas
FHIR (HL7 FHIR R4)	Saúde · padrão	Funciona com qualquer servidor compatível com FHIR R4, como sistemas de prontuário hospitalar e APIs de saúde na nuvem, ou uma fachada FHIR na frente de um sistema legado HL7 v2.x.
DHIS2	Saúde · padrão	Instância DHIS2 auto-hospedada. Configure uma unidade organizacional e, opcionalmente, um programa. Instâncias anteriores à 2.38 podem exigir substituição do caminho da API.
DCI (Digital Convergence Initiative)	Proteção social · padrão	Consulta qualquer registro de proteção social compatível com DCI (padrões spdci.org) para registros de Person, Member e RelatedPerson. As solicitações são assinadas com HMAC-SHA256 conforme a especificação DCI.
OpenMRS	Saúde · EMR	API REST nativa do OpenMRS para instâncias auto-hospedadas. Use o conector FHIR se o servidor expuser uma fachada FHIR R4.
ODK Central	Coleta de dados	ODK Central auto-hospedado — selecione um projeto e um formulário para sincronizar as submissões.
KoboToolbox	Coleta de dados	Nuvem (kf.kobotoolbox.org) ou auto-hospedado — selecione um formulário para sincronizar as submissões.
CommCare	Plataforma de campo	Sincronização de submissões de formulários do CommCare HQ para um espaço de projeto.

Cada uma dessas opções vem pré-configurada no catálogo de Nova integração com suas próprias credenciais exigidas, exibidas automaticamente ao selecioná-la — você não precisa construir manualmente uma conexão de API REST para usar uma delas.

Casos de uso comuns de ETL

Importação do registro social nacional — trazer registros domiciliares de um registro social governamental para o Scolah Compass como beneficiários
Sincronização de registro do ACNUR — importar dados de refugiados e deslocados internos do UNHCR ProGres ou sistemas de registro semelhantes
Sincronização com MIS governamental — sincronização bidirecional com plataformas de MIS nacionais para dados de casos e resultados de programas
Exportação para data warehouse — enviar dados de casos, visitas e desembolsos do Scolah Compass para uma plataforma analítica para relatórios
Fusão de deduplicação — importar uma lista deduplicada de beneficiários a partir de um sistema de identidade nacional ou biométrico

Configurar uma integração de ETL

Clique em Integrações → Nova integração.
Selecione o tipo de conexão — um tipo genérico (API REST, CSV, Excel) ou um dos padrões/plataformas nomeados (FHIR, DHIS2, DCI, OpenMRS, ODK Central, KoboToolbox, CommCare) listados acima.
Preencha os detalhes de conexão:
- Para API REST: URL base, método de autenticação, cabeçalhos
- Para conexões baseadas em arquivo: host SFTP, porta, usuário, chave/senha, padrão de caminho do arquivo
Configure os mapeamentos de campos — associe colunas ou campos JSON da origem aos campos de beneficiário/caso do Scolah Compass.
Defina a direção de sincronização: Importação, Exportação ou Bidirecional.
Defina o agendamento: manual, a cada hora, diário, semanal ou expressão cron personalizada.
Clique em Salvar e testar.

Gateways de Pagamento

As integrações de pagamento conectam os desembolsos do Scolah Compass a trilhos de pagamento reais, permitindo transferências diretas para carteiras móveis, contas bancárias ou sistemas de vales dos beneficiários.

Métodos de pagamento suportados

Método	Exemplos
Mobile money	M-Pesa (Quênia, Tanzânia), MTN MoMo (Gana, Uganda, Ruanda), Airtel Money, Orange Money
Transferência bancária	Transferência direta banco a banco via sistemas de compensação interbancária locais
Vale	Resgate de vale digital ou em papel via uma integração com plataforma de vales
Em espécie	Bens não monetários rastreados pelo Scolah Compass (nenhum gateway externo necessário)
Dinheiro	Distribuição manual de dinheiro confirmada por comprovante de entrega do assistente social

Configurar um gateway de pagamento

Clique em Integrações → Nova integração → selecione a categoria Desembolso.
Selecione o provedor de pagamento.
Insira as credenciais de API fornecidas pelo provedor de pagamento (chave de API, segredo, ID do lojista, etc.).
Defina o ambiente operacional: Sandbox (para testes) ou Produção.
Vincule a integração a um método de pagamento nas Configurações de Desembolso.
Clique em Salvar e testar — o Scolah Compass envia uma pequena transação de teste para verificar a conexão.

Uma vez configurado, os administradores podem encaminhar lotes de desembolso pelo gateway e acompanhar o status das transações em tempo real.

Canais de Mensagens

As integrações de mensagens habilitam campanhas de divulgação, notificações automáticas e comunicação bidirecional com os beneficiários.

API do WhatsApp Business

Envie mensagens de campanha, lembretes de compromissos e notificações de desembolso aos beneficiários via WhatsApp.

Provedores suportados:

Twilio
Vonage (Nexmo)
360dialog
Meta Cloud API (direto)

Configuração:

Clique em Integrações → Canais de Chat → Novo canal → selecione WhatsApp.
Insira as credenciais do provedor (chave de API, ID do número de telefone, ID da conta do WhatsApp Business).
Configure a URL de webhook no painel do seu provedor para apontar para o Scolah Compass.
Configure as regras de palavras-chave para respostas automáticas a mensagens recebidas (por exemplo, responder STOP para cancelar a inscrição, STATUS para receber o status do caso).
Clique em Salvar e testar.

USSD

Para beneficiários sem smartphone, o USSD permite menus interativos via telefones básicos — sem necessidade de internet.

Provedores suportados:

Africa’s Talking
Infobip
Gateway USSD personalizado (via REST)

Configuração:

Clique em Integrações → Canais de Chat → Novo canal → selecione USSD.
Insira as credenciais do provedor e o código curto USSD.
Defina o fluxo de sessão — a estrutura de menu que os beneficiários percorrem.
Configure as regras de palavras-chave para ações automatizadas disparadas por entradas dos beneficiários.
Clique em Salvar e testar.

Orçamentos com o Scolah Compass Resources

O Scolah Compass Resources armazena os orçamentos e o estoque da agência. Ao conectá-lo, você associa cada programa à linha orçamentária correspondente e, a partir daí, cada pagamento de um programa associado é verificado em relação a essa linha no momento da aprovação (veja Verificação do orçamento na aprovação). Sem a integração, o Scolah Compass nunca chama o Resources e nada de novo aparece.

Conectar o Resources

Clique em Integrações → Nova integração → escolha Scolah Compass Resources (categoria FINANCE).
Escolha como conectar:
- Usar a conexão da instalação quando seu Scolah Compass estiver conectado ao Resources na Scolah Compass Platform. Não é preciso informar endereço nem chave.
- Informar um endereço e uma chave nos demais casos: o Endereço do Scolah Compass Resources, uma Chave de API criada no Resources e a Organização (tenant), se o serviço Resources hospedar mais de uma organização.
Clique em Verificar conexão. O Scolah Compass confirma que a chave funciona e que o Resources usa uma versão de API suportada (1.x); uma versão mais nova ou mais antiga é recusada, com a indicação da versão necessária.
Em 2. Espaço de trabalho, escolha Usar um espaço de trabalho existente (só aparecem os que nenhuma outra agência usa) ou Criar um espaço de trabalho com nome, moeda e fuso horário.
Clique em Ativar integração. Se sua agência exigir aprovação para novas integrações, ela é criada depois de aprovada.

Uma agência só pode ter uma integração com o Scolah Compass Resources. O limite de espaços de trabalho do Resources se aplica: se todos estiverem em uso, a criação de outro é recusada.

Associar programas a linhas orçamentárias

Abra a integração e clique em Correspondências orçamentárias.
Para cada programa, escolha a linha orçamentária de onde saem os pagamentos dele. Só aparecem orçamentos ativos. Abaixo de cada escolha você vê a regra da linha: Acima do orçamento: bloqueado ou Acima do orçamento: aviso, e se é necessária liberação financeira.
Clique em Salvar correspondências.

Verificar conexão, na mesma página, consulta o Resources e mostra a versão da API, o modo de compromisso e a moeda do espaço de trabalho. Veja também as integrações do Scolah Compass Resources.

Manter o orçamento em dia

Depois que você associa os programas, o Scolah Compass mantém o orçamento atualizado sozinho, a cada poucos segundos:

Um pagamento efetuado, inclusive um que um gateway de pagamento confirma mais tarde, passa a contar como despesa na linha.
Um vale fica comprometido até ser usado e então passa a despesa; um vale expirado devolve o valor dele.
Um pagamento cancelado, rejeitado ou deixado de fora quando um lote é fechado devolve o que não foi pago.
Um pagamento aprovado enquanto o Resources estava inacessível é registrado quando ele volta, marcado como aprovado offline.

Os lançamentos ficam na linha em que foram registrados: alterar depois a correspondência de um programa só afeta novas aprovações. A despesa é definitiva; se o status de um pagamento efetuado mudar depois, ele é contado em Status finais alterados para que o financeiro corrija no Resources. Uma verificação noturna também devolve qualquer compromisso que o Scolah Compass não sustenta mais, por exemplo o deixado por uma aprovação interrompida.

O painel Sincronização com o Scolah Compass Resources mostra a última sincronização, os itens Aguardando nova tentativa, Com falha, Aprovados offline e Status finais alterados, e o último erro. Sincronizar agora executa uma sincronização na hora.

Aprovações anteriores. Só são registradas as aprovações feitas depois que a integração é ativada. Para incluir as anteriores, escolha uma data em Registrar aprovações anteriores, clique em Pré-visualizar para ver quantas aprovações e qual montante seriam registrados e, em seguida, em Registrar a partir desta data.

Estoque com o Scolah Compass Resources

Com o módulo Estoque ativo, a página da integração também mostra Armazéns para pagamentos em espécie e Itens em espécie no Estoque:

Para cada programa, escolha o Armazém principal. Para direcionar alguns beneficiários a outro lugar, escolha Enviar alguns beneficiários para outro lugar por (distrito, comunidade, gênero ou um dos seus campos personalizados de beneficiário) e depois Adicionar exceção com o valor e o armazém correspondente.
Em Itens em espécie no Estoque, escolha o item do Resources que corresponde a cada item em espécie.
Clique em Salvar correspondências de estoque.

Pagamentos aprovados antes de o programa ter um armazém não têm mercadorias reservadas. A página da integração mostra quantos são; clique em Reservar agora para reservar as mercadorias no Scolah Compass Resources. Um lote sem estoque suficiente aparece com o motivo e fica sem reserva, então nada é reservado pela metade.

Só os itens em espécie vinculados a um item do Resources, em programas com armazém, são reservados e entregues (veja Verificação do estoque na aprovação); todo o resto é aprovado como antes.

O Scolah Compass mantém o estoque em dia sozinho: dá baixa nos bens quando uma entrega é confirmada e devolve as reservas quando pagamentos são cancelados, expiram ou ficam de fora ao fechar um lote. Uma verificação noturna encerra qualquer reserva que o Scolah Compass não sustenta mais. A cada hora, ele também envia ao Resources sua lista de itens em espécie, que o Resources usa em Importar do Scolah Compass.

Desconectar

Em Desconectar, escolha o que acontece com o dinheiro ainda comprometido no orçamento e clique em Desconectar:

Liberar os compromissos em aberto no Scolah Compass Resources: o orçamento recupera esse dinheiro na hora.
Deixá-los para o financeiro encerrar no Scolah Compass Resources.

A sincronização para e a integração é desativada. Se você ativá-la de novo, a sincronização é retomada de onde parou e nada é registrado duas vezes.

Monitorar todas as integrações

Log de execuções de integração

Clique em Integrações → Execuções de Integração para ver um log de todos os jobs de sincronização e chamadas de API:

Coluna	Descrição
Integração	Qual integração foi executada
Iniciado	Data/hora
Duração	Quanto tempo levou
Registros	Quantos registros foram processados
Status	Sucesso, Parcial ou Falha

Clique em qualquer linha para ver o log de execução completo, incluindo erros e avisos.

Eventos de sincronização

Clique em Integrações → Eventos de Sincronização para um fluxo de eventos de baixo nível das mudanças de dados que passam pelas integrações — útil para depurar problemas de mapeamento de campos ou rastrear um registro específico.