Documentação

Integração Ploomes - Omie

Equipe

  • Matheus Pagani - CEO

  • Vinicius Sampaio - CTO

  • Pedro Queiroz - Developer

  • Fernanda Machado - Product Manager

  • Arthur Soares - Quality Assurance

Introdução

A integração do Ploomes com o Omie ERP tem como objetivo unir as entidades de clientes, produtos e vendas dos dois sistemas. Esta aplicação permite a integração rápida, fácil e sem custos adicionais de desenvolvimento para os clientes da parceria.

Este documento apresenta o escopo e as explicações da integração. O documento começa com o resumo do escopo geral da integração. Em seguida, é explicado como funciona o mapeamento de campos entre as duas ferramentas e as instruções de ativação. Por fim, são demonstrados os detalhes técnicos de implementação para os desenvolvedores que precisarem de algum tipo de guia.

Escopo geral

A integração do Ploomes com o Omie liga as informações de clientes, produtos e vendas do Ploomes com as entidades de Clientes/Fornecedores, Produtos e Serviços e Venda de Produto no Omie.

Conforme a imagem abaixo, a comunicação da integração se comporta unilateral ou bilateralmente, a depender das entidades envolvidas. A entidade de Clientes no Ploomes, se comunica bilateralmente com a entidade de Clientes/Fornecedores do Omie. Isso quer dizer que a criação, edição e exclusão de um cliente em um dos sistemas afetará o outro também. Entenda sobre mais quais são os campos que fazem parte da integração e às exceções de integração na seção sobre clientes.

A base de Produtos do Ploomes será preenchida pelo Omie, já que esta integração é feita unilateralmente. Qualquer criação, edição e exclusão no Omie será refletida no Ploomes. Por outro lado, nenhuma modificação no Ploomes é enviada ao Omie. O Omie possui duas entradas separadas: uma para produtos e outra para serviços. Essas duas tabelas serão enviadas ao Ploomes como produtos. Dito isso, recomenda-se que o cliente que optar por ativar a integração use somente o Omie para gerenciar os seus produtos.

A entidade de Proposta do Ploomes não é integrada ao Omie. Os cálculos de preços serão configurados no Ploomes, já que não foi possível integrar as tabelas de preços do Omie. A contribuição do Omie na criação de propostas será com o campo de consulta de estoque. Ao ativar a integração, o campo de tabela de estoque estará disponível para o usuário. Este campo dinâmico em produtos no Ploomes que contém uma tabela de informações sobre estoque de produto obtidas do Omie, obedece às regras de negócio do Omie como permissão de acesso da tabela para vendas e inativação da tabela.

Por fim, Vendas no Ploomes estão integradas ao módulo de Venda de Produto do Omie. Portanto, é imprescindível que o módulo esteja habilitado na conta Ploomes daqueles que querem usufruir da integração. A integração se comporta bilateralmente, então criação, edição e exclusão são transferidas entre os dois lados. Vale destacar que, por mais que os serviços do Omie sejam enviados ao Ploomes, a entidade de Vendas não está integrada à entidade de Ordens de Serviços do Omie. Qualquer venda, contendo produtos ou serviços, será enviada ao módulo de Venda de Produto do Omie.

De forma implícita, foi necessário sincronizar também usuários Ploomes com vendedores Omie, mas de forma passiva, i.e., não são criados novos usuários em nenhum dos dois lados já que o número de usuários define o preço de licença do software Ploomes, e também do Omie. É feita uma busca com base no e-mail, que é esperado existir em ambos os lados, como usuário Ploomes e vendedor Omie.

A próxima seção explica o comportamento fixo entre os dois sistemas. Alguns campos de clientes, produtos e vendas se comportam da mesma forma durante a integração para todos os usuários. A seção de mapeamento de campos explica melhor como o usuário pode customizar a integração usando campos personalizados do Ploomes para enviar impostos, dados dos clientes e especificidades das vendas entre os dois sistemas.

Escopo: Detalhamento das entidades

Cada entidade integrada apresenta suas próprias particularidades e comportamentos. A seguir, cada entidade é detalhada com a informação de quais campos têm protagonismo na comunicação entre os dois sistemas e quais ações dos usuários podem prejudicar a sincronização das informações.

