Integração com Plataforma

API para integração com o e-Millennium

Modelo de integração, contendo os detalhes sobre nossa API no padrão ODATA que permite conversar utilizando REST, JSON, utilizado no e-Millennium.

O Servidor de aplicação Millennium (wtsBroker) é um serviço que permite a invocação de procedimentos de negócios (chamados de transações) executando em um computador servidor por um programa client. A plataforma Millennium é totalmente construída com base neste servidor, ou seja, não se trata de um recurso feito apenas para permitir integrações. Por isto, o servidor é escalável e provado, provendo um grande número de funções disponíveis que podem ser chamadas pelas APIs disponíveis.

esquema-comunicacao-client-server-millenniumjpg

Para permitir a chamada das funções expostas pelo servidor Millennium por qualquer linguagem de programação do Windows, a Millennium desenvolveu um componente ActiveX capaz de manipular e invocar as transações no servidor de aplicações por meio de TCP/IP utilizando um protocolo extremamente compacto e eficiente. A versão 2.0 do SDK possui também um gateway que permite a comunicação via OData/REST com o servidor. Este protocolo utiliza apenas padrões abertos da internet, permitindo a qualquer linguagem capaz de fazer chamadas HTTP acesso às funções do servidor. Qualquer nova integração deve utilizar a API OData/REST.

Devido ao grande volume de chamadas disponíveis na aplicação Millennium, foram desenvolvidas algumas bibliotecas específicas, com chamadas mais concisas, especializadas em certas áreas. Neste documento trataremos do MILLENIUM_ECO, que foi desenvolvido para integrações onde o pedido de venda é capturado externamente ao MILLENNIUM. Este cenário é típico de sites de e-commerce ou m-commerce, mas pode também ser utilizados em outros cenários como integração com coletores de dados ou qualquer outro dispositivo.

Millenium_Eco

A biblioteca Millenium_Eco foi desenvolvida especialmente para facilitar o uso por integradores com a plataforma Millennium. Esta biblioteca expõe apenas métodos especializados em tarefas comuns de integração como:

  • Leitura da árvore de classificações do produto
  • Leitura de produtos com suas características
  • Leitura de estoque
  • Leitura de preço
  • Leitura de cadastros auxiliares
  • Manutenção (inserção e alteração combinada) de clientes e consulta
  • Inserção e consulta de pedidos
Alguns dos métodos de integração se baseiam no envio de uma data/hora de mudança que o sistema utiliza para retornar apenas os registros que foram modificados a partir dela. Para evitar problemas de sincronização de horários, recomendamos ler a última data de sincronização diretamente dos registros retornados. Isto é possível porque os métodos retornam e são ordenados pelo campo DATA_ATUALIZACAO. Desta forma é apenas necessário armazenar o valor do último registro lido e repassá-lo à consulta na próxima vez.

Além de limitar a lista dos registros antigos, é possível utilizar a opção $top nas chamadas para limitar o número de registros retornados. Esta forma de leitura é importante porque equilibra o processamento em lotes menores entre o servidor e sua aplicação. Os métodos que suportam controle de mudança são:

  • Vitrine.Lista_Classificacoes
  • Produtos.Lista ou Produtos.ListaVitrine
  • Produtos.PrecoDeTabela
  • Produtos.SaldoDeEstoque
  • Pedido_Venda.ConsultaStatusWF

Abaixo temos um pseudo-código demonstrando este padrão para a listagem de produtos:

Leitura_incremental

O fluxo básico para o qual o millenium_eco foi desenvolvido se baseia na exportação das informações relacionadas aos produtos (incluindo categorias, preços e estoque) e importação dos clientes e pedidos. Os produtos possuem informações sensíveis como preços e estoque que podem ser sincronizadas com maior frequência e informações cadastrais que mudam menos e podem ter maior frequência de atualização. As informações de preços e estoques são obtidas por métodos especializados ao invés de serem listados como mudanças de produtos porque a lista de produtos é muito mais complexa, por outro lado, com métodos especializados é possível retornar milhares de registros mais simples com grande desempenho.

