Este artigo também responde a:
Onde eu gero a credencial de acesso da API do Monde?
Por que não consigo salvar a credencial da API?
Como liberar só algumas informações para quem vai fazer a integração?
Perdi a credencial da API, como faço para gerar outra?
O que você vai resolver
Neste artigo, você vai aprender a criar a credencial que o sistema externo usa para se conectar à API do Monde, a definir o que essa credencial pode acessar em cada empresa e a gerar uma nova quando a anterior for perdida.
Público-alvo: usuários com Acesso Total ao sistema.
Requisitos: a definição de quais informações a integração vai acessar. O que a API permite fazer está em Como utilizar a API do Monde.
Contexto ou termos-chave
Três termos aparecem ao longo do artigo e valem a pena entender antes de começar:
Credencial de acesso: o código que o sistema externo envia ao Monde em cada requisição, no lugar de usuário e senha. Ele vale para a base da agência.
Identificação da credencial: o nome que aparece nos logs e na auditoria do Monde quando a integração cria ou altera um registro. É por ele que você reconhece qual integração fez o quê.
Permissões da credencial: o que aquela credencial pode ler, criar, editar, fechar e anexar, definido empresa por empresa.
A tela Cadastros > Integrações também guarda as integrações com fornecedores, que são outro tipo de integração e não usam esta credencial.
Como criar a credencial
O problema: o sistema externo precisa de um acesso à base da agência, e o usuário e a senha de uma pessoa não servem para isso.
A causa: a API do Monde não usa o login do sistema. Ela usa uma credencial própria, criada na tela de Integrações e limitada às permissões que você marcar.
Como resolver:
Acesse Cadastros > Integrações;
Clique em Adicionar e selecione Integração com API Monde;
Digite a Identificação da credencial: o nome pelo qual você vai reconhecer essa integração depois. Pode ser o nome de uma pessoa ou uma referência ao sistema que vai se conectar, como BI Integração ou API Marketing;
Em Permissões, abra a aba da empresa que a integração vai acessar;
Marque as permissões de cada cadastro, ou use Selecionar todas as permissões para marcar todas de uma vez;
Repita os dois passos anteriores em cada empresa que a integração vai acessar;
Clique em Salvar e gerar credencial.
O Monde exibe a mensagem Credencial criada com sucesso e, logo abaixo do campo Credencial de acesso, mostra o código gerado.
O que marcar em Permissões
As permissões da credencial são separadas por empresa, uma aba para cada, e dentro de cada empresa são separadas por cadastro — Vendas, Pessoas, Produtos, Contas a Pagar e Receber, Notas Fiscais e os demais.
Cada cadastro oferece as permissões que fazem sentido para ele:
Ler todas as vendas, Ler todas as pessoas, e assim por diante: a integração consulta aquele cadastro;
Criar e editar: a integração lança e altera registros;
Fechar: a integração fecha a venda;
Adicionar anexos: a integração envia arquivos para a venda.
Marque só o que a integração precisa. Uma credencial que apenas alimenta um painel de BI, por exemplo, não precisa de permissão para criar nem para editar nada.
Essas permissões não se confundem com as Permissões de Acesso dos usuários: uma coisa é o que a integração pode fazer, outra é o que cada pessoa pode fazer no Monde.
Como copiar e guardar a credencial
A credencial aparece uma única vez, no momento em que é gerada, junto do aviso Certifique-se de copiar sua credencial de acesso agora. Por motivos de segurança, ela não será exibida novamente.
Clique no ícone de cópia ao lado do campo e envie o código a quem vai montar a integração, por um canal seguro. Depois disso, o Monde passa a exibir apenas a informação de que a credencial foi gerada.
A credencial dá acesso à base da agência dentro das permissões marcadas. Trate-a como uma senha: não publique em local público, não envie por conversa aberta e compartilhe apenas com quem vai configurar a integração.
A documentação com os endereços, os campos e os exemplos de uso está em https://web.monde.com.br/api/v3/documentation. É o material a repassar a quem vai montar a integração.
Como gerar uma nova credencial
Não existe como consultar uma credencial já gerada. Se ela for perdida, o caminho é gerar outra:
Acesse Cadastros > Integrações;
Localize a credencial pela Identificação da credencial e abra o cadastro dela;
Clique em Gerar nova credencial;
Confirme o aviso Tem certeza? Ao gerar uma nova credencial, a anterior será invalidada;
Copie o novo código e repasse a quem vai montar a integração.
A credencial anterior deixa de funcionar assim que a nova é gerada, e a integração que ainda estiver usando o código antigo para de se conectar até ser atualizada.
Como desativar ou excluir uma credencial
Quando a integração for suspensa por um período, desative a credencial em vez de excluí-la:
Abra o cadastro da credencial;
Clique em Editar;
Desmarque a opção Ativo;
Clique em Salvar.
Para remover de vez, use Excluir no mesmo cadastro. A exclusão não pode ser desfeita: para voltar a integrar, será preciso criar outra credencial e gerar um novo código.
Também é pelo botão Editar que se ajustam as permissões de uma credencial já criada — o que ela acessa pode mudar a qualquer momento, sem gerar um código novo.
Mensagens de erro conhecidas
Estas são as mensagens que podem aparecer ao salvar a credencial:
Mensagem exibida | Causa | Solução |
Permissões não podem ficar em branco | Nenhuma permissão foi marcada em nenhuma empresa | Abra a aba de cada empresa que a integração vai acessar e marque ao menos uma permissão |
Limitações conhecidas
A credencial é exibida uma única vez. Não há como consultá-la depois: se for perdida, o caminho é gerar uma nova, e a anterior deixa de funcionar.
A Identificação da credencial não pode ser alterada depois que a credencial é criada. Para usar outro nome, exclua a credencial e crie outra.
A credencial só alcança as empresas em que há permissões marcadas. Empresa sem nenhuma permissão marcada fica fora do alcance da integração.
Validação e próximos passos
Para garantir que a credencial está pronta para uso, acesse Cadastros > Integrações e verifique se ela aparece na lista com o tipo API Monde e a coluna Ativo marcada. Abrindo o cadastro dela, as permissões marcadas aparecem agrupadas por empresa.
A confirmação final vem do outro lado: a primeira consulta à API funciona com o código que você enviou.