Contatos

As entidades de Clientes/Fornecedor (Omie) e Contatos (Ploomes) estão sincronizadas simultaneamente com seus campos mais importantes.

Mapeamento fixo de campos:

  • Razão Social;

  • Nome Fantasia [CNPJ] / Nome Abreviado [CPF] (Omie) <=> Nome (Ploomes);

  • CNPJ/CPF;

  • Endereço;

  • Número;

  • Bairro;

  • Complemento;

  • Estado;

  • Cidade;

  • CEP;

  • DDD Telefone;

  • Telefone;

  • DDD Telefone 2;

  • Telefone 2;

  • DDD fax;

  • Fax;

  • E-mail;

  • Website;

  • Código CNAE;

  • Vendedor padrão (Omie) <=> Responsável (Ploomes) ;

  • Tags (Omie) <=> Marcadores (Ploomes) ;

  • Ativo/Inativo (Omie) => Status (Ploomes).

Observações:

  • É possível colocar mais de um endereço no Omie, mas não no Ploomes (precisa criar novos campos). Então, por enquanto, o Ploomes conseguiria integrar apenas um endereço. O endereço integrado será o primeiro inserido no Omie.

  • O Omie possui um limite de três telefones por cadastro, diferente do Ploomes que permite a inclusão de vários números em um só contato. Por isso, os números de telefones cadastrados no Ploomes são enviados para os seguintes campos do Omie: Telefone 1, Telefone 2 e Fax. Se mais de três números de telefones forem cadastrados, apenas os três primeiros números serão enviados ao Omie.

  • O Omie possui uma funcionalidade de ativar/inativar clientes cadastrados. Clientes inativados continuam na base mas não podem ser selecionados para vendas. As informações de ativo/inativo serão enviadas ao Ploomes como opções do campo de Status do cliente. No entanto, a edição do campo no Ploomes não afetará a ativação/inativação no Omie via API. Portanto, ao ativar a integração, é recomendável bloquear o campo status da entidade Cliente no Ploomes (por segurança, ele já força manter o valor).

  • O campo responsável representa um usuário no Ploomes, e para integrar com o Omie, é preciso que haja um vendedor com o mesmo e-mail cadastrado no Omie.

  • O Omie exige preenchimento dos campos Razão Social e também do Nome Fantasia e no Ploomes só é exigido o campo Nome. Caso a razão social não seja preenchida no Ploomes, é tomado o que foi digitado no campo Nome para maior flexibilidade ao usuário.

  • O Omie exige que o cliente tenha um CNPJ ou CPF, enquanto que no Ploomes não. Contatos sem um número de documento não são integrados. Isso implica em dois comportamentos:

  • Um cliente sem documento vai ser enviado ao Omie assim que o CPF ou CNPJ for cadastrado. Isso pode ser usado para controlar as etapas de workflow no Ploomes, ou seja, para controlar quando o contato é enviado ao Omie.

  • Se um número de documento válido for retirado de um cliente, a integração de edição deste cliente é interrompida.

  • O Ploomes não permite que um contato seja trocado de tipo pessoa física para jurídica (pessoa ou empresa) ou vice e versa, já o Omie sim. Por isso, trocar o tipo de pessoa no Omie não irá refletir no Ploomes.

Produtos

Os produtos no Ploomes são sincronizados com os Produtos e os Serviços do Omie. Eles são divididos por famílias, em que haverá uma família chamada “Produtos”, e outra chamada “Serviços”. Dentro da família de produtos no Ploomes, pode haver vários grupos, que são sincronizados com o campo chamado família de produto no Omie (grupo de produto Ploomes = campo família de produto Omie). Produtos Omie sem informação no campo família de produto são alocados no grupo “Produtos” dentro da família “Produtos” do Ploomes. Como os cadastros de serviços no Omie não possuem um campo de família, os serviços são cadastrados no Ploomes com o grupo “Serviços” da família “Serviços”.

