Neste artigo, você vai aprender como funciona a conexão automática de integradores no Monde: quem pode solicitá-la, como é o fluxo até a aprovação, o que o integrador informa na integração, o que a agência autoriza, inclusive quais registros o integrador alcança na conta dela, e como ela desativa e reativa a conexão.
Para o cadastro de parceiro, são necessários o CNPJ da empresa e um e-mail com o domínio dela. Para autorizar a conexão, é preciso um usuário administrador da agência.
Contexto ou termos-chave
Conexão automática: a ligação entre o sistema de um integrador e o Monde de uma agência, criada quando a agência autoriza esse integrador a acessar a conta dela.
Integrador (parceiro): a empresa aprovada pelo Monde para acessar o Monde das agências pela API, identificada pelo CNPJ informado no cadastro. No cadastro e na área dela, ela é chamada de parceiro; para a agência, é o integrador.
Registros de outras origens: as vendas, as contas a pagar e receber e as tarefas lançadas pelos usuários da agência e por outras integrações, e não pelo próprio integrador.
OAuth 2.0: o padrão que a conexão automática segue. É o mesmo de quando um site pede permissão para acessar a sua conta do Google: a agência autoriza o sistema do integrador sem passar a senha.
URL de retorno: o endereço da página do sistema do integrador para onde o Monde leva a agência depois que ela autoriza a conexão.
Quem pode solicitar a conexão automática
O pedido parte da empresa que quer integrar o próprio sistema ao Monde, e não da agência. A agência entra depois, autorizando um integrador que o Monde já aprovou.
Podem solicitar:
Empresas que trabalham com agências de viagens, como operadoras, consolidadoras, redes hoteleiras, locadoras, seguradoras e receptivos;
Empresas de tecnologia que desenvolvem CRM, BI, aplicativos e sites para o turismo.
A agência que quer ligar o próprio site, o próprio BI ou outra ferramenta dela ao Monde não passa por aqui: esse caso é a API usada diretamente pela agência, explicada em Como utilizar a API do Monde.
Como é o fluxo para se tornar parceiro
O cadastro é público, e o acesso à API só começa depois que o Monde aprova.
Acesse https://web.monde.com.br/partners/signup e preencha Empresa, CNPJ, Responsável, E-mail corporativo e Telefone / WhatsApp
Marque a declaração de que você pode representar a empresa e o aceite dos Termos de Uso da API Monde para Parceiros
Clique em Solicitar integração
Abra o e-mail que o Monde envia, clique em Confirmar e-mail e crie a senha da área do parceiro
Aguarde o contato da equipe do Monde para a reunião de alinhamento
Aprovado o cadastro, abra pelo e-mail a página de credenciais, clique em Ver minhas credenciais e guarde o Client ID e o Segredo, usando o botão de copiar ao lado de cada um
Entre em https://web.monde.com.br/partners/integration e informe a Política de privacidade e a URL de retorno
Dois detalhes do cadastro:
O e-mail precisa ter o domínio da empresa. Gmail, Hotmail, Outlook e afins não são aceitos;
O link de confirmação do e-mail vale dois dias.
O que o Monde avalia antes de aprovar
Seguir o fluxo não garante a aprovação. O Monde confere os dados da empresa, conversa com o seu time na reunião de alinhamento e decide a seu critério: ele pode aprovar, recusar ou pedir mais informações, sem obrigação de justificar a decisão.
Depois da aprovação, o CNPJ do cadastro não muda mais: para integrar com outro CNPJ, é preciso um cadastro novo, e as agências autorizam esse cadastro de novo.
As permissões do integrador
É na aprovação que o Monde define as permissões do integrador, ou seja, o que ele vai poder fazer no Monde das agências. O integrador não escolhe essa lista, e as permissões têm os mesmos nomes das Permissões de Acesso do Monde.
Cada permissão alcança só o que o próprio integrador criar:
Vendas: com Editar, o integrador cria e edita as próprias vendas na conta da agência, e com Adicionar anexos pode anexar arquivos a elas;
Contas a Pagar e Receber: ele lança, altera e exclui só as próprias contas, inclusive as já liquidadas quando recebe também Editar lançamento liquidado;
Anexos: o integrador anexa arquivos e baixa os anexos só das vendas e das contas que ele mesmo lançou.
O acesso ao que a agência lançou é exceção: o Monde só concede as permissões que alcançam registros lançados pela agência e por outras integrações, como Acessar lançamentos de todos os usuários e do sistema, quando a integração precisa delas, como um integrador de conciliação que lê os lançamentos feitos à mão. Também são exceção as permissões sobre o que vale para a agência inteira:
criar, editar e excluir categorias de tarefa, marcadores e funções;
criar, editar e excluir produtos, com os fornecedores e os representantes deles;
criar, editar e excluir categorias financeiras, centros de custo e formas de pagamento;
criar, editar e excluir contas e cartões e fechar e reabrir o caixa delas, que vale para a conta inteira;
lançar, alterar e excluir transferências entre contas, que não guardam quem as lançou, e consultar o saldo e o extrato das contas, as transferências e o histórico delas, que mostram o que a agência lançou;
a Conciliação Bancária, que alcança o extrato e as movimentações da conta corrente inteira;
criar, editar, excluir, emitir e copiar para reemissão as notas fiscais, e Gerar Notas Fiscais, porque a nota é documento fiscal da agência;
consultar os recibos do Extrato CVC, porque no Monde a consulta do extrato também lança recibos;
consultar o Master - Extrato CVC, porque ele é o repasse da agência master franqueado.
A agência vê essas permissões marcadas com o selo Acesso ampliado antes de autorizar.
O Monde pode mudar as permissões do integrador depois da aprovação. O que muda nas conexões que as agências já têm está em Quando as permissões do integrador mudam.
Como acompanhar a situação do cadastro
A situação do cadastro aparece na área do parceiro, em https://web.monde.com.br/partners/integration, acessada com o e-mail e a senha criados na confirmação.
As situações possíveis são:
Aguardando e-mail: falta confirmar o e-mail pelo link que o Monde enviou;
Em análise: o Monde confere os dados e entra em contato para agendar a reunião de alinhamento;
Aprovado, configuração pendente: falta informar a Política de privacidade, a URL de retorno ou as duas;
Conexão em homologação: nenhuma agência conecta ainda. O parceiro faz os dois testes da homologação, e depois a equipe do Monde valida a integração e a libera para todas as agências;
Conexão habilitada: todas as agências já podem conectar o seu sistema ao Monde;
Suspenso: o acesso está suspenso;
Não aprovado: o cadastro não foi aprovado.
O que a conexão automática custa
A conexão automática não exige licença à parte, qualquer que seja a permissão que o Monde liberou para o integrador. Para o integrador, o uso da API é gratuito, e a agência não contrata nada além da licença do Monde que já tem.
O que vale para a empresa escolhida pela agência:
Empresa com licença ativa do Monde: pode receber o integrador, com todas as permissões que ele recebeu na aprovação;
Empresa com licença somente leitura: o integrador consulta os dados dela, mas não grava nada;
Empresa desativada ou sem licenças do Monde: o acesso do integrador a ela para;
Conteúdos: fazem parte da licença Monde Pro. O integrador que recebe uma empresa com essa licença alcança todos os conteúdos da agência, porque eles não são de uma empresa só.
Quando a agência tem mais de uma empresa cadastrada, essas regras valem por empresa, como explicado em Como funcionam multiempresas no Monde.
O que o parceiro precisa fazer na integração
Com o cadastro aprovado, a integração é construída no sistema do parceiro, por um desenvolvedor. O caminho é o botão Conectar com o Monde: toda integração precisa dele, e é por ele que a agência autoriza a conexão.
Na área do parceiro, em https://web.monde.com.br/partners/integration, informe a Política de privacidade, que a agência lê antes de autorizar, e a URL de retorno, o endereço do seu sistema que recebe a agência depois da autorização. As duas precisam começar com https://
Guarde o Client ID e o Segredo da página de credenciais no servidor do seu sistema, nunca no navegador do usuário
Coloque no seu sistema o botão Conectar com o Monde, apontando para o endereço de autorização que o seu sistema monta a cada acesso. O código do botão está na página de credenciais, com um botão de copiar
Siga a documentação da API para montar o endereço de autorização, trocar o código pelo token e usar a API
Combine os testes com o Monde e avise quando a integração estiver pronta para ser liberada
Enquanto faltar a Política de privacidade ou a URL de retorno, nenhuma agência consegue autorizar o seu sistema.
A homologação
Com as duas URLs informadas, a integração entra em Conexão em homologação: o botão Conectar com o Monde ainda não conecta com nenhuma agência. A agência que tentar vê a mensagem A conexão automática deste integrador ainda está em homologação com o Monde.
Antes da liberação, o sistema do parceiro faz os dois testes da homologação, com o Client ID e o Segredo:
Conferência das credenciais: uma chamada ao endereço de homologação do Monde, que confirma que o Client ID e o Segredo funcionam
Chamada de teste: uma chamada com um corpo fixo, que mostra a resposta de sucesso e a de erro da API. Ela não grava nenhum dado
Os endereços e os exemplos estão na seção da conexão automática da documentação da API. Em https://web.monde.com.br/partners/integration, a área Testes da homologação mostra cada teste com a data em que passou, ou como pendente.
Com os dois testes feitos, escreva para parcerias@monde.com.br. Depois que a equipe do Monde valida a integração, ela é liberada para todas as agências, e a situação passa para Conexão habilitada. Antes dos dois testes, o Monde não consegue liberar a integração.
A URL de conexão
A URL de conexão é opcional. Ela é o endereço da área logada do seu sistema em que a agência clica em Conectar com o Monde.
Na área do parceiro, em https://web.monde.com.br/partners/integration, clique em Editar
Informe o endereço no campo URL de conexão. Ele precisa começar com https://
Clique em Salvar
Com a integração liberada e a URL de conexão informada, o seu sistema aparece para as agências na tela de Integrações do Monde Web. O botão Conectar abre esse endereço numa aba nova, e a agência conclui a conexão pelo seu sistema.
O que é a URL de retorno
A URL de retorno é o endereço de uma página do seu sistema. É para essa página que o Monde leva a agência depois que ela clica em Autorizar.
O caminho da agência é este:
No seu sistema, a agência clica em Conectar com o Monde
O Monde abre, a agência entra com o usuário dela e autoriza a conexão
O Monde leva a agência de volta para o seu sistema, no endereço que você informou como URL de retorno
Sem esse endereço, o Monde não sabe para onde devolver a agência, e a conexão não é concluída.
Como descobrir a URL de retorno:
Peça ao desenvolvedor do seu sistema o endereço da página que recebe a agência depois da autorização. O nome técnico do endereço é
redirect_uriConfira se o endereço começa com https://, como em https://www.suaempresa.com.br/monde/retorno
Na área do parceiro, em https://web.monde.com.br/partners/integration, clique em Editar e informe o endereço no campo URL de retorno
O endereço precisa ser exatamente o mesmo que o seu sistema usa no botão Conectar com o Monde. Até uma barra a mais no fim faz a autorização falhar.
Limitações conhecidas
O Segredo aparece uma única vez, na página de credenciais. Guarde-o nesse momento, pelo botão de copiar ao lado dele. Para vê-lo de novo, não há como reabrir a mesma página: é preciso pedir ao Monde que gere um segredo novo, pelo e-mail parcerias@monde.com.br, que a própria página de credenciais mostra;
A URL de retorno é uma só por parceiro. Para atender endereços diferentes, trate essa diferença dentro do seu próprio sistema;
Depois de informadas, as duas URLs podem ser trocadas, mas não podem ficar em branco;
A conexão automática não faz login único (SSO). O usuário da agência não passa a entrar no sistema do parceiro com o login do Monde. Quem recebe o acesso é o sistema do parceiro, para fazer o que a agência autorizou.
A documentação da API
A documentação da API do Monde é pública, em https://web.monde.com.br/api/v3/documentation, e não exige login. Ela está em português e em inglês, e tem uma seção própria sobre a conexão automática, com o passo a passo técnico e os modelos do botão Conectar com o Monde.
Na abertura da página há o link para baixar o arquivo da especificação, no padrão OpenAPI, para abrir a documentação em outras ferramentas.
Para quem desenvolve com um assistente de IA, o Monde mantém um guia em texto em https://web.monde.com.br/llms.txt, que aponta para a documentação e para o passo a passo da conexão automática. Os links da documentação e desse guia também vêm nos e-mails de confirmação do cadastro e das credenciais.
Como a agência autoriza a conexão pelo sistema do integrador
A agência autoriza a conexão a partir do sistema do integrador, e quem faz isso precisa ser um usuário administrador.
No sistema do integrador, clique em Conectar com o Monde
Entre na conta da agência no Monde com um usuário administrador
Confira o nome e o CNPJ do integrador e, se quiser, abra a Política de privacidade do integrador
Em Empresa, escolha qual empresa da agência o integrador vai acessar. Com uma empresa só, o nome dela já aparece
Confira a lista Este integrador poderá: o resumo no topo diz quantas permissões o integrador vai receber, e cada grupo, como Vendas, mostra as permissões dele ao clicar no nome
Confira, acima dos botões, com qual usuário você está autorizando
Clique em Autorizar
Com mais de uma empresa ativa, o campo Empresa lista todas. A autorização vale só para a selecionada. Para liberar o integrador em mais de uma empresa, repita o processo uma vez para cada uma.
Se o usuário mostrado não for o seu, saia do Monde e clique de novo em Conectar com o Monde no sistema do integrador.
Começar a conexão pelo Monde Web
A agência também chega ao sistema do integrador pelo Monde Web, quando o integrador informou a URL de conexão.
No Monde Web, acesse Cadastros > Integrações
Clique em Adicionar e escolha Integração com Fornecedor
Encontre o integrador na lista, se quiser pelo campo Buscar fornecedor. Ele tem o selo Conexão automática
Clique em Conectar. O sistema do integrador abre numa aba nova
Entre no sistema do integrador, clique em Conectar com o Monde e siga os passos acima
Só aparecem na lista os integradores já liberados pelo Monde e que informaram a URL de conexão.
O selo Acesso ampliado
Quando o Monde concedeu ao integrador acesso a registros de outras origens, a tela de autorização, que abre ao clicar em Conectar com o Monde no sistema do integrador, mostra o selo Acesso ampliado na lista Este integrador poderá:
No resumo da lista: quantas permissões têm o selo, como 74 com Acesso ampliado;
Em cada grupo: abaixo do nome do grupo, quantas permissões dele têm o selo;
Na permissão: ao abrir o grupo, o selo aparece ao lado do nome da permissão.
Logo abaixo da lista, antes do botão Autorizar, a legenda explica o selo: Acesso ampliado: inclui registros lançados pela agência e por outras integrações.
Sem o selo, o integrador alcança só o que ele mesmo criar.
Onde a agência vê, desativa e reativa a conexão
No Monde Web, acesse Cadastros > Integrações: a conexão aparece na lista com o tipo Conexão automática, o nome da empresa e a situação Ativa.
Nessa lista, o administrador da agência pode:
Abrir a conexão e ver o integrador, a empresa e as permissões concedidas, com os nomes do Monde. Quando o integrador tem acesso a registros de outras origens, essas permissões aparecem com o selo Acesso ampliado, e a legenda do selo fica no fim da lista de permissões;
Renomear a conexão, no campo Nome da integração, o que ajuda quando o mesmo integrador tem mais de uma integração na mesma empresa;
Desativar a conexão, no botão Desativar da tela de edição.
Ao desativar, o integrador perde o acesso na hora e a conexão fica na lista com a situação Inativo. O que ele já cadastrou não é afetado. Para ver a conexão desativada na lista, altere o filtro Ativa para Não.
Como o integrador religa a conexão pelo sistema dele
O integrador que se desconectou, ou que a agência desativou, volta pelo botão Conectar com o Monde no sistema dele. Um administrador da agência aprova a autorização, como na primeira vez.
Com uma única conexão desativada desse integrador na empresa escolhida: a autorização reativa essa conexão, e o integrador volta a acessar o que já tinha cadastrado por ela. A tela de autorização avisa antes qual conexão será reativada;
Com mais de uma conexão desativada, ou sem nenhuma: a autorização cria uma conexão nova, que não alcança o que o integrador cadastrou pelas anteriores.
Log da conexão
A renomeação, a desativação e a reativação ficam no log da conexão, com quem fez e, na renomeação, o nome antigo e o novo. Para consultá-lo, no Monde Web, acesse Funcionários > Consulta Global de Log e filtre a Origem por Conexões automáticas, como explica Consulta Global de Log: entenda como funciona.
Quando as permissões do integrador mudam
O Monde pode mudar as permissões de um integrador depois que as agências já conectaram o sistema dele. A conexão continua a mesma, com a mesma chave de acesso, e o integrador não precisa fazer nada. O que muda na conexão depende de o integrador perder ou ganhar permissões.
Quando o integrador perde permissões
A permissão retirada sai na hora de todas as conexões ativas do integrador, sem a agência precisar aprovar. As demais permissões continuam como estavam.
Se o integrador perder todas as permissões que a conexão tinha, a conexão, aberta em Cadastros > Integrações no Monde Web, mostra Nenhuma permissão nesta empresa na lista de permissões. Quando o integrador pedir novas permissões, a conexão volta a funcionar depois que um administrador as aprovar, como explica a seção abaixo.
A retirada fica registrada no log da conexão, com as permissões que saíram e o aviso de que a mudança veio do Monde. Para consultá-lo, no Monde Web, acesse Funcionários > Consulta Global de Log e filtre a Origem por Conexões automáticas.
Quando o integrador pede novas permissões
Permissão nova só entra na conexão com a aprovação de um administrador da agência. Até lá, a conexão continua funcionando com as permissões que já tinha.
No Monde Web, acesse Cadastros > Integrações e abra a conexão do integrador
Confira o aviso com o nome do integrador seguido de pede novas permissões, com a lista do que entra. A permissão com o selo Acesso ampliado traz também o motivo que o Monde registrou ao concedê-la ao integrador
Clique em Aprovar e confirme
A conexão passa a ter também as permissões da lista, e a aprovação fica no log da conexão, com quem aprovou.
Detalhes do pedido:
O aviso aparece só ao abrir a conexão em Cadastros > Integrações, no Monde Web. O Monde não envia e-mail nem notificação sobre ele;
O pedido não expira: fica na conexão até um administrador aprová-lo;
Só as conexões ativas mostram o pedido. A conexão desativada já volta com as permissões atuais do integrador quando é reativada;
Se o pedido mudar enquanto a tela está aberta, o Monde não aprova e mostra a mensagem O integrador mudou o pedido de permissões. Confira a lista atualizada antes de aprovar. Abra a conexão de novo, confira a lista e clique em Aprovar.
Mensagens de erro conhecidas
As mensagens abaixo aparecem para a agência ao clicar em Conectar com o Monde no sistema do integrador, ou na tela de autorização que abre em seguida.
A conexão automática deste integrador ainda não está configurada
Causa: o integrador ainda não informou a Política de privacidade ou a URL de retorno na área dele.
Como resolver: avise o integrador, que completa os dados em https://web.monde.com.br/partners/integration. A agência não tem como liberar isso.
A conexão automática deste integrador ainda está em homologação com o Monde
Causa: a integração do integrador ainda está em teste com o Monde e não foi liberada para todas as agências.
Como resolver: fale com o integrador para saber quando a conexão será liberada. A agência não tem como liberar isso.
Apenas administradores da agência podem autorizar integradores a acessar a API
Causa: o usuário que entrou no Monde não é administrador.
Como resolver: peça a um administrador da agência que faça a autorização, ou ajuste o usuário em Como configurar Permissões de Acesso.
Validação e próximos passos
Para garantir que a conexão automática foi concluída, confira os dois lados.
O integrador entra em https://web.monde.com.br/partners/integration e verifica se a situação aparece como Conexão habilitada;
A agência acessa, no Monde Web, Cadastros > Integrações e verifica se a conexão aparece com o tipo Conexão automática, a empresa certa e a situação Ativa.
A partir daí, os registros criados pelo integrador entram no Monde da agência sozinhos. As integrações em que a agência informa usuário e senha do fornecedor são outro caminho, descrito em Como cadastrar, editar, desativar ou excluir integrações com fornecedores.
