omie-mcp

Servidor MCP (Model Context Protocol) para la integración de Claude con la API de Omie.

Permite que Claude consulte y ejecute operaciones en el ERP Omie mediante herramientas MCP. En esta v1, el foco es el módulo Planta de Producción (Órdenes de Producción, Estructura de Productos, Inventario y Compras de insumos), con una herramienta genérica que ya cubre todos los demás módulos de Omie (General, CRM, Finanzas, Ventas/NF-e, Servicios/NFS-e, Panel del Contador).

Configuración

1. Instale las dependencias:

   pnpm install

   El gestor de este repositorio es pnpm (workspace). No ejecutes npm install ni npm run en la raíz. La única excepción intencional es ejecutar npm test / npm run build desde dentro de packages/omie-data.

   La devDependency vite de la raíz no la usa ningún código: existe solo para fijar la resolución de la peer dependency de vitest. Sin ella, pnpm resolvía vite@5, incompatible con vitest@4 (que exige vite ^6 || ^7 || ^8), y toda la suite fallaba al iniciar. No la elimines como "dependencia huérfana" — ningún test detecta esa eliminación.

2. Copia .env.example a .env y complétalo con tu App Key y App Secret de Omie (obtenidos en https://developer.omie.com.br/my-apps/):

   cp .env.example .env

3. Compila:

   pnpm run build

4. Registra el servidor en tu cliente MCP (p. ej., Claude Desktop / Claude Code), apuntando a dist/index.js, con las variables de entorno OMIE_APP_KEY y OMIE_APP_SECRET.

   Ejemplo de configuración (claude_desktop_config.json o equivalente):

   {
     "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"
         }
       }
     }
   }

API HTTP local (opcional, para consumir desde un frontend/backend propio)

Además del servidor MCP (stdio, para Claude), existe un segundo transporte — src/httpServer.ts — que expone las mismas herramientas (allTools + handleToolCall, el mismo registry del MCP) como una API REST sencilla, para quien quiera montar un frontend u otro backend que consuma esa lógica sin hablar el protocolo MCP.

Exige una API key: genérala con pnpm run gerar-api-key, colócala en HTTP_API_KEY en el .env — el servidor se niega a arrancar sin ella. Toda ruta exige la cabecera Authorization: Bearer <HTTP_API_KEY> (devuelve 401 sin ella). Además, solo escucha en 127.0.0.1; la API key es el mínimo para esta etapa (local, de un solo usuario) — no es suficiente por sí sola si esto se expone al exterior algún día.

Dos capas extra de protección:

• Rate limit — como máximo 120 peticiones por minuto (ventana fija); por encima de eso responde 429.

• Confirmación en operaciones destructivas — las herramientas que incluyen, modifican o eliminan datos en Omie (omie_op_incluir/alterar/excluir, omie_estoque_ajuste_incluir, omie_requisicao_compra_incluir, omie_pedido_compra_incluir, y cualquier llamada mediante omie_chamar_api cuyo call empiece por Incluir/Alterar/Excluir/Cancelar/Deletar) exigen "confirmar": true en el payload; de lo contrario responden 400 — evita una llamada destructiva accidental (script con errores, bucle, etc.).

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 — lista todas las herramientas disponibles (nombre + descripción). Pasa ?schema (p. ej., /tools?schema) para que ya venga con el JSON Schema del payload de cada una.

• GET /tools/<nome>/schema — JSON Schema del payload de UNA herramienta específica (campos, tipos, cuáles son obligatorios, descripción de cada uno) — útil para que un frontend monte el formulario/payload correcto sin adivinar.

• GET /tools/<nome>?campo=valor&outroCampo=valor — llama a la herramienta directamente por URL (se puede probar en el navegador, sin Postman/curl). Cada valor del query string se interpreta como JSON cuando es posible (true, 123, "texto"); de lo contrario, se queda como string.

• POST /tools/<nome> — llama a la herramienta; el cuerpo de la petición (JSON) es el payload de la herramienta. Preferible para payloads grandes/anidados (p. ej., arrays en codigos_conta_corrente).

Ejemplos:

# 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"}'

⚠️ Solo para uso local. Escucha en 127.0.0.1 (no acepta conexiones desde fuera de la máquina), sin autenticación, sin validación de origen. No expongas ese puerto fuera de la máquina/red local antes de añadir autenticación — la misma advertencia de seguridad ya hecha sobre convertir omie-mcp en un Connector remoto (ver sección de seguridad). La intención es: usarlo local ahora para desarrollar contra él, migrar a un servicio realmente expuesto solo después de implementar seguridad mínima (auth, validación de entrada).

Arquitectura

Existen dos formatos de módulo, elegidos según la necesidad:

• Passthrough (plano) — src/tools/<modulo>.ts, un array de ToolDef que mapea 1:1 a un resource+call de Omie, sin lógica propia. Úsalo cuando Omie ya devuelve el dato tal y como lo necesita el usuario (la mayoría de los casos).

• Módulo en capas — src/modules/<modulo>/, con application/use-cases, infrastructure/gateways y presentation/mcp. Úsalo cuando la API de Omie no entrega el dato listo — p. ej., estoque no tiene "stock total del producto", solo posición por ubicación de stock (paginada); el use-case lo busca todo y suma. En ese caso, la regla de negocio (paginación, filtro, agregación) no puede vivir dentro de OmieClient (que es genérico) ni de la definición de la tool (que es solo metadato MCP).