Mapeamento fixo de campos:

  • Descrição (Omie) => Nome (Ploomes);

  • Código do produto;

  • Família de produto (Omie) => Grupo de produto (Ploomes) *;

  • Preço unitário de venda (Omie) => Valor unitário (Ploomes);

  • Unidade (Omie) => Unidade de Medida(Ploomes)

  • (In)atividade (Omie) => Marcadores (Ploomes)

Observações:

  • O campo de marcadores de produtos no Ploomes segue o mesmo comportamento do campo status relatado nas observações da integração de clientes.

  • Consulta de estoque: um campo dinâmico do tipo de texto multilinha guarda uma tabela HTML de estoque de produtos. Esta tabela obedece às regras de negócio de permissão para vendas do painel de configuração de Locais de Estoque no Omie. Desta forma, só aparecem estoque de locais habilitados para venda, opção destacada da imagem a seguir:

Os campos carregados à essa tabela são:

  • Status do Estoque

  • Local de Estoque

  • Estoque Disponível

  • CMC Unitário

  • CMC Total

  • Estoque Mínimo

  • Previsão de Saída

  • Tipo de Local de Estoque

Esta tabela é atualizada quando acontece uma movimentação no estoque do produto em que ela está ou quando o administrador clica em atualizar. Esta ação atualiza a situação de todos os produtos. No fim da tabela é indicado data e horário da última atualização para maior transparência.

Vendas

Mapeamento fixo de campos:

  • Cliente

  • Vendedor

  • Itens do pedido

  • Produto do item

  • Quantidade

  • Preço definido

Observações:

  • As vendas do Ploomes e os pedidos do Omie sincronizam automaticamente ao ligar a integração. Isso quer dizer que, vendas e pedidos criados antes da ativação vão ser sincronizados entre os dois sistemas assim que a integração for ativada. Com isso, passamos o histórico de vendas e de pedidos de um lado para o outro.

  • Os serviços do Omie também são incluídos no cadastro de produtos do Ploomes da forma explicada acima. No entanto, devido ao impasse técnico comentado sobre a API de ordem de serviços, incluir serviços em uma venda não criará uma ordem de serviço.

  • Todas as vendas são inseridas no Omie usando a informação de conta corrente configurada no modal da integração.

  • Caso o cliente Omie da venda não tenha um estado no cadastro, o pedido não é criado. Desta forma, o preenchimento do Estado do cliente é obrigatório para a geração do pedido no Omie.

  • Caso o produto Omie usado em um item da venda não tenha valor, este não é inserido no pedido. O preenchimento do valor do produto é obrigatório para a geração de um pedido no Omie corretamente.

  • Caso o item da venda tenha a quantidade zerada, este não é inserido no pedido. A quantidade do produto precisa ser maior que zero para a geração de um pedido no Omie corretamente.

  • Os itens não seguem a mesma sequência de número do pedido unilateralmente. Caso seja desejável sincronizar os números do pedido em ambos os lados, Ploomes e Omie, é possível configurar o próximo número a ser usado no Ploomes. No módulo de Administração, entre na opção Módulos do sistema e selecione Vendas.

  • O pedido ao ser enviado para o Omie, é inserido com as configurações tributáveis alteradas automaticamente pelo Omie.

  • No Omie é possível alterar o Cliente da venda, no Ploomes não. Alterações no Cliente da venda no Omie não são aplicadas no Ploomes.

  • O Omie não permite que uma venda de produto seja excluída, apenas cancelada. Por isso, um pedido excluído no Omie é apagado do Ploomes, mas uma venda excluída no Ploomes apenas cancela um pedido no Omie.

Mapeamento de campos

Durante a ativação da integração, o cliente vai conseguir mapear campos do Ploomes com campos do Omie. Com isso, os usuários poderão usufruir da integração através das regras fixas entre campos (como mencionado na seção de Escopo), e de regras customizadas de acordo com as necessidades deles.

