omie-mcp

MCP-сервер (Model Context Protocol) для интеграции Claude с API Omie.

Позволяет Claude запрашивать и выполнять операции в ERP Omie через MCP-инструменты. В этой v1 основное внимание уделяется модулю Производственный цех (производственные заказы, структура продуктов, склад и закупка сырья) с универсальным инструментом, который уже покрывает все остальные модули Omie (Общие, CRM, Финансы, Продажи/NF-e, Услуги/NFS-e, Панель бухгалтера).

Настройка

1. Установите зависимости:

   pnpm install

   Менеджер пакетов этого репозитория — pnpm (workspace). Не запускайте npm install или npm run в корне. Единственное намеренное исключение — запуск npm test / npm run build из каталога packages/omie-data.

   devDependency vite в корне не используется ни одним кодом — она существует только для фиксации разрешения peer-зависимости vitest. Без неё pnpm разрешал vite@5, несовместимый с vitest@4 (который требует vite ^6 || ^7 || ^8), и весь набор тестов падал при запуске. Не удаляйте её как «осиротевшую зависимость» — ни один тест не поймает это удаление.

2. Скопируйте .env.example в .env и заполните App Key и App Secret Omie (полученные на https://developer.omie.com.br/my-apps/):

   cp .env.example .env

3. Скомпилируйте:

   pnpm run build

4. Зарегистрируйте сервер в вашем MCP-клиенте (например, Claude Desktop / Claude Code), указав dist/index.js, с переменными окружения OMIE_APP_KEY и OMIE_APP_SECRET.

   Пример конфигурации (claude_desktop_config.json или эквивалент):

   {
     "mcpServers": {
       "omie": {
         "command": "node",
         "args": ["/caminho/completo/para/omie-mcp/dist/index.js"],
         "env": {
           "OMIE_APP_KEY": "sua_app_key",
           "OMIE_APP_SECRET": "seu_app_secret"
         }
       }
     }
   }

Локальный HTTP API (необязательно, для использования из собственного фронтенда/бэкенда)

Помимо MCP-сервера (stdio, для Claude), существует второй транспорт — src/httpServer.ts — который предоставляет те же инструменты (allTools + handleToolCall, тот же реестр MCP) в виде простого REST API для тех, кто хочет создать фронтенд или другой бэкенд, использующий эту логику без протокола MCP.

Требуется API-ключ: сгенерируйте его с помощью pnpm run gerar-api-key, поместите в HTTP_API_KEY в .env — без него сервер откажется запускаться. Каждый маршрут требует заголовок Authorization: Bearer <HTTP_API_KEY> (без него возвращается 401). Пока слушает только на 127.0.0.1; API-ключа достаточно на этом этапе (локальный, однопользовательский) — но его недостаточно, если это когда-нибудь будет открыто наружу.

Два дополнительных уровня защиты:

• Ограничение частоты запросов — не более 120 запросов в минуту (фиксированное окно); сверх этого отвечает 429.

• Подтверждение деструктивных операций — инструменты, которые добавляют, изменяют или удаляют данные в Omie (omie_op_incluir/alterar/excluir, omie_estoque_ajuste_incluir, omie_requisicao_compra_incluir, omie_pedido_compra_incluir и любые вызовы через omie_chamar_api, чей call начинается с Incluir/Alterar/Excluir/Cancelar/Deletar), требуют "confirmar": true в полезной нагрузке, иначе отвечают 400 — предотвращает случайные деструктивные вызовы (баговый скрипт, цикл и т. д.).

pnpm run gerar-api-key  # gera a chave e mostra a linha pra colar no .env
pnpm run dev:http    # desenvolvimento (tsx)
pnpm run start:http  # produção (build + node dist/httpServer.js)

• GET /tools — выводит список всех доступных инструментов (имя + описание). Передайте ?schema (например: /tools?schema), чтобы также получить JSON Schema полезной нагрузки каждого инструмента.

• GET /tools/<nome>/schema — JSON Schema полезной нагрузки ОДНОГО конкретного инструмента (поля, типы, обязательные поля, описание каждого) — полезно для фронтенда, чтобы сформировать правильную форму/полезную нагрузку без угадывания.

• GET /tools/<nome>?campo=valor&outroCampo=valor — вызывает инструмент напрямую через URL (можно тестировать в браузере, без Postman/curl). Каждое значение строки запроса интерпретируется как JSON, когда это возможно (true, 123, "texto"), иначе остаётся строкой.

• POST /tools/<nome> — вызывает инструмент; тело запроса (JSON) — это полезная нагрузка инструмента. Предпочтительно для больших/вложенных полезных нагрузок (например, массивов в codigos_conta_corrente).

Примеры:

# ver o payload esperado por uma ferramenta
curl -H "Authorization: Bearer $HTTP_API_KEY" http://127.0.0.1:3939/tools/omie_fluxo_caixa_gerar/schema

# chamar direto pela URL (também funciona colado na barra do navegador)
curl -H "Authorization: Bearer $HTTP_API_KEY" "http://127.0.0.1:3939/tools/omie_familias_listar?pagina=1&registros_por_pagina=5"

# chamar via POST (corpo JSON)
curl -H "Authorization: Bearer $HTTP_API_KEY" -X POST http://127.0.0.1:3939/tools/omie_fluxo_caixa_gerar \
  -H "Content-Type: application/json" \
  -d '{"data_inicio":"01/07/2026","data_fim":"31/07/2026","agrupamento":"dia"}'

⚠️ Только для локального использования. Слушает на 127.0.0.1 (не принимает подключения извне машины), без аутентификации, без проверки источника. Не открывайте этот порт за пределы машины/локальной сети до добавления аутентификации — то же предупреждение о безопасности, что и о превращении omie-mcp в удалённый коннектор (см. раздел о безопасности). Замысел такой: использовать локально сейчас для разработки, а переносить на по-настоящему открытый сервис только после реализации минимальной безопасности (аутентификация, валидация входных данных).

Архитектура

Существует два формата модулей, выбираемых по необходимости:

• Passthrough (плоский) — src/tools/<modulo>.ts, массив ToolDef, который сопоставляет 1:1 с resource+call Omie, без собственной логики. Используйте, когда Omie уже возвращает данные в том виде, который нужен пользователю (в большинстве случаев).

• Многослойный модуль — src/modules/<modulo>/, с application/use-cases, infrastructure/gateways и presentation/mcp. Используйте, когда API Omie не отдаёт данные в готовом виде — например, в estoque нет «общего остатка продукта», только позиция по складу (с постраничной навигацией); use-case получает всё и суммирует. В этом случае бизнес-логика (пагинация, фильтрация, агрегация) не может жить внутри OmieClient (который является общим) или в определении инструмента (которое является лишь метаданными MCP).

В обоих форматах ToolDef (src/tools/types.ts) — это общий контракт: PassthroughToolDef (resource/call) или UseCaseToolDef (пользовательский execute). src/tools/registry.ts объединяет все модули в единый массив (allTools) и решает, каким путём следовать; src/index.ts только перебирает этот массив и регистрирует каждый инструмент на MCP-сервере — добавление нового модуля не требует изменения index.ts, достаточно создать модуль и импортировать его в реестр.

src/
  omieClient.ts             # cliente HTTP genérico (auth, retries, throttle) — nunca tem regra de negócio
  index.ts                   # bootstrap do servidor MCP (stdio), registra allTools + genérica
  httpServer.ts               # bootstrap do servidor HTTP (local, opcional) — mesmo allTools + genérica
  tools/
    types.ts                 # ToolDef (Passthrough | UseCase), helper defineTool()
    registry.ts               # agrega os módulos e expõe handleToolCall()
    generic.ts                 # ferramenta omie_chamar_api (fallback p/ qualquer endpoint)
    compras.ts                  # passthrough: Requisição e pedido de compra
  modules/
    ordemProducao/                 # módulo em camadas (cruza com produtos/)
      application/
        use-cases/                    # ex: listar OPs já com descrição do produto
        dto/
      infrastructure/
        gateways/
      presentation/
        mcp/
      ordemProducao-register.ts
      index.ts
    estoque/                       # módulo em camadas (tem lógica própria)
      application/
        use-cases/                    # regra de negócio (ex: somar estoque entre locais)
        dto/                            # schemas zod + tipos de entrada/saída do use-case
      infrastructure/
        gateways/                        # isola as chamadas Omie específicas do módulo
      presentation/
        mcp/                              # definição das ToolDefs expostas via MCP
      estoque-register.ts                  # agrega as tools do módulo
      index.ts                              # barrel export
    produtos/                      # módulo em camadas (mesma estrutura, cruza com estoque/)
      application/
        use-cases/                    # ex: listar produtos com quantidade/valor em estoque
        dto/
      infrastructure/
        gateways/
      presentation/
        mcp/
      produtos-register.ts
      index.ts
    pedidoVenda/                   # módulo em camadas
      application/
        use-cases/                    # ex: produtos que precisam ser separados p/ despacho
        dto/
      infrastructure/
        gateways/
      presentation/
        mcp/
      pedidoVenda-register.ts
      index.ts
    clientesFornecedores/           # módulo em camadas (gateway reutilizável por outros módulos)
      infrastructure/
        gateways/
      presentation/
        mcp/
      clientesFornecedores-register.ts
      index.ts
    contasCorrentes/                # módulo em camadas (gateway reutilizável, mesmo padrão de clientesFornecedores)
      infrastructure/
        gateways/
      presentation/
        mcp/
      contasCorrentes-register.ts
      index.ts
    fluxoCaixa/                     # módulo em camadas (cruza com contasCorrentes/)
      application/
        use-cases/                    # agrega lançamentos em fluxo de caixa por dia/mês/conta
        dto/
      infrastructure/
        gateways/
      presentation/
        mcp/
      fluxoCaixa-register.ts
      index.ts
    contasPagar/                    # módulo em camadas (resolve nome do fornecedor via clientesFornecedores)
      application/
        use-cases/
        dto/
      infrastructure/
        gateways/
      presentation/
        mcp/
      contasPagar-register.ts
      index.ts
    contasReceber/                  # módulo em camadas (resolve nome do cliente via clientesFornecedores)
      application/
        use-cases/
        dto/
      infrastructure/
        gateways/
      presentation/
        mcp/
      contasReceber-register.ts
      index.ts

Многослойные модули могут зависеть от шлюза другого модуля, когда отчёт пересекает два домена (например, produtos использует EstoqueOmieGateway из estoque для расчёта стоимости запасов по продукту; ordemProducao использует ProdutosOmieGateway из produtos для разрешения описаний ПЗ) — это явная зависимость между модулями, а не дублирование кода доступа к Omie.

Доступные инструменты

Полная техническая справка (название каждого инструмента, параметры по одному, какие из них деструктивные, и общие ограничения): docs/FERRAMENTAS.md, генерируется автоматически из кода с помощью pnpm run doc-ferramentas. Разделы ниже сосредоточены на бизнес- контексте и выводах каждого модуля (почему); сгенерированный — на том, что (схема).

Навык Claude Code (.claude/skills/omie-skill/): та же техническая справка, но разбитая на кэш по модулям (cache/*.md + cache/_index.md), чтобы Claude обращался только к нужному модулю, а не ко всему FERRAMENTAS.md целиком — экономит токены контекста при использовании инструментов omie_*. Кэш создаётся командой (pnpm run skill-cache или /omie-skill:atualizar-cache в чате), не автоматически; подробности см. в .claude/skills/omie-skill/SKILL.md и в .claude/commands/omie-skill/ для терминальных команд (/omie-skill:guia, /omie-skill:atualizar-cache, /omie-skill:verificar-cache). Также есть команды, которые вызывают реальный API и возвращают уже отформатированный результат (не сырой JSON) для некоторых модулей: /omie-skill:estoque, /omie-skill:produtos, /omie-skill:op, /omie-skill:estrutura, /omie-skill:pedidos.

Универсальный фильтр (filtros): несколько инструментов «обогащённого» списка (которые уже разрешают имена клиентов/продуктов и т. д.) принимают необязательный параметр filtros: список критериев { campo, operador, valor }, применяемый к ЛЮБОМУ полю результата, даже к тем, которые Omie изначально не фильтрует (src/shared/filtro.ts). Операторы: igual, diferente, contem (игнорирует регистр/диакритику), maior_que, menor_que, entre (valor: [min, max]). Поддерживаются вложенные поля через dot-path (например, cliente.razaoSocial). Все критерии должны совпадать (И). Дополняет, а не заменяет собственные фильтры каждой конечной точки (семейство, этап, дата и т. д.), которые по-прежнему предпочтительны, когда существуют, — они выполняются на сервере Omie, без необходимости перелистывать всё перед фильтрацией.

Производственный заказ (src/modules/ordemProducao/)

• omie_op_incluir / omie_op_alterar / omie_op_excluir / omie_op_consultar — use-case (первые 3 деструктивные), CRUD поверх IOrdemProducaoGateway, тестируется через OpFakeGateway без обращения к реальной Omie. Внимание: проверено вживую (полный цикл с одноразовым продуктом/сырьём/ структурой), что продукт принимает ПЗ только если уже заполнена структура (спецификация), и что codigo_local_estoque обязателен даже при простом добавлении (0 = склад по умолчанию), несмотря на то, что публичная документация Omie помечает его как необязательный

• omie_op_listar — passthrough, выводит список сырых ПЗ (продукт только как код, этап как сырой код)

• omie_op_listar_com_produto — use-case: выводит список ПЗ с уже разрешёнными описанием/SKU продукта (переиспользует ProdutosOmieGateway из модуля produtos) и полем concluida (true/false, надёжное) в дополнение к сырому etapaCodigo

Этап (cEtapa) ПЗ — это код канбана, настраиваемый для каждого аккаунта (от 3 до 6 фаз, названия задаются самим пользователем в Omie), и у API нет конечной точки для перевода кода в название фазы — поэтому инструменты и не пытаются его интерпретировать, а только предоставляют поле concluida (производное от cConcluida, которому можно доверять) и сырой код для тех, кто уже знает значение этапов в своём аккаунте.

Продукты (src/modules/produtos/)

• omie_produtos_consultar — passthrough, карточка конкретного продукта

• omie_produtos_listar — passthrough, выводит список продуктов (поле quantidade_estoque НЕ надёжно, всегда приходит 0). Принимает filtrar_apenas_familia (код семейства, найден при тестировании WSDL — не документировано на справочной странице) для ограничения семейством продуктов. Также принимает filtrar_apenas_descricao ("%texto%" = содержит, "texto%" = начинается с и т. д.) для поиска по названию без перелистывания всего

• omie_produtos_incluir / omie_produtos_alterar / omie_produtos_excluir — use-case (деструктивные), по тому же шаблону шлюз+интерфейс+фейк+тест, что и остальные методы модуля (IProdutosGateway.incluirProduto/alterarProduto/excluirProduto) — тестируется через ProdutosFakeGateway без обращения к реальной Omie. Внимание: проверено вживую (цикл создать→изменить→удалить), что codigo (SKU) обязателен в IncluirProduto, даже если публичная документация Omie помечает его как необязательный

• omie_familias_listar — passthrough, семейства продуктов

• omie_produtos_listar_com_estoque — use-case: выводит список продуктов с уже рассчитанными количеством и стоимостью запасов (продажа и средняя себестоимость), сопоставляя карточку продукта с позицией склада по всем местам хранения (переиспользует EstoqueOmieGateway из модуля estoque). Также принимает filtrar_apenas_familia — фильтрует по семейству и сразу возвращает рассчитанные запасы одним вызовом

Структура продуктов (src/modules/estrutura/)

• omie_estrutura_listar — сценарий использования: выводит товары, у которых заведена структура (BOM/технологическая карта), уже с названием товара и каждого входящего компонента (Omie возвращает это готовым в ListarEstruturas, ресурс geral/malha — связываться с карточкой товаров не нужно)

• omie_estrutura_buscar_por_produto — сценарий использования: находит структуру товара по названию/описанию (или его фрагменту) либо по коду, не зная заранее внутренний код Omie — например: «какая структура у товара 100kg». Прогоняет весь ListarEstruturas целиком и фильтрует на стороне клиента (у Omie нет текстового поиска в этом endpoint)

• omie_estrutura_incluir / omie_estrutura_alterar / omie_estrutura_excluir — сценарий использования (разрушающие), CRUD позиций структуры (IEstruturaGateway.incluirItensEstrutura/alteraItensEstrutura/excluirItemEstrutura), который можно тестировать через EstruturaFakeGateway без обращения к реальной Omie. Внимание: проверено вживую (round-trip включить → изменить → удалить на временном одноразовом товаре), что родительский товар должен быть типа '03 - Produto em Processo" ou '04 - Produto Acabado (принято), что intMalha обязательно в IncluirEstrutura (публичная документация помечает его как опциональный) и что AlterarEstrutura/ExcluirEstrutura требуют idProdMalha вместе с idMalha.

Склад (src/modules/estoque/)

• omie_estoque_ajuste_incluir / omie_estoque_ajuste_excluir — сценарий использования (разрушающие), CRUD корректировки через IEstruturaGateway.incluirAjuste/excluirAjuste, тестируется через EstoqueFakeGateway без обращения к реальной Omie. Внимание, важная находка при живом тесте: поле motivo принимает только 'INI'/'INV'/'OPE'/'PDV' (не описано в публичной документации, появляется только в ошибке валидации Omie); и после ЛЮБОЙ корректировки остатков по товару этот товар уже никогда нельзя удалить — в Omie остаётся постоянное «Movimento de Estoque (calculado)», связанное с ним, даже если сама корректировка потом удалена.

• omie_estoque_movimentos_listar — транзитный вызов, список движений за период

• omie_estoque_total_produto — сценарий использования: суммирует физический остаток товара по всем складам, поскольку Omie отдаёт доступ только по конкретному месту

omie_estoque_consultar (ConsultarEstoque) удалена: мы её протестировали, и такого метода не существует в актуальном API Omie (возвращает Method "ConsultarEstoque" not exists).

Заказ на продажу (src/modules/pedidoVenda/)

• omie_pedido_venda_consultar / omie_pedido_venda_incluir / omie_pedido_venda_alterar / omie_pedido_venda_excluir — сценарий использования (последние три — разрушающие), CRUD над IPedidoVendaGateway, тестируется через PedidoVendaFakeGateway без обращения к реальной Omie. Внимание: проверено вживую (полный round-trip с одноразовым клиентом и товаром) — у клиента в карточке должен быть заполнен штат UF, иначе Omie отклонит заказ, а codigo_categoria/codigo_conta_corrente, обязательные даже в простом заказе.

• omie_pedido_venda_listar — транзитный вызов, список заказов (принимает встроенный фильтр Omie etapa)

• omie_pedido_venda_etapas_listar — транзитный вызов, каталог этапов выставления (канбан продаж/обслуживания/закупок) с кодом и описанием — в отличие от этапа OP, здесь этап фиксирован и документирован

• omie_pedido_venda_produtos_para_separar — сценарий использования: список товаров, которые нужно отделить со склада для отправки (заказы на запрошенной этапе «Separar Estoque», обычно код 20), при этом отменённые уже исключаются и возвращается сводка, сгруппированная по товару (общее количество, в каком количестве заказов)

• omie_pedido_venda_listar_com_cliente — сценарий использования: список заказов уже с именем клиента (переиспользует ClientesOmieGateway из модуля clientesFornecedores), этапом по полному наименованию и позициями заказа (товар/SKU/описание/количество/единица) в виде логического статуса cancelado/faturado и общей суммой заказа. Необязательный фильтр etapa_codigo (без него возвращаются все этапы — не отфильтрованы отменёнными по умолчанию, в отличие от инструмента выше)

• omie_pedido_separar_estoque_listar — сценарий использования: короткий доступ к самому просматриваемому отчёту на текущий момент — в том же формате, что и ome_pedido_venda_listar_com_cliente, но с фиксированным etapa_codigo «Separar Stock» и отменёнными по умолчанию исключёнными (параметр incluir_cancelados просматривает также отменённые). Внутри использует ListarPedidosComClienteUseCase.

Важная находка при тестировании: отменённые заказы не сбрасывают etapa в Omie — отменённая заявка продолжает отображаться как «Separar-заказ», если была отменена на этой фазе. Поэтому omie_pedido_venda_produtos_para_separar всегда сверяет infoCadastro.cancelado, перед тем как считать заказ действительно отменённым; omie_pedido_venda_listar_com_cliente же — это общая выборка, которая просто отображает cancelado, чтобы вызывающий решил, что делать с этим дальше.

Клиенты и поставщики (src/modules/clientesFornecedores/)

В Omie клиент и поставщик — это ОДНА карточка (geral/clientes), различаются только по tag (Cliente, Fornecedor, Colaborador, Sócios, и их может быть несколько) — отдельного эндпоинта geral/fornecedores нет.

• omiae_clientes_consultar — транзитный вызов, один клиент/поставщик (юр. название, фантазийное название, CNPJ/CPF, контакт, адрес, теги)

• omiae_clientes_listar — транзитный вызов, список клиентов/поставщиков; есть расширенный фильтр через clientesFiltro (например, {"tags": [{"tag": "Fornecedor"}]})

• omiae_fornecedores_listar — облегчённый сценарий: ярлык к omiae_clientes_listar, уже отдельный фильтр по тегу Fornecedor, с поиском по юр./фантазийному имени/CNPJ-CPF и apenas_ativos (удаляет неактивных на клиенте, потому что clientesFiltro.tags не сочетается с фильтром по статусу в одном вызове напрямую)

• omiae_clientes_incluir / omiae_clientes_alterar / omiae_clientes_excluir — сценарий (разрушающие), CRUD через IClientesGateway.incluirCliente/alterarCliente/excluirCliente, тестируется через ClientesFakeGateway без реальной Omie. Внимание: проверено живьём (round-trip создать→изменить→удалить) — обязательность codigo_cliente_integracao в IncluirCliente даже при указании опционального в публичной документации

Текущий охват: только чтение (консультация/список). По запросу пользователя полный CRUD (включение, изменение, удаление) остаётся на потом — после того как у MCP появится минимальная защита (см. раздел про квоты/безопасность и src/httpServer.ts).

Текущие счета (src/modules/contasCorrentes/)

• om_contas_correntes_listar — транзитный вызов, список текущих счетов (банки, кассы, карты, эквайринговые терминалы) с кодом, описанием, банком, типом и начальным зарегистрированным остатком

• om_extrato_conta_corrente_consultar — сценарий использования: выписка по текущему счёту за указанный период (операции с датой/описанием/суммой/категорией/состоянием сверки и остатками: предыдущий/текущий/инн/конко/доступный). Метод Omie: ListarExtrato (ресурс financas/extrato), тестируется через ContasCorrentesFakeGateway без обращения к реальной Omie. Принимает общий параметр filtros по операциям (например, замысел, категория). Проверено вживую на реальном счёте.

Денежный поток (src/modules/fluxoCaixa/)

• omie_fluxo_caixa_gerar — сценарий использования: собирает денежный поток (поступления, оттоки, остаток за период и накопленным) в табличном виде, группируя по дням или месяцам и по счёту. Готового отчёта в Omie нет — только financas/mf ListarMovimentos: проводка за проводкой по счетам к оплате/к получению, постранично по 100 записей — поэтому этот инструмент тянет все операции периода, разделяет выполненные (уже поступления/выплаты, по дате платежа) и планируемые (в работе/не погашённые, по дате срока, с исключением отменённых), и агрегирует всё, подставляя имя связанного счёта (из ContasCorrentesOmGateway модуля contasCorrentes). Формат подобран так, чтобы его можно было потом выгружать в таблицу. По умолчанию (apenas_favoritas: true) ограничивается избранными счетами пользователя (src/modules/fluxoCaixa/application/contas-favoritas.ts: Cartão NuBank, Stone, Banco do Brasil, Wix, iFood, Sicoob, Itaú, Cartão Elo LEANDRO, Amazon, CAIXA LOJAS — остальные ~39 счетов, заведённых в Omie, например старые карты и отдельные эквайры, остаются в стороне); используйте apenas_favoritas: false, чтобы увидеть все счета, или codigos_conta_corrente для своего списка.

Реальный остаток (опция, usar_saldo_real: true): по silent default накопленный остаток — это только сумма изменения за период, указанный в запросе, а не фактический банковский остаток — Salário через API исторического дневного остатка по каждому счёту Omie не отдаёт. При usar_saldo_real: true инструмент привязывает расчёт к saldo_inicial/saldo_data, указанным по каждому счёту (через omie_contas_correntes_listar): суммирует операции, проведённые между saldo_data и началом периода, и даёт saldoRealAcumulado, близкое к фактическому банковскому остатку, — это не жёстокосвязанное значение в MCP, оно считывается из карточки Omа, поэтому когда кто-то там введёт реальный остаток по счёту (например, 01/01), расчёт уже автоматически станет учитывать это без изменений в коде. Если счёт без заданных saldo_data/saldo_inicial (или saldo_data позже начала периода), выдаёт saldoRealAcumulado: null вместо «изобретённого» числа. За этим расчётом добавляется нулевое учреждение (операции между самой ранней saldo_data среди счетов и началом периода) — может быть медленно, если saldo_data в далёком прошлом.

Важная находка при тестировании: Omie отклоняет два параллельных вызова одного и того же метода (ошибка "Já existe uma requisição desse método em execução"), даже если параметры разные — поэтому проходы сделанных и планируемых (оба используют ListarMovimentos) в сценарий внутри выполняются последовательно, а не параллельно. Это дополнительное ограничение помимо rate limit в следующем разделе, специально для параллельных вызовов одного call.

Длинные периоды дают очень много страниц (например, только поступления за ~3 недели уже превысили 3.700 записей) — предпочтительнее периоды до ~3 месяцев за вызов.

Счета к оплате (src/modules/contasPagar/)

• omie_contas_pagar_listar — сценарий использования: список записей из financas/contapagar (ListarContasPagar) уже с подстановкой имени поставщика (используется модуль clientesFornecedores — ClientesOmieGateway, так как Omie возвращает только код), суммой, датой уплаты, состоянием (PAGO/ABERTO/VENCIDO по счёту), фискальным полем, категорией и комментарием. Паджин, необязательный фильтр data_fluxo_de/data_fluxo_ate.

Счета к получению (src/modules/contasReceber/)

• omie_contas_receber_listar — use-case: список записей из financas/contareceber (ListarContasReceber) уже с разрешённым именем клиента (переиспользует ClientesOmieGateway из модуля clientesFornecedores), сумма, дата погашения, статус (PAGO/ABERTO/VENCIDO), фискальный документ, номер заказа и категория. С пагинацией, с необязательным фильтром data_alteracao_de/data_alteracao_ate.

• omie_contas_receber_boleto_gerar / omie_contas_receber_boleto_obter / omie_contas_receber_boleto_prorrogar / omie_contas_receber_boleto_cancelar — use-case (генерация/пролонгация/отмена деструктивные), CRUD банковского билета по счёту к получению (financas/contareceberboleto: GerarBoleto/ObterBoleto/ProrrogarBoleto/CancelarBoleto), тестируемый через ContasReceberFakeGateway без обращения к реальной Omie. Внимание: проверено вживую, что этот аккаунт Omie не имеет настроенного банковского соглашения/билета — ProrrogarBoleto возвращает "Não temos suporte para geração da remessa de pagamento para o banco -sem instituição-"; GerarBoleto вероятно завершится ошибкой по той же причине (не тестировалось вживую, чтобы не создавать реальный билет по счёту клиента из продакшена). ObterBoleto/CancelarBoleto были проверены вживую (безопасно возвращают "nenhum boleto gerado", без побочных эффектов).

Важная находка при тестировании: параметр фильтра по дате Omie в этих двух конечных точках (filtrar_por_data_de/filtrar_por_data_ate) фильтрует по дате последнего изменения записи (info.dAlt), а не по дате погашения — подтверждено запросом диапазона в 1 день и сравнением с data_vencimento возвращённых записей (разные даты погашения, dAlt всегда в пределах запрошенного диапазона). Поэтому инструменты MCP выставляют параметр как data_alteracao_de/data_alteracao_ate (не data_vencimento_de/ate), чтобы не предполагать поведение, которого нет в API. Не существует (проверено) нативного фильтра по дате погашения в этих двух конечных точках — для этого используйте `omie_fluxo_ca

• omie_servico_incluir / omie_servico_alterar / omie_servico_excluir / omie_servico_consultar / omie_servico_listar — use-case (первые 3 деструктивные), CRUD кадастра услуг (servicos/servico), тестируемый через ServicoFakeGateway без обращения к реальной Omie. Внимание, находка при живом тестировании: AlterarCadastroServico требует код, вложенный в intEditar, а не в cabecalho, как казалось бы естественным — в публичной документации это не отражено.

• omie_os_incluir / omie_os_alterar / omie_os_excluir / omie_os_consultar / omie_os_listar — use-case (первые 3 деструктивные), CRUD заказа на услуги (servicos/os), тестируемый через OrdemServicoFakeGateway без обращения к реальной Omie. Внимание, важные находки при живом тестировании: (1) каждый элемент требует codigo_servico_municipal/codigo_servico_lc116 — код, уже зарегистрированный в таблице LC116 (см. omie_servicos_lc116_listar), а не произвольный текст — иначе Omie отклоняет запрос с сообщением «Código da LC116 não cadastrada»; (2) cRetemISS обязателен в каждом элементе, даже если он не помечен как обязательный в публичной документации; (3) у клиента в шапке должно быть заполнено поле UF (то же требование, что и в заказе на продажу). Проверено при живом тестировании с полным безопасным циклом создания и удаления (использовался одноразовый тестовый клиент, созданный и удалённый без следов).

• omie_os_listar — use-case: список NFS-e (счёт-фактура на услуги; servicos/nfse, ListarNFSEs), тестируемый через NfseFakeGateway. ТОЛЬКО ЧТЕНИЕ — то же правило, что и для модуля NF-e по товарам (налоговый документ, имеющий юридическую силу; безопасная выписка невозможна).

• omie_servicos_lc116_listar — use-case: возвращает 255 допустимых кодов Дополнительного закона 116 (классификация услуг), используется для определения правильного кода перед созданием заказа на услуги. Метод Omie: ListarLC116 (ресурс servicos/lc116).

Вне рамок этого цикла (не запрошено, низкий приоритет): периодический контракт на услуги (servicos/contrato) и пакетное выставление счетов по ОУ/контракту (servicos/osp, servicos/oslote, servicos/contratofat, servicos/contratolote) — реализовать только когда понадобится пользователю.

Закупки (src/modules/compras)

• omie_pedido_compra_incluir / omie_pedido_compra_alterar / omie_pedido_compra_excluir / omie_pedido_compra_consultar / omie_pedido_compra_listar — use-case (первые 3 деструктивные), полный CRUD через IPedidoCompraGateway (produtos/pedidocompra), тестируемый через PedidoCompraFakeGateway без обращения к реальной Omie. Внимание, важные находки при живом тестировании: (1) nCodConta (передаётся как codigo_conta_corrente) требует код расчётного счёта (geral/contacorrente), а не департамента/подразделения, несмотря на название — Omie отклоняет с ошибкой «Conta corrente não cadastrada», если использовать не то; (2) PesquisarPedidoCompra по умолчанию скрывает ВСЕ заказы — нужно явно запрашивать каждый статус (lExibirPedidosPendentes/Faturados/Recebidos/Cancelados/RecParciais/ FatParciais, все 'S'), что gateway уже делает всегда; (3) когда на странице нет записей, Omie возвращает ошибку (SOAP-ENV:Client-5113) вместо пустого списка — в gateway это нормализовано, возвращается пустой список.

• omie_requisicao_compra_incluir / omie_requisicao_compra_alterar / omie_requisicao_compra_excluir / omie_requisicao_compra_consultar / omie_requisicao_compra_listar — use-case (первые 3 деструктивные), полный CRUD через IRequisicaoCompraGateway (produtos/requisicaocompra), тестируемый через RequisicaoCompraFakeGateway без обращения к реальной Omie. Внимание, находка при живом тестировании: в отличие от других эндпоинтов, поля IncluirReq/AlterarReq передаются в корне запроса, а не внутри обёртки requisicaoCadastro: {...}, как указано в публичной документации (Omie отклоняет запрос с XML, если использовать обёртку из документации). Проверено при живом тестировании.

Generic (src/tools/generic.ts)

• omie_chamar_api — принимает resource (путь конечной точки) и action (метод), позволяя вызывать любой ресурс и метод Omie без изменения кода. ATTENTION: ответ может быть строкой (не JSON) для операций без возвращаемого значения; OmieClient возвращает в этом случае { success: true }.

Диагностика (src/tools/diagnostics.ts)

• omie_diagnostics_estado — внутренний инструмент: возвращает сводку по заданным client_id/client_secret без вызова Omie: список избранного (можно листовым обходом через navegar получить 13/todo), максимальный HTTP-размер тела запроса и сведения о зарегистрированных инструментах. Полезен, чтобы понять, почему конечная точка не работает, — проблемы обычно связаны с отсутствием доступа к API или неправильными настройками приложения.

Примечание: модуль услуг имеет право на существование рядом с модулем «Товары» (produtos/), потому что в Omie это независимые модули с независимой аутентификацией (app key/secret), и распространённая конфигурация интеграции включает в себя «Товары/услуги» вместе. Стоимость поддержки минимальна (несколько файлов), и он закрывает интеграцию без необходимости двух разных MCP-серверов.

Общие услуги (servicos/)

Подробности в секции выше. Вкратце: локальная таблица 255 кодов LC116 (только чтение, кэшируется, без вызовов Omie) для валидации codigo_servico_municipal/codigo_servico_lc116; внесение услуг основано на LC116; заказ на услуги (OS) всегда требует codigo_servico_municipal/codigo_servico_lc116 как действительный код LC116 (не свободный текст), а также cRetemISS, клиента с заполненным UF. Проверено на живом аккаунте путём цикла создания-изменения-запроса-удаления.