En ambos formatos, el ToolDef (src/tools/types.ts) es el contrato común: PassthroughToolDef (resource/call) o UseCaseToolDef (execute personalizado). src/tools/registry.ts agrega todos los módulos en un único array (allTools) y decide qué camino seguir; src/index.ts solo itera ese array y registra cada herramienta en el servidor MCP — añadir un módulo nuevo no exige modificar index.ts, solo crear el módulo e importarlo en el registry.

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

Los módulos en capas pueden depender del gateway de otro módulo cuando el informe cruza dos dominios (p. ej., produtos usa el EstoqueOmieGateway de estoque para calcular el valor en stock por producto; ordemProducao usa el ProdutosOmieGateway de produtos para resolver la descripción de las OPs) — es una dependencia explícita entre módulos, no duplicación de código de acceso a Omie.

Herramientas disponibles

Referencia técnica completa (nombre de cada herramienta, parámetros uno a uno, cuáles son destructivas y limitaciones generales): docs/FERRAMENTAS.md, generado automáticamente desde el código mediante pnpm run doc-ferramentas. Las secciones siguientes se centran en el contexto de negocio y en los hallazgos de cada módulo (el "porqué"); el generado se centra en el "qué" (schema).

Skill de Claude Code (.claude/skills/omie-skill/): la misma referencia técnica, pero dividida en una caché por módulo (cache/*.md + cache/_index.md) para que Claude consulte solo el módulo relevante en lugar del FERRAMENTAS.md completo — ahorra tokens de contexto al usar las herramientas omie_*. La caché se genera por comando (pnpm run skill-cache, o /omie-skill:atualizar-cache en el chat), no automáticamente; ver .claude/skills/omie-skill/SKILL.md para detalles y .claude/commands/omie-skill/ para los comandos de terminal (/omie-skill:guia, /omie-skill:atualizar-cache, /omie-skill:verificar-cache). También hay comandos que llaman a la API real y devuelven el resultado ya formateado (no JSON crudo) para algunos módulos: /omie-skill:estoque, /omie-skill:produtos, /omie-skill:op, /omie-skill:estrutura, /omie-skill:pedidos.

Filtro genérico (filtros): varias herramientas de listado "enriquecido" (que ya resuelven nombre de cliente/producto, etc.) aceptan un parámetro opcional filtros: lista de criterios { campo, operador, valor } aplicada sobre CUALQUIER campo del resultado, incluso los que Omie no filtra de forma nativa (src/shared/filtro.ts). Operadores: igual, diferente, contem (ignora mayúsculas/acentos), maior_que, menor_que, entre (valor: [min, max]). Soporta campo anidado mediante dot-path (p. ej., cliente.razaoSocial). Todos los criterios deben cumplirse (AND). Complementa, no sustituye, los filtros nativos de cada endpoint (familia, etapa, fecha, etc.), que siguen siendo preferibles cuando existen — se ejecutan en el servidor de Omie, sin necesidad de paginar todo antes de filtrar.

Orden de Producción (src/modules/ordemProducao/)

• omie_op_incluir / omie_op_alterar / omie_op_excluir / omie_op_consultar — use-case (las 3 primeras destructivas), CRUD sobre IOrdemProducaoGateway, testeable mediante OpFakeGateway sin tocar la Omie real. Atención: validado en vivo (round-trip completo con producto/insumo/estructura descartables) que el producto solo acepta OP si ya tiene estructura (BOM) cumplimentada, y que codigo_local_estoque es obligatorio incluso en el alta simple (0 = ubicación por defecto), aunque la doc pública de Omie lo marque como opcional

• omie_op_listar — passthrough, lista OPs crudas (producto solo como código, etapa como código crudo)

• omie_op_listar_com_produto — use-case: lista OPs ya con la descripción/SKU del producto resueltos (reutiliza el ProdutosOmieGateway del módulo produtos) y el campo concluida (true/false, fiable) además del etapaCodigo crudo

La etapa (cEtapa) de una OP es un código de kanban configurable por cuenta (de 3 a 6 fases, nombres definidos por el propio usuario en Omie) y la API no tiene endpoint para traducir el código al nombre de la fase — por eso las herramientas no intentan interpretarlo, solo exponen el campo concluida (derivado de cConcluida, ese sí fiable) y el código crudo para quien ya sepa el significado de las etapas de su propia cuenta.

Productos (src/modules/produtos/)

• omie_produtos_consultar — passthrough, ficha de un producto específico

• omie_produtos_listar — passthrough, lista productos (el campo quantidade_estoque NO es fiable, siempre viene 0). Acepta filtrar_apenas_familia (código de la familia, encontrado probando el WSDL — no documentado en la página de ayuda) para restringir a una familia de productos. También acepta filtrar_apenas_descricao ("%texto%" = contiene, "texto%" = empieza por, etc.) para buscar por nombre sin paginar todo

• omie_produtos_incluir / omie_produtos_alterar / omie_produtos_excluir — use-case (destructivas), siguiendo el mismo patrón gateway+interfaz+fake+test de los demás métodos del módulo (IProdutosGateway.incluirProduto/alterarProduto/excluirProduto) — testeable mediante ProdutosFakeGateway sin tocar la Omie real. Atención: validado en vivo (round-trip crear→modificar→eliminar) que codigo (SKU) es obligatorio en IncluirProduto, aunque la doc pública de Omie lo marque como opcional

• omie_familias_listar — passthrough, familias de productos

• omie_produtos_listar_com_estoque — use-case: lista productos ya con cantidad y valor en stock calculados (venta y coste medio), cruzando la ficha de productos con la posición de stock en todas las ubicaciones (reutiliza el EstoqueOmieGateway del módulo estoque). También acepta filtrar_apenas_familia — filtra por familia y ya viene con el stock calculado en una sola llamada

Estructura de Productos (src/modules/estrutura/)

• omie_estrutura_listar — caso de uso: lista los productos que tienen estructura (BOM/ficha técnica) registrada, ya con el nombre del producto y de cada insumo (Omie lo devuelve listo en ListarEstruturas, recurso geral/malha — no es necesario cruzar con el registro de productos)

• omie_estrutura_buscar_por_produto — caso de uso: encuentra la estructura de un producto por nombre/descripción (o parte de ella) o código, sin necesidad de saber el código interno de Omie de antemano — ej: "cuál es la estructura del producto 100kg". Recorre todo ListarEstruturas y filtra del lado del cliente (Omie no tiene búsqueda por texto en ese endpoint)

• omie_estrutura_incluir / omie_estrutura_alterar / omie_estrutura_excluir — caso de uso (destructivas), CRUD de ítems de la estructura (IEstruturaGateway.incluirItensEstrutura/alterarItensEstrutura/excluirItemEstrutura), testeable vía EstruturaFakeGateway sin tocar la Omie real. Atención: validado en vivo (round-trip incluir→alterar→excluir en un producto de prueba descartable) que el producto padre debe ser tipo '03 - Produto em Processo' o '04 - Produto Acabado', que intMalha es obligatorio en IncluirEstrutura (la doc pública lo marca como opcional) y que AlterarEstrutura/ExcluirEstrutura exigen idProdMalha junto con idMalha.

Estoque (src/modules/estoque/)

• omie_estoque_ajuste_incluir / omie_estoque_ajuste_excluir — caso de uso (destructivas), CRUD de ajuste sobre IEstoqueGateway.incluirAjuste/excluirAjuste, testeable vía EstoqueFakeGateway sin tocar la Omie real. Atención, hallazgo en vivo importante: el campo motivo solo acepta 'INI'/'INV'/'OPE'/'PDV' (no documentado en la doc pública, solo aparece en el error de validación de Omie); y después de CUALQUIER ajuste de stock en un producto, ese producto nunca más puede ser eliminado — Omie mantiene un "Movimiento de Stock (calculado)" permanente vinculado a él, incluso si el ajuste en sí se elimina después.

• omie_estoque_movimentos_listar — passthrough, lista movimientos por período

• omie_estoque_total_produto — caso de uso: suma el stock físico de un producto en todos los locales de stock, ya que Omie solo expone posición por local

omie_estoque_consultar (ConsultarEstoque) fue eliminada: probamos y el método no existe en la API Omie actual (devuelve Method "ConsultarEstoque" not exists).

Pedido de Venta (src/modules/pedidoVenda/)

• omie_pedido_venda_consultar / omie_pedido_venda_incluir / omie_pedido_venda_alterar / omie_pedido_venda_excluir — caso de uso (las 3 últimas destructivas), CRUD sobre IPedidoVendaGateway, testeable vía PedidoVendaFakeGateway sin tocar la Omie real. Atención: validado en vivo (round-trip completo con cliente/producto descartables) que el cliente necesita tener UF rellenada en el registro (si no, Omie rechaza el pedido) y que codigo_categoria/codigo_conta_corrente son obligatorios incluso en un pedido simple

• omie_pedido_venda_listar — passthrough, lista pedidos (acepta filtro etapa nativo de Omie)

• omie_pedido_venda_etapas_listar — passthrough, catálogo de etapas de facturación (kanban de ventas/OS/compras) con código y descripción — a diferencia de la etapa de OP, aquí es fijo y documentado

• omie_pedido_venda_produtos_para_separar — caso de uso: lista los productos que necesitan ser separados del stock para despacho (pedidos en la etapa "Separar Estoque", código 20 por defecto), ya eliminando los cancelados y devolviendo un resumen agregado por producto (cantidad total, en cuántos pedidos)

• omie_pedido_venda_listar_com_cliente — caso de uso: lista pedidos ya con el nombre del cliente (reutiliza el ClientesOmieGateway del módulo clientesFornecedores), la etapa por extenso y los ítems del pedido (producto/SKU/descripción/cantidad/unidad) resueltos, cancelado/faturado como booleano y el valor total del pedido. Filtro etapa_codigo opcional (sin él, trae todas las etapas — no filtra cancelados por defecto, a diferencia de la herramienta anterior)

• omie_pedido_venda_separar_estoque_listar — caso de uso: atajo para el informe más seguido en el día a día — mismo formato que omie_pedido_venda_listar_com_cliente, pero con etapa_codigo fijo en "Separar Estoque" y cancelados eliminados por defecto (parámetro incluir_cancelados para ver también los cancelados). Internamente reutiliza ListarPedidosComClienteUseCase.

Hallazgo importante probando: los pedidos cancelados no tienen la etapa reiniciada por Omie — un pedido cancelado sigue apareciendo como si estuviera en "Separar Estoque" si fue cancelado en esa fase. Por eso omie_pedido_venda_produtos_para_separar siempre cruza con infoCadastro.cancelado antes de considerar un pedido como realmente pendiente; ya omie_pedido_venda_listar_com_cliente es un listado genérico y expone cancelado para que quien lo llame decida qué hacer con eso.

Clientes y Proveedores (src/modules/clientesFornecedores/)

En Omie, cliente y proveedor son el MISMO registro (geral/clientes), diferenciados solo por la tag (Cliente, Fornecedor, Colaborador, Sócios, pudiendo tener más de una) — no existe endpoint geral/fornecedores separado.

• omie_clientes_consultar — passthrough, un cliente/proveedor específico (razón social, nombre fantasia, CNPJ/CPF, contacto, dirección, tags)

• omie_clientes_listar — passthrough, lista clientes/proveedores; acepta filtro avanzado vía clientesFiltro (ej: {"tags": [{"tag": "Fornecedor"}]})

• omie_fornecedores_listar — caso de uso ligero: atajo para omie_clientes_listar ya filtrado por la tag Fornecedor, con búsqueda por razón social/nombre fantasia/CNPJ-CPF y apenas_ativos (elimina inactivos del lado del cliente, ya que el filtro clientesFiltro.tags no se combina con filtro de estado en la misma llamada de forma directa)

• omie_clientes_incluir / omie_clientes_alterar / omie_clientes_excluir — caso de uso (destructivas), CRUD sobre IClientesGateway.incluirCliente/alterarCliente/excluirCliente, testeable vía ClientesFakeGateway sin tocar la Omie real. Atención: validado en vivo (round-trip crear→alterar→excluir) que codigo_cliente_integracao es obligatorio en IncluirCliente, incluso si la doc pública de Omie lo marca como opcional

Alcance actual: solo lectura (consulta/listado). A petición del usuario, el CRUD completo (incluir, alterar, excluir) de clientes/proveedores queda para después — solo después de que el MCP tenga seguridad mínima implementada (ver sección de rate limit/seguridad y src/httpServer.ts).

Cuentas Corrientes (src/modules/contasCorrentes/)

• omie_contas_correntes_listar — passthrough, lista cuentas corrientes (bancos, cajas, tarjetas, terminales de pago) con código, descripción, banco, tipo y saldo inicial registrado

• omie_extrato_conta_corrente_consultar — caso de uso: extracto de una cuenta corriente en un período (movimientos con fecha/descripción/valor/categoría/situación de conciliación, y saldos anterior/actual/conciliado/disponible). Método Omie: ListarExtrato (recurso financas/extrato), testeable vía ContasCorrentesFakeGateway sin tocar la Omie real. Soporta el parámetro genérico filtros sobre los movimientos (ej: naturaleza, categoría). Validado en vivo contra la cuenta real.

Flujo de Caja (src/modules/fluxoCaixa/)

• omie_fluxo_caixa_gerar — caso de uso: arma el flujo de caja (entradas, salidas, saldo del período y acumulado) en un formato tabular, agrupado por día o mes y por cuenta corriente. Omie no tiene ese informe listo — solo financas/mf ListarMovimentos, lanzamiento por lanzamiento de cuentas a pagar/cobrar, paginado a 100/vez — así que esta herramienta busca todos los lanzamientos del período, separa realizado (ya pagado/cobrado, por la fecha de pago) de previsto (en abierto, aún no liquidado, por la fecha de vencimiento, excluyendo cancelados) y agrega todo, resolviendo el nombre de la cuenta corriente (reutiliza ContasCorrentesOmieGateway, del módulo contasCorrentes). Formato pensado para poder exportarse como hoja de cálculo en el futuro. Por defecto (apenas_favoritas: true) restringe a las cuentas favoritas definidas por el usuario (src/modules/fluxoCaixa/application/contas-favoritas.ts: Cartão NuBank, Stone, Banco do Brasil, Wix, iFood, Sicoob, Itaú, Cartão Elo LEANDRO, Amazon, CAIXA LOJA — las ~39 demás cuentas registradas en Omie, ej: tarjetas antiguas y adquirentes específicas, quedan fuera); use apenas_favoritas: false para ver todas las cuentas, o codigos_conta_corrente para una lista personalizada.

Saldo real (opcional, usar_saldo_real: true): por defecto el saldo acumulado es solo la variación neta dentro del período consultado, no el saldo bancario real — Omie no expone historial de saldo diario por cuenta vía API. Con usar_saldo_real: true, la herramienta ancla el cálculo en el saldo_inicial/saldo_data que esté registrado en cada cuenta corriente (vía omie_contas_correntes_listar): suma los lanzamientos realizados entre la saldo_data y el inicio del período pedido, llegando a un saldoRealAcumulado cercano al saldo bancario real — no es un valor hardcodeado en el MCP, se lee del registro Omie, así que cuando alguien configure el saldo real de cada cuenta allí (ej: en 01/01), el cálculo ya pasa a reflejarlo automáticamente, sin tocar el código. Cuentas sin saldo_data/saldo_inicial configurados (o con saldo_data posterior al inicio del período) reciben saldoRealAcumulado: null en lugar de un número inventado. Buscar ese offset dispara una llamada extra (movimientos entre la saldo_data más antigua entre las cuentas y el inicio del período) — puede ser lento si la saldo_data está muy en el pasado.

Hallazgo importante probando: Omie rechaza dos llamadas concurrentes del mismo método (error "Já existe uma requisição desse método sendo executada"), incluso con parámetros diferentes — por eso los pases de realizado/previsto (ambos usan ListarMovimentos) corren en secuencia, no en paralelo, dentro del caso de uso. Es una restricción adicional al rate limit ya documentado en la sección siguiente, específica para llamadas concurrentes del mismo call.

Períodos largos generan muchas páginas (ej: solo los cobros de ~3 semanas ya superaron 3.700 registros) — prefiera períodos de hasta ~3 meses por llamada.

Cuentas a Pagar (src/modules/contasPagar/)

• omie_contas_pagar_listar — caso de uso: lista lanzamientos de financas/contapagar (ListarContasPagar) ya con el nombre del proveedor resuelto (reutiliza el ClientesOmieGateway del módulo clientesFornecedores — Omie solo devuelve el código), valor, fecha de vencimiento, estado (PAGO/ABERTO/VENCIDO), documento fiscal, categoría y observación. Paginado, con filtro opcional data_alteracao_de/data_alteracao_ate.

Cuentas a Cobrar (src/modules/contasReceber/)

• omie_contas_receber_listar — caso de uso: lista apuntes de financas/contareceber (ListarContasReceber) ya con el nombre del cliente resuelto (reutiliza el ClientesOmieGateway del módulo clientesFornecedores), importe, fecha de vencimiento, estado (PAGADO/ABIERTO/VENCIDO), documento fiscal, número de pedido y categoría. Paginado, con filtro opcional 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 — caso de uso (generar/prorrogar/cancelar destructivas), CRUD de boleto sobre un título de cuentas a cobrar (financas/contareceberboleto: GerarBoleto/ObterBoleto/ProrrogarBoleto/CancelarBoleto), comprobable mediante ContasReceberFakeGateway sin tocar la Omie real. Atención: probado en vivo que esta cuenta Omie no tiene convenio bancario/boleto configurado — ProrrogarBoleto devuelve "No tenemos soporte para la generación de la remesa de pago para el banco -sin institución-"; GerarBoleto probablemente falla por el mismo motivo (no probado en vivo para no generar un boleto real de un título de cliente de producción). ObterBoleto/CancelarBoleto fueron validados en vivo (devuelven "ningún boleto generado" con seguridad, sin efecto secundario).

Hallazgo importante probando: el parámetro de filtro de fecha de Omie en estos dos endpoints (filtrar_por_data_de/filtrar_por_data_ate) filtra por la fecha de última modificación del apunte (info.dAlt), no por la fecha de vencimiento — confirmado pidiendo un rango de 1 día y comparando con data_vencimento de los registros devueltos (vencimientos distintos, dAlt siempre dentro del rango pedido). Por eso las herramientas del MCP exponen el parámetro como data_alteracao_de/data_alteracao_ate (no data_vencimento_de/ate), para no sugerir un comportamiento que la API no tiene. No existe (probado) filtro nativo por fecha de vencimiento en estos dos endpoints — para eso, use omie_fluxo_caixa_gerar, que usa financas/mf y filtra correctamente por vencimiento/pago.

Diferencia con omie_fluxo_caixa_gerar: estas dos herramientas exponen el apunte crudo (proveedor/cliente por apunte, sin agregación), útiles para revisar título por título; el flujo de caja agrega todo por período/cuenta corriente.

Presupuesto de Caja (src/modules/orcamentoCaixa/)

• omie_orcamento_caixa_consultar — caso de uso: presupuesto de caja NATIVO de Omie (previsto x realizado) por categoría financiera, en un mes/año. Método Omie: ListarOrcamentos (recurso financas/caixa), testable mediante OrcamentoCaixaFakeGateway sin tocar la Omie real. Diferente de omie_fluxo_caixa_gerar (calculado manualmente a partir de cuentas a pagar/ cobrar, agrupado por cuenta corriente/día), este es el informe listo de la propia Omie, agrupado por categoría (ej.: "1.01.01 Ventas"). Soporta el parámetro genérico filtros. Validado en vivo contra la cuenta real.

PIX (src/modules/pix/)

• omie_pix_listar / omie_pix_obter / omie_pix_obter_status / omie_pix_gerar / omie_pix_cancelar — caso de uso (generar/cancelar destructivas), CRUD de PIX sobre títulos de cuentas a cobrar (financas/pix: ListarPix/ObterPix/ObterStatusPix/GerarPix/ CancelarPix), testable mediante PixFakeGateway sin tocar la Omie real. Diferente de Boleto, esta cuenta Omie SÍ tiene PIX configurado y activo (379 registros reales en la base probada) — Listar/Obter/ObterStatus validados en vivo contra la cuenta real. Gerar/ Cancelar no fueron probados en vivo contra título de producción por prudencia (generarían/ cancelarían un cobro PIX de hecho, sin round-trip seguro garantizado — mismo cuidado que con el Boleto).

Notas Fiscales / NF-e (src/modules/nfe/)

• omie_nfe_listar / omie_nfe_consultar — caso de uso: consulta notas fiscales (NF-e) ya emitidas/registradas en Omie mediante produtos/nfconsultar (ListarNF/ConsultarNF), testable mediante NfeFakeGateway sin tocar la Omie real. La listación devuelve resumen (número, serie, clave, cliente, importe, cancelada o no); la consulta trae el detalle (ítems, títulos financieros generados por la nota). Módulo deliberadamente SOLO LECTURA: no emite ni cancela NF-e. La búsqueda contra la doc oficial no encontró un endpoint de "emitir NF-e desde cero" (tipo IncluirNFe(itens, cliente)) equivalente al IncluirPedidoVenda — la API trata NF-e mayoritariamente como consulta/importación de documento ya procesado por el motor fiscal del ERP, y la nota fiscal emitida es documento con efecto legal (sin "excluir y no dejar rastro" como en los demás módulos). Validado en vivo contra la cuenta real (4765 notas en la base de prueba).

Nota de Entrada (src/modules/notaEntrada/)

• omie_nota_entrada_listar / omie_nota_entrada_consultar — caso de uso: consulta notas de entrada (recepción física de mercancía proveniente de compra) ya registradas, mediante ListarNotaEnt/ConsultarNotaEnt (recurso produtos/notaentrada), testable mediante NotaEntradaFakeGateway. SOLO LECTURA — misma cautela que el módulo NF-e de producto y NFS-e: es la etapa final del flujo Requisición → Pedido de Compra → Recepción de NF-e → Nota de Entrada, un apunte fiscal/financiero definitivo (afecta stock y finanzas de verdad), sin round-trip seguro de prueba. La recepción de NF-e de proveedor (produtos/recebimentonfe) y el propio facturación de la nota (produtos/notaentradafat) quedaron fuera del alcance por el mismo motivo. Validado en vivo contra la cuenta real (3 notas de entrada existentes).

Características de Producto (src/modules/caracteristicasProduto/)

• omie_caracteristica_incluir / omie_caracteristica_alterar / omie_caracteristica_excluir / omie_caracteristica_consultar / omie_caracteristica_listar — caso de uso (las 3 primeras destructivas), CRUD de características reutilizables de producto (ej.: "Color", "Tamaño") mediante geral/caracteristicas, testable mediante CaracteristicaFakeGateway. Diferente de Categoría, probado en vivo que el CRUD completo funciona sin reservas (round-trip completo, sin rastro).

Categorías y Departamentos (src/modules/categoriasDepartamentos/)

• omie_categoria_incluir / omie_categoria_alterar / omie_categoria_consultar / omie_categoria_listar — caso de uso (las 2 primeras destructivas), CRUD de categorías financieras (geral/categorias), testable mediante CategoriaFakeGateway. Atención, hallazgos en vivo importantes: (1) IncluirCategoria NO recibe el código de la nueva categoría — recibe categoria_superior (código del grupo padre) y Omie GENERA el código del hijo automáticamente (ej.: padre 2.09 genera hijo 2.09.04); (2) no existe exclusión de categoría en la API, y probar AlterarCategoria con conta_inativa: 'S' NO tuvo efecto real (confirmado consultando de nuevo después) — las categorías creadas vía API quedan permanentemente activas en la cuenta, sin forma de eliminar/desactivar. Esto dejó una categoría de prueba residual en esta cuenta (2.09.04, "Categoría Prueba MCP Modificada") — inofensiva pero registrada aquí para no confundir a quien la encuentre después (mismo patrón que el producto de prueba residual del módulo estoque).

• omie_departamento_incluir / omie_departamento_alterar / omie_departamento_excluir / omie_departamento_consultar / omie_departamento_listar — caso de uso (las 3 primeras destructivas), CRUD de Departamento/Centro de Costo (geral/departamentos), testable mediante DepartamentoFakeGateway. Atención, hallazgo en vivo: codigo en IncluirDepartamento es el código del departamento PADRE (donde incluir), no del nuevo — Omie genera y devuelve el código del hijo en la respuesta (mismo patrón que Categoría). Diferente de Categoría, ExcluirDepartamento funciona de verdad — validado en vivo con round-trip completo, sin dejar rastro.

Registros Auxiliares (src/modules/cadastrosAuxiliares/)

• omie_bancos_listar / omie_cidades_listar / omie_paises_listar / omie_ncm_listar / omie_unidade_consultar — caso de uso, tablas de referencia estáticas mantenidas por la propia Omie (Bacen, IBGE, Receita Federal): bancos (geral/bancos), ciudades (geral/cidades), países (geral/paises), NCM (produtos/ncm) y unidades de medida (geral/unidade). Todos solo lectura, testable mediante CadastrosAuxiliaresFakeGateway. Soportan filtro nativo (nombre, UF, código, etc.) y el parámetro genérico filtros. Atención, hallazgo en vivo: omie_unidade_consultar exige el código exacto (no pagina/lista todo, diferente de los demás) — es consulta puntual, no listado. Validado en vivo contra la cuenta real.

CRM (src/modules/crm/)

• omie_crm_conta_incluir / omie_crm_conta_alterar / omie_crm_conta_excluir / omie_crm_conta_consultar / omie_crm_conta_listar — caso de uso (las 3 primeras destructivas), CRUD de Cuenta del CRM (crm/contas — embudo de ventas B2B, diferente del registro de Cliente/Proveedor), testable mediante ContaFakeGateway sin tocar la Omie real. Atención, hallazgo en vivo: IncluirConta/AlterarConta exigen los bloques endereco y telefone_email completos presentes (incluso con pocos campos rellenados) — Omie rechaza con "Tag [endereco]/[telefone_email] no informada!" si el bloque falta por completo.

• omie_crm_contato_incluir / omie_crm_contato_alterar / omie_crm_contato_excluir / omie_crm_contato_consultar / omie_crm_contato_listar — caso de uso (las 3 primeras destructivas), CRUD de Contacto del CRM (crm/contatos), siempre vinculado a una Cuenta.

• omie_crm_oportunidade_incluir / omie_crm_oportunidade_alterar / omie_crm_oportunidade_excluir / omie_crm_oportunidade_consultar / omie_crm_oportunidade_listar — caso de uso (las 3 primeras destructivas), CRUD de Oportunidad del embudo (crm/oportunidades). Atención, hallazgo en vivo: además de cuenta y contacto, exige codigo_solucao y codigo_origem — registros auxiliares que deben existir antes (Omie ya viene con "Solución 01"/"Solución 02" y orígenes estándar como "Activo").

• omie_crm_fases_listar / omie_crm_solucoes_listar / omie_crm_origens_listar — caso de uso (lectura), registros auxiliares del CRM (crm/fases, crm/solucoes, crm/origens) — los dos últimos son requisito previo para poder crear una Oportunidad.

• Validado en vivo con round-trip completo y seguro (cuenta, contacto y oportunidad de prueba, creados y eliminados sin dejar rastro).

Fuera del alcance de este ciclo (no pedido, baja prioridad): Tareas (crm/tarefas) y Características de Cuenta (crm/contascaract) — implementar solo cuando el usuario lo necesite.

Servicios / Orden de Servicio / NFS-e (src/modules/servicos/)

• omie_servico_incluir / omie_servico_alterar / omie_servico_excluir / omie_servico_consultar / omie_servico_listar — caso de uso (las 3 primeras destructivas), CRUD del registro de servicios prestados (servicos/servico), testeable mediante ServicoFakeGateway sin tocar la Omie real. Atención, hallazgo en vivo: AlterarCadastroServico exige el identificador anidado en intEditar (no en cabecalho como parecería natural) — la doc pública no lo deja claro.

• omie_os_incluir / omie_os_alterar / omie_os_excluir / omie_os_consultar / omie_os_listar — caso de uso (las 3 primeras destructivas), CRUD de Orden de Servicio (servicos/os), testeable mediante OrdemServicoFakeGateway sin tocar la Omie real. Atención, hallazgos en vivo importantes: (1) cada ítem exige codigo_servico_municipal/codigo_servico_lc116 como un código YA REGISTRADO en la tabla LC116 (ver omie_servicos_lc116_listar), no texto libre — la Omie rechaza con "Código da LC116 não cadastrada" si no; (2) cRetemISS es obligatorio en cada ítem aunque no esté marcado como tal en la doc pública; (3) el cliente del encabezado necesita tener la UF rellenada (mismo requisito ya visto en Pedido de Venta). Validado en vivo con round-trip completo y seguro (cliente de prueba desechable, creado y eliminado sin dejar rastro).

• omie_nfse_listar — caso de uso: lista las NFS-e ya emitidas (servicos/nfse, ListarNFSEs), testeable mediante NfseFakeGateway. SOLO LECTURA — la misma precaución que el módulo NF-e de producto (documento fiscal con efecto legal, sin round-trip seguro de emisión).

• omie_servicos_lc116_listar — caso de uso: lista los 255 códigos válidos de la Ley Complementaria 116 (clasificación de servicios), usado para descubrir el código correcto antes de crear una OS. Método Omie: ListarLC116 (recurso servicos/lc116).

Fuera del alcance de este ciclo (no pedido, baja prioridad): Contrato de Servicio recurrente (servicos/contrato) y facturación por lotes de OS/contrato (servicos/osp, servicos/oslote, servicos/contratofat, servicos/contratolote) — implementar solo cuando el usuario lo necesite.

Compras (src/modules/compras/)

• omie_pedido_compra_incluir / omie_pedido_compra_alterar / omie_pedido_compra_excluir / omie_pedido_compra_consultar / omie_pedido_compra_listar — caso de uso (las 3 primeras destructivas), CRUD completo sobre IPedidoCompraGateway (produtos/pedidocompra), testeable via PedidoCompraFakeGateway sin tocar la Omie real. Atención, hallazgos en vivo importantes: (1) nCodCC (pasado como codigo_conta_corrente) exige un código de cuenta corriente (geral/contacorrente), no de departamento/centro de coste, a pesar del nombre — la Omie rechaza con "Conta Corrente não cadastrada" si se usa un código de departamento; (2) PesquisarPedCompra (listado) oculta TODOS los pedidos por defecto — hay que solicitar explícitamente cada situación (lExibirPedidosPendentes/Faturados/Recebidos/Cancelados/Encerrados/RecParciais/ FatParciais, todo 'S'), lo que el gateway ya hace siempre; (3) cuando la página no tiene registros la Omie devuelve un error (SOAP-ENV:Client-5113) en lugar de una lista vacía — normalizado en el gateway para devolver una lista vacía.

• omie_requisicao_compra_incluir / omie_requisicao_compra_alterar / omie_requisicao_compra_excluir / omie_requisicao_compra_consultar / omie_requisicao_compra_listar — caso de uso (las 3 primeras destructivas), CRUD completo sobre IRequisicaoCompraGateway (produtos/requisicaocompra), testeable mediante RequisicaoCompraFakeGateway sin tocar la Omie real. Atención, hallazgo en vivo importante: a diferencia de otros endpoints de la Omie, los campos de IncluirReq/AlterarReq van directo en la raíz de param — no existe el wrapper requisicaoCadastro: {...} que sugiere la doc pública (la Omie rechaza con "Tag [REQUISICAOCADASTRO] não faz parte da estrutura".

Genérica (cubre todos los demás módulos)

• omie_chamar_api — recibe resource (ruta del módulo), call (método) y param (parámetros), permitiendo acceder a cualquier endpoint listado en https://developer.omie.com.br/service-list/ (clientes, financiero, CRM, ventas, NF-e, servicios, etc.)

Límite de peticiones de la Omie — cómo se protege el MCP

La Omie bloquea ráfagas de llamadas de dos formas: "consumo indebido" (el límite de peticiones propiamente dicho) y "consumo redundante" (llamadas muy parecidas en secuencia rápida — ya ha ocurrido en la práctica al consultar ~20 clientes en paralelo para montar un informe de pedidos). La protección está centralizada en OmieClient (src/omieClient.ts), por lo que cualquier módulo se beneficie automáticamente, sin tener que reimplementar nada:

• Throttle — toda llamada respeta un espaciado mínimo (300 ms) desde la llamada anterior realizada por la misma instancia de OmieClient, incluso si varias llegan al mismo tiempo (Promise.all, mapWithConcurrency, etc.). Esto reduce la probabilidad de caer en "consumo redundante" incluso antes de necesitar un reintento.

• Reintento con la espera adecuada — si la Omie aun así bloquea, el OmieClient vuelve a intentarlo (hasta 4 veces), respetando el tiempo que la propia Omie sugiere en el mensaje de error (ej.: "Aguarde 57 segundos") en lugar de un backoff fijo corto.

• mapWithConcurrency (src/shared/concurrency.ts) — usado por los gateways que buscan varios registros por código en lote (ProdutosOmieGateway.consultarProdutosPorCodigo, ClientesOmieGateway.consultarClientesPorCodigo), limita la concurrencia del propio código a 5 llamadas simultáneas, complementando el throttle del cliente.

Regla para módulos nuevos:

1. Nunca llamar Promise.all / Promise.allSettled en un array de códigos sin límite de concurrencia — usar siempre mapWithConcurrency.

2. Nunca llamar dos veces al MISMO método (call) en paralelo, incluso con parámetros distintos — la Omie rechaza con "Já existe uma requisição desse método sendo executado" (hallazgo al construir fluxoCaixa, que necesita dos pasadas de ListarMovimentos). Ejecuta en secuencia (await una, después la otra).

3. Las llamadas en paralelo de métodos diferentes (por ejemplo, consultar productos y stock al mismo tiempo) son seguras y no necesitan nada de esto; el throttle del cliente ya lo cubre.

Añadir un nuevo módulo

Passthrough (la Omie ya devuelve el dato listo):

1. Crea src/tools/<modulo>.ts exportando un array de ToolDef (usa defineTool() de src/tools/types.ts).

2. Importa ese array y concaténalo en allTools, en src/tools/registry.ts.

En capas (necesita agregar/combinar llamadas de la Omie — copia src/modules/estoque/ como referencia):

1. application/use-cases/ — la regla de negocio (recibe un gateway y devuelve el resultado listo para el usuario).

2. application/dto/ — esquema zod del param de entrada y tipo del resultado.

3. infrastructure/gateways/ — solo llamadas resource/call, sin regla de negocio.

4. presentation/mcp/ — la ToolDef con execute instanciando gateway + caso de uso.

5. <modulo>-register.ts + index.ts — exportación del paquete de tools.

6. Importa el array en allTools, en src/tools/registry.ts.

En ambos casos, src/index.ts registra la herramienta automáticamente — no cambies nada ahí.

Próximos pasos (roadmap)

• Añadir módulos dedicados para Financeiro, Ventas/NF-e y CRM según sea necesario (mismo patrón de archivo).

• Añadir cache/paginación automática para listados grandes.

• Añadir pruebas automatizadas con mocks de la API de Omie.

Seguridad

Nunca hagas commit del archivo .env ni expongas OMIE_APP_KEY/OMIE_APP_SECRET en repositorios públicos.