Tendo em vista que os campos do Omie e do Ploomes apresentam comportamentos diferentes, é importante salientar os seguintes pontos:

  • Toda mudança no mapeamento de campos é salva ao clicar em “Atualizar integração”. Quando a opção é ativada, a uma nova varredura é feita entre os dois sistemas. Esse processo pode demorar alguns minutos e é bastante pesado, então evite atualizações constantes a todo momento. Atualize a integração quando terminar todas as modificações ao invés de salvar a cada campo mapeado. A integração só executa caso houver alguma diferença nas configurações (para evitar abuso dessa função que sobrecarrega a API do Omie).

  • Os campos do tipo “opções pré-cadastradas” sincronizam suas opções com o Omie toda vez que a integração é atualizada. Ou seja, uma sincronização é disparada quando o usuário clica em “Atualizar integração” no painel de configuração de plug & play no Ploomes. Portanto, evite a alteração das opções quando o campo for usado na integração. Uma dica para evitar falhas é restringir a edição e inclusão de opções do campo para apenas o administrador da conta.

  • Toda vez que um campo de imposto do Omie é mapeado, o sistema do Omie automaticamente interpreta que as informações de imposto serão enviadas do Ploomes ao Omie. Então, o usuário deve escolher entre fazer as regras de impostos do Ploomes e enviar para o Omie ou deixar que o Omie se encarregue dos impostos. Cuidado com esta decisão. Se ao menos um campo de imposto do Omie for mapeado, ele deixa de calcular os impostos.

  • Alguns campos são apenas para leitura. O Omie recebe a informação mas não a utiliza para inserção ou atualização. Esses campos são:

  • Valor do Desconto

  • Total de Mercadorias

  • Valor Total do Pedido

  • Total de ICMS ST

  • Total de IPI

  • Nº pedido do cliente

  • Etapa

  • Os campos a serem mapeados devem ter tipos compatíveis. Se qualquer campo estiver mapeado com tipos errados, a integração alerta sobre esse erro e não executa a sincronização.


  • Abaixo está a relação de campos do Omie e o tipo de campo esperado no Ploomes:

Campo do Omie

Tipo de campo do Ploomes

ClienteFornecedor.Inscrição Estadual

Texto Simples

ClienteFornecedor.Inscrição Municipal

Texto Simples

ClienteFornecedor.Inscrição SUFRAMA

Texto Simples

ClienteFornecedor.Tipo de Atividade

Opções pré-cadastradas

ClienteFornecedor.Optante do Simples Nacional

Checkbox

ClienteFornecedor.É um produtor rural

Checkbox

ClienteFornecedor.Limite de Crédito Total

Moeda

Produto.Código EAN

Texto Simples

Produto.Marca

Texto Simples

Produto.Altura

Número com casas decimais ilimitadas

Produto.Largura

Número com casas decimais ilimitadas

Produto.Profundidade

Número com casas decimais ilimitadas

Produto.Dias de Garantia

Número inteiro

Produto.Dias de Crossdocking

Número inteiro

Produto.Peso Líquido

Número com casas decimais ilimitadas

Produto.Peso Bruto

Número com casas decimais ilimitadas

Produto.Indicador de Produção em Escala Relevante

Checkbox

Produto.Descrição Detalhada do Produto

Texto Multilinha

Produto.Observações Internas

Texto Multilinha

VendaProduto.Previsão de Faturamento

Data

VendaProduto.Valor do Desconto (apenas leitura)

Moeda

VendaProduto.Total de Mercadorias (apenas leitura)

Moeda

VendaProduto.Valor Total do Pedido (apenas leitura)

Moeda

VendaProduto.Total de ICMS ST (apenas leitura)

Moeda

VendaProduto.Total de IPI (apenas leitura)

Moeda

VendaProduto.Tipo do frete

Opções pré-cadastradas

VendaProduto.Valor do Frete

Moeda

VendaProduto.Observações

Texto Multilinha

VendaProduto.Nº pedido do cliente (apenas leitura)

Texto Simples

VendaProduto.Etapa (apenas leitura)

Opções pré-cadastradas

VendaProduto.Número de Parcelas

Número inteiro

VendaProduto.Contato

Texto Simples

VendaProduto.Item.Alíquota ICMS

Porcentagem

VendaProduto.Item.Base ICMS

Moeda

VendaProduto.Item.Situação Tributária ICMS

Opções pré-cadastradas

VendaProduto.Item.Modalidade ICMS

Opções pré-cadastradas

VendaProduto.Item.Origem ICMS