É importante enviar os pedidos ao Millennium imediatamente após serem lançados para que o estoque seja reservado e reflita a baixa. Se isto não for feito, uma chamada que busca o estoque fará a leitura incorreta do saldo, podendo levar a vendas sem estoque disponível. Se a sua plataforma possuir o conceito de reserva, esta chance é bastante minimizada.

fluxo_basico_integracao-1024x546

O conceito de vitrine foi desenvolvido na plataforma Millennium para permitir diversas apresentações diferentes dos produtos cadastrados no sistema, levando o conceito omnichannel ao extremo. Com este conceito, é possível organizar a árvore de produtos, determinar preços e estabelecer regras para cada canal, mesmo que estes acessem o mesmo servidor Millennium. Cada vitrine pode ser configurada, por exemplo, para atender a um site B2B, outra para B2C, outra para uma loja no facebook e ainda outra para uma loja com parceiro todas compartilhando ou não os mesmos produtos. As possibilidades são ilimitadas.

conceito_vitrine-1024x216

A integração de produtos se inicia pela integração de categorias. A chamada Vitrine.Lista_Classificacoes recebe um código de vitrine retorna uma lista com uma árvore de classificação no formato id/idpai. As classificações consideradas ativas são aquelas que possuem produtos ativos abaixo dela, o que pode ser verificado pelo campo QTDE_ATIVOS. Quando este campo possui zero, significa que não há produtos ativos em nenhum nível abaixo deste nó e, portanto este pode ser desativado até uma segunda integração. Sempre que existir mudança em um nó da categoria, o sistema irá retornar toda sua hierarquia até o último pai para facilitar a verificação dos nós ativos.
O segundo passo da integração de produtos é a leitura dos cadastros. Para isto é utilizada a chamada Produtos.ListaVitrine. Esta chamada recebe um identificador de vitrine e uma data de atualização. A data de atualização deve ser utilizada conforme o padrão demonstrado no tópico 2.1. Além dos dados básicos de produtos, esta chamada retorna algumas listas importantes:

        • SKU: Esta lista possui os dados das variações de um produto como cor e tamanho, além de suas características como dimensões e tempo de entrega. O campo “inativo” também deve ser verificado, já que o usuário pode desativar certos SKUs para que não apareçam para venda. As mudanças de preço e estoque devem ser lidas por meio dos métodos PrecoDeTabela e PRODUTOS.SaldoDeEstoque que também possuem controle de mudança.
        • CLASSIFICACOES: Retorna uma lista com os identificadores das classificações da vitrine associadas ao produto. Um produto pode estar associado a mais de uma classificação (isto pode ser controlado por vitrine). Se um produto é adicionado a uma classificação e depois removido, a lista ainda assim retornará tal classificação com o campo “EXCLUIDO” marcado como true.
        • ESPECIFICACOES: A lista de especificações pode ser usada para adicionar classificações que variam produto a produto. Geralmente estes valores são usados para formar a área de filtro dos produtos, ou a aba de especificações técnicas. É possível identificar o uso da especificação por seu código. Cada especificação possui um tipo, um nome e uma descrição que podem ser utilizadas para compor o conteúdo dependendo da necessidade da plataforma. O uso pela plataforma (filtro, aba etc) pode ser controlado pelo tipo da especificação.
Os preços são integrados por meio do método produtos.PrecoDeTabela que recebe um identificador de vitrine, por onde o sistema já identifica as tabelas de preço e as promoções ativas. Este método também recebe e retorna uma data de atualização que deve ser utilizada conforme o padrão demonstrado no tópico 2.1. São retornados os dados do SKU (produto, cor, estampa e tamanho e id SKU) o PRECO1 e PRECO2, sendo que o primeiro é o preço atual do produto. Quando existe uma promoção, o PRECO2 retorna o preço anterior à promoção (ou preço “de”), caso contrário o valor será igual ao do PRECO1.
Os saldos de estoque são integrados por meio do método produtos.SaldoDeEstoque que recebe um identificador de vitrine, por onde o sistema já identifica as tabelas de preço e as promoções ativas. Este método também recebe e retorna uma data de atualização que deve ser utilizada conforme o padrão demonstrado no tópico 2.1. São retornados os dados do SKU (produto, cor, estampa e tamanho e id SKU) e os saldos separados que devem ser utilizados da seguinte forma:

Se sua plataforma possui o conceito de reserva deve ser utilizado como saldo:

((SALDO + RESERVA_VITRINE)-(SALDO_NAOVITRINE – RESERVA_NAOVITRINE))
ESTOQUE_MIN

Se sua plataforma não possui o conceito de reserva, deve ser utilizado como saldo:

(SALDO)-(SALDO_VITRINE – RESERVA_VITRINE)-(SALDO_NAOVITRINE -RESERVA_NAOVITRINE)-ESTOQUE_MIN

Toda a integração de pedidos é orquestrada pelo método pedido_venda/processaStatus. Este método recebe uma lista de registros contendo o código do pedido e o status atual no seu ponto de vista. Esta lista é processada no Millennium e como resposta, é retornada uma lista de códigos de pedido e ações para que você processe, como no diagrama abaixo:

integracao_pedidos-1024x427

Para facilitar o entendimento, vamos considerar 3 pedidos, WEB-000001 a WEB000003. O código dos pedidos deve ser enviado ao serviço da maneira que serão incluídos no Millennium. É recomendado o uso de um prefixo antes do código do pedido (WEB-* no exemplo), para evitar conflito de numeração. Para cada pedido, deverá será enviado o status conforme tabela abaixo:

Status Significado
0 – Aguardando Pagamento O pedido foi inserido no site, mas o pagamento está pendente. Esta situação ocorre mais comumente em caso de pagamento por boleto, mas o Millennium pode processar os cartões se assim for parametrizado.
1 – Pagamento Confirmado O pedido foi inserido no site e o pagamento já foi confirmado (do ponto de vista do site)
2 – Em separação Em outra chamada, o Millennium retornou que o pedido está em separação. O site deve atualizar seu status e repassá-lo na próxima chamada.
5 – Cancelado O cliente cancelou o pedido no site.

A chamada ao Millennium ficará assim:

integracao_pedidos_chamada-1024x393

Quando o Millennium retornar a ação 1, como no pedido WEB-000001 do nosso exemplo, você deve chamar a sequência de inclusão de pedidos, conforme sequencia abaixo:

integracao_pedidos_retorna-1024x427

Quando o Millennium retorna a ação 2 (mudar status), o campo status associado à ele retornará para qual status você deve alterar seu pedido. Conforme o status, alguns campos associados ao registro também retornam conforme tabela abaixo. Note que estes status devem ser considerados sempre quando a ação é 2, em outras ações esta tabela não se aplica:

Seu Status Status Retornado Significado
0 – Aguardando Pagamento 1 – Pagamento confirmado O Millennium verificou que todos os títulos financeiros associados ao pedido já foram processados.
Normalmente isto ocorre em casos de boleto, já que a plataforma deve aguardar o processamento do boleto
para liberar o pedido, porém existem casos onde o Millennium pode processar também os cartões.
1 – Pagamento Confirmado 2 – Em preparação Ao passar ao Millennium a confirmação do pagamento, é executada a liberação da reserva para
expedição, gerando o retorno de preparação.
2 – Em separação 3 – Despachado O pedido foi faturado e a nota aprovada. Se foi implementada a integração SIGEP, o sistema
irá aguardar que o numero do objeto seja informado. Os campos serão também retornados: nota, serie_nf,
url_tracking_pedido, valor, data_emissao_nf

Vale ressaltar que, enquanto o status não mudar, a ação retornada será 0 (zero), indicando que nada deve ser feito em relação ao pedido. A tabela acima aplica-se apenas quando a ação retornada é 2.

Baixe Documentação Completa

Servidor de Teste

Todos os nossos métodos para integração estão disponíveis e atualizados online em uma instância de integração que permite iniciar os testes de integração imediatamente.

Servidor de Testes

Que tal uma coleção de exemplos prontos de nossa API?

Instale a extensão do Google Chrome – Postman:

Instale o Postman

Após instalar o Postman, importe a nossa Collection para ver os exemplos.

É bem simples, Copie e cole esse endereço https://www.getpostman.com/collections/f015d4034ca5ad30e01c na Opção “Import a Collection” disponível no Postman, conforme figura abaixo:

collection_tela-300x213