Integração Service

Integração Service application mainly performs the synchronization of the Sankhya ERP with the e-commerce on the VTEX platform.

Features
About
NuGet Packages
Organization
Architecture
Diagrams
Development
Contributing

Features

Catalog export (products, SKU, components).
Price list update.
Update of stock availability.
Synchronization of the Lista de Compras (reflects catalog, prices, and stock).
Import orders.
Export of online course requests (Vitrine do Artesanato Digital).
Import and export of subscriptions (Canal do Artesanato).
Order status updates.
Integration with carriers and related services (AVJ/CGE, Mandaê, SIGEP - Correios).
Monitoring and correction of flows in orders (billing, correction of flows, and status).
Correction of NF-e.
Manual stock correction.
Data indexing for Elastic Search for report extraction.
Capture of events from VTEX’s Bridge module.
Capture geolocation by address of partners (customers) via Google Maps API.

About

This application is responsible for the integration between the various systems, platforms, and services used or developed by the Inovação group, such as:

System	Type
Sankhya	ERP
VTEX	E-commerce PaaS
Canal do Artesanato	Own platform
Lista de Compras	Own platform
Vitrine do Artesanato Digital	Own platform
SIGEP - Correios	Carrier / courier
Mandaê	Carrier / courier
WMW Vendas	CRM
Postal Net	AGF - Correios reporting system
CGE - AVJ	Delivery control and management

NuGet Packages

The following libraries are published as NuGet packages and can be consumed by other projects within the Inovação group:

Package	Description
`IntegracaoService.Configuration`	Application configuration and dependency resolution classes
`IntegracaoService.Databases`	Database communication classes (SQL Server, PostgreSQL, MariaDB/MySQL)
`IntegracaoService.Infrastructure`	Infrastructure utilities (versioning, operation management, competition)
`IntegracaoService.Logging`	Log adapter implementations
`IntegracaoService.Notifications`	Notification adapter implementations
`IntegracaoService.ProductsCrawlers`	Product data scraping utilities
`IntegracaoService.Shared`	Shared constants and cross-cutting classes
`IntegracaoService.TotalIp`	PostgreSQL integration with TotalIP (Digital PBX)
`IntegracaoService.WMWVendas`	SQL integration with WMW Vendas CRM

Organization

The application consists of 26 projects:

Solution

Src
- Hosts
  - Services — Workers that perform tasks in the background (gRPC / RabbitMQ).
  - Application — Main application, running as a dispatcher.
  - ForIntegration — API to receive webhooks and provide functionality for the general intranet.
  - Scheduler — Node.js application that executes scheduled tasks.
  - Installer / Updater — Installs and updates the main application.
- Lib
  - App
    - Core — Library with event handlers.
    - GUI — Windows Forms library (authentication, note correction, stock correction, order checking).
    - Products Crawlers — Data scraping of competing websites for product pricing.
    - Resources — Images and templates shared across projects.
    - TotalIp — PostgreSQL integration with TotalIP (Digital PBX).
    - VTEX — Integration with VTEX. (Migrating to VTEX-SDK-DotNet)
    - WMWVendas — SQL integration with WMW Vendas.
  - Domain & Infra
    - Integrations — Wrappers for integrations that do not require their own project.
  - Utilities
    - Commons — Basic features, utilities, and shared helpers.
    - Commons Utils — Additional integrations to be migrated to Integrations.
    - Configuration — Application configuration classes.
    - Databases — RDBMS communication classes (SQL Server, PostgreSQL, MariaDB/MySQL).
    - Infrastructure — Infrastructure management classes.
    - Logging — Log adapter implementations.
    - Notifications — Notification adapter implementations.
    - Plugins — Plugins for utilities such as screenshot capture, email attachments, and Windows progress bar.
    - Shared — Shared constants and cross-cutting classes.
Tests
- Unit Tests — Unit test suite.
- Integration Tests — Integration test suite.
- Tests — Tests in the legacy pattern.
Tools
- Log Monitor — Console application that receives logs published to RabbitMQ.
- Logging & Tracing — Experimental log & tracing library.

Architecture

Stack

Containers

Diagrams

SVG diagrams of the modules, the runtime and every operation flow. They are kept in docs/diagrams. Click a diagram to open it at full size.

Modules and runtime

Solution modules

The 26 projects grouped by layer, with each project’s ProjectReferences.

Runtime architecture

Processes, triggers, external systems and infrastructure.

Operation execution pipeline

What IntegracaoService.exe does from process start to exit when it runs an operation.

Operations catalog

Every value of the Operation enum, with its [OperationEntryPoint] method, data source and destination.

ForIntegration web API

Callers, controllers and the data each controller reads or writes.

Operation flows

Catalog, price and stock export (Sankhya → VTEX)

ExportCatalog, UpdateCatalogPrice and UpdateCatalogInventory.

Order import (VTEX → Sankhya)

ImportOrders, including the error and manual-fix loop.

Order lifecycle after import

UpdateOrders, CancelOrders and the delivery notification.

Shipment tracking: data collection

ShipmentsTracking: the handlers that collect data from Correios, Mandaê, PostalNet and AVJ/CGE.

Shipment tracking: status dispatch and customer service

How tracking statuses become VTEX notifications, seller messages and WMW Vendas tickets.

Order flow monitoring

ProcessOrdersFlows and the order-control flow register.

Data, platform and maintenance operations

Geolocation, Elasticsearch indexing, marketplace errors, Lista de Compras, Vitrine do Artesanato Digital, NF-e correction and stock correction.

Platform flows

Self-update

The VersionManager version check and the IntegracaoService.Updater installer.

Logging, telemetry and health monitoring

Log providers, the RabbitMQ log monitor, run history and the Node.js scheduler’s health checks.

CI/CD

The GitHub Actions build, package and release pipelines.

Development

To carry out application development, troubleshooting, or maintenance, the following tools are required:

IDE

Microsoft Visual Studio 2022 or JetBrains Rider

SDKs

.NET Framework SDK 4.8
.NET Standard SDK 2.0 and 2.1
.NET SDK 8

Tooling

Git client
NuGet client
GitVersion — automatic semantic versioning from Git history
Docker (optional, but recommended)

Versioning

Versions are derived automatically via GitVersion using the GitHubFlow/v1 workflow in ContinuousDeployment mode. The version is computed from Git tags and branch names — no manual Version.txt files are needed. To create a new release, push a tag like v9.3.0 to main.

Infrastructure

Available over the network, via docker-compose, or installed locally:

Service	Purpose
Elastic Search	Data indexing and report extraction
Microsoft SQL Server	Primary relational database
Microsoft SQL Server Management Studio	Database management UI
RabbitMQ	Async messaging between services
Redis	Cache and distributed state

Contributing

Issues and pull requests are tracked on GitHub.

To report a bug or request a feature, open an issue.
Pull requests should target the main branch and pass the CI pipeline before review.
The CI pipeline runs on GitHub Actions: build, static analysis (SonarCloud), packaging, and release.

Developed by Guilherme Branco Stracini for Editora Inovação.

Integração Service