Opções pré-cadastradas

VendaProduto.Item.Percentual de redução da base de cálculo do ICMS

Porcentagem

VendaProduto.Item.Valor ICMS

Moeda

VendaProduto.Item.Alíquota ICMS ST Operação Própria

Porcentagem

VendaProduto.Item.Alíquota ICMS ST

Porcentagem

VendaProduto.Item.Valor Base ICMS ST

Moeda

VendaProduto.Item.Margem ICMS ST

Número com casas decimais ilimitadas

VendaProduto.Item.Modalidade ICMS ST

Opções pré-cadastradas

VendaProduto.Item.Percentual de redução da base de cálculo do ICMS ST

Porcentagem

VendaProduto.Item.Valor ICMS ST

Moeda

VendaProduto.Item.Alíquota IPI

Número com casas decimais ilimitadas

VendaProduto.Item.Valor Base IPI

Moeda

VendaProduto.Item.Situação Tributária IPI

Opções pré-cadastradas

VendaProduto.Item.Enquadramento IPI

Opções pré-cadastradas

VendaProduto.Item.Quantidade de Unidades Tributáveis do IPI

Número com casas decimais ilimitadas

VendaProduto.Item.Tipo de cálculo do IPI

Opções pré-cadastradas

VendaProduto.Item.Valor IPI

Moeda

VendaProduto.Item.Valor do IPI por Unidade Tributável

Moeda

Instruções de ativação da integração

  1. Após a criação do seu aplicativo Omie, acesse a seguinte URL: https://developer.omie.com.br/my-apps/ e entre com seu login e senha.

  1. Na tela inicial estão as informações necessárias para realizar a integração. Vamos utilizar o App Key e App Secret para dar continuidade pelo Ploomes.

  1. Após copiar as informações, basta acessar o Ploomes e navegar para a tela de Integrações Plug & Play pela opção Administração no menu lateral.

  1. Basta clicar na integração do Omie na lista e habilitar a integração.

  1. Copie as informações de App Key e App Secret nos campos que serão exibidos na tela de configuração da integração e clique em “Ativar a integração”.

  1. Após a ativação da integração, copie a URL gerada para criar os webhooks dentro do Omie.

  1. Retorne ao painel do Omie e na barra inferior de opções do mesmo aplicativo que foi configurado no Ploomes (App Key) e clique em “Adicionar novo webhook”.

  1. Cole a URL gerada pelo Ploomes no campo “Endpoint”.

  1. Marque as seguintes entidades e clique em “SALVAR” ao final.

  1. Cliente Fornecedor

  1. Produto

  1. Serviço

  1. Venda Produto

  1. Mapeie os campos que vão ter uma comunicação entre o Ploomes e o Omie. Se atente à tabela de correspondência entre os campos Omie e o tipo de campo no Ploomes. Quando acabar, finalize a ativação da integração.

Detalhes de Implementação

Esta seção tem por objetivo auxiliar desenvolvedores responsáveis pela manutenção da integração ou pela criação de projetos adicionais para clientes que pagarem o adendo. Essas dicas foram deixadas pelo desenvolvedor da integração, Pedro Queiroz.

  • O link a seguir contém uma lista de endpoints disponíveis para informações dos aplicativos Omie (link) .

  • As requisições sempre seguem o formato a seguir:

POST https://app.omie.com.br/api/v1/módulo/entidade/

{

“call": “NomeDaChamada”,

“app_key”: “valorDaAppKey”,

“app_secret”: “valorDaAppSecret”,

“param": [

{

“parametro1”: “valor1”,

“parametro2”: 2,

...

}

]

}

  • As chaves e senha dos aplicativos estão disponíveis aqui. Os parâmetros esperados pela chamada se encontram também no link do endpoint da chamada em questão.

  • Todas as requisições são POST.

  • A maioria dos erros devolvidos pelo Omie (pra não dizer todos) são do status code 500. Isso inclui propriedades no JSON de parâmetros (param) que não são esperadas. Para citar exemplos, uma requisição totalmente correta em todos os aspectos, mas que não retorna nenhum resultado devido aos valores dos filtros, ou até mesmo sem filtros mas que a tabela dessa entidade esteja vazia pra essa conta do Omie. Todos esses exemplos devolvem status code 500, caso contrário, retorna status code 200 normalmente.

  • Requisições que alteram uma entidade específica (AlterarCliente por exemplo), têm uma taxa de requisição por código por minuto muito baixa. Isto significa que com poucas requisições você é bloqueado de fazer requisições para esta mesma entidade por em média 1 a 5 minutos.

  • Dentro do projeto CallbackHub2, foi feito um utilitário em OmieIntegration.cs na classe OmieRequest, que unifica as requisições de maneira simplificada:

