Integrações
O Compass se conecta a sistemas externos em três categorias: intercâmbio de dados (ETL), gateways de pagamento e canais de mensagens. As integrações são configuradas em Configurações → Integrações.
Intercâmbio de Dados (ETL)
Seção intitulada “Intercâmbio de Dados (ETL)”As integrações de ETL importam ou exportam dados de beneficiários, casos e programas entre o Compass e sistemas externos, como registros governamentais, plataformas de MIS nacionais e data warehouses.
Tipos de conexão suportados
Seção intitulada “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 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
Seção intitulada “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 — Epic, Cerner, Azure Health Data Services, GCP Cloud Healthcare API — 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
Seção intitulada “Casos de uso comuns de ETL”- Importação do registro social nacional — trazer registros domiciliares de um registro social governamental para o 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 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
Seção intitulada “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 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
Seção intitulada “Gateways de Pagamento”As integrações de pagamento conectam os desembolsos do 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
Seção intitulada “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 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
Seção intitulada “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 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
Seção intitulada “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
Seção intitulada “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 Compass.
- Configure as regras de palavras-chave para respostas automáticas a mensagens recebidas (por exemplo, responder
STOPpara cancelar a inscrição,STATUSpara receber o status do caso). - Clique em Salvar e testar.
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.
Monitorar todas as integrações
Seção intitulada “Monitorar todas as integrações”Log de execuções de integração
Seção intitulada “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
Seção intitulada “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.