string result = new OmieRequest(“valorDaAppKey”, “valorDaAppSecret”).Module(“geral”) .Entity(“clientes”).Request(new JArray(){ new JObject() });

Qualquer erro causa retorno null.

  • Caso seja preciso requisitar uma lista inteira iterando por todas as páginas da consulta, tem um utilitário no mesmo arquivo supracitado, usado como no exemplo:

OmieRequest.Module("geral").Entity("clientes").Call("ListarClientes");

JArray param = new JArray() { new JObject() { { "apenas_importado_api", "N" } } };

List<OmieClientSupplier> results = new OmieListPageHandler<OmieClientSupplier>()

GetFullResults(OmieRequest, param, OmieType.CLIENTS);

  • Novas listas precisam ser adicionadas no enum OmieType, e nos lugares onde esse enum é usado. Basicamente existem dois tipos de listas por lá: as que parecem ser um pouco mais legadas que devolvem as propriedades paginadoras:

{

"pagina": 1,

"total_de_paginas": k,

"registros": m,

"total_de_registros": n

“lista_valores”: [...]

}

Que usam o método padrão explícito no código, e as que parecem ser recentemente implementadas que devolvem as propriedades paginadoras:

{

"nPagina": 1,

"nTotPaginas": k,

"nRegistros": m,

"nTotRegistros": n,

"listaValores”: [...]

}

Que usam os métodos que terminam com V2. Lendo o método a seguir fica claro e intuitivo o que foi comentado e o porquê dessas mudanças no enum:

OmieIntegration.cs

public List<T> GetFullResults(OmieRequest omieRequest, JArray param, OmieType omieType)

  • Algumas entidades do Omie têm uma propriedade no JSON para guardar um código externo, como por exemplo codigo_cliente_integracao na entidade de ClienteFornecedor. É preciso ter muito cuidado com isso, pois, métodos que referenciam uma entidade, como ConsultarCliente, AlterarCliente e DeletarCliente, recebem como parâmetro tanto o codigo_cliente que é o id do Omie (tipo inteiro long) quanto o codigo_cliente_integracao (tipo string). Caso os dois estejam presentes, em geral a API usa o código de integração para encontrar a entidade. Preencher os dois códigos chamando o AlterarCliente não vai atualizar o codigo_cliente_integracao da entidade representada por codigo_cliente ou vice versa. Para isso, usamos a chamada AssociarCodIntCliente (neste exemplo sobre a entidade de clientes). Nem todas as entidades têm esse método. Quando um registro de uma dessas for criado pelo aplicativo do Omie, o campo de código de integração ficará vazio e não será possível alterá-lo. Por esse motivo não recomendo dependerem das propriedades codigo_entidade_integracao em novas implementações.

  • Alguns métodos de listagem contém parâmetros para filtrar “apenas inseridos via API” ou parecido. Considere isso ao criar consultas em listas.

  • No campo “tags” de ClienteFornecedor, não é necessário criar a tag em outro lugar pra ser referenciada, o próprio nome da tag é a chave primária, e se não tiver criado antes, ele cria no momento de insert do ClienteFornecedor.

  • Para deletar um item de um pedido, é preciso inserir ele na lista de itens da requisição AlterarPedidoVenda, e adicionar no item o campo ide.acao com o valor “E” (de Excluir).

  • Requisições à API pública do Omie também ativam os webhooks registrados lá. Eles podem ser evitados se os webhooks recebidos forem verificados se o email do evento não é o email do usuário de integração deles, que é “no-reply@omie.com.br”.

Encontrou sua resposta?