home / skills / openclaw / skills / omie

omie skill

safe

This skill integrates Omie ERP via REST API to manage clients, products, orders, invoices, financials, and stock, including real-time webhooks.

npx playbooks add skill openclaw/skills --skill omie

Review the files below or copy the command above to add this skill to your agents.

Files (5)

SKILL.md

2.4 KB

---
name: omie
description: "Omie ERP integration via API. Manage clients, products, orders, invoices (NF-e), financials (contas a receber/pagar), and stock. Use when users ask about ERP data, financials, orders, invoices, stock, or clients from Omie. Also handles webhooks for real-time events."
---

# Omie ERP Skill

Integração com o Omie ERP via API REST.

## Setup

Requer variáveis de ambiente:
```bash
export OMIE_APP_KEY="your_app_key_here"
export OMIE_APP_SECRET="your_app_secret_here"
```

## API Client

Use o script Python para todas as operações:

```bash
python3 skills/omie/scripts/omie_client.py <command> [args]
```

### Comandos disponíveis

#### Clientes
```bash
python3 scripts/omie_client.py clientes_listar [pagina] [por_pagina]
python3 scripts/omie_client.py clientes_buscar cnpj_cpf=00.000.000/0001-00
python3 scripts/omie_client.py clientes_buscar codigo=1234567
python3 scripts/omie_client.py clientes_detalhar codigo=1234567
```

#### Produtos
```bash
python3 scripts/omie_client.py produtos_listar [pagina] [por_pagina]
python3 scripts/omie_client.py produtos_detalhar codigo=1234567
```

#### Pedidos de Venda
```bash
python3 scripts/omie_client.py pedidos_listar [pagina] [por_pagina]
python3 scripts/omie_client.py pedidos_detalhar numero=1234
python3 scripts/omie_client.py pedidos_status numero=1234
```

#### Financeiro
```bash
python3 scripts/omie_client.py contas_receber [pagina] [por_pagina]
python3 scripts/omie_client.py contas_pagar [pagina] [por_pagina]
python3 scripts/omie_client.py resumo_financeiro
```

#### Notas Fiscais
```bash
python3 scripts/omie_client.py nfe_listar [pagina] [por_pagina]
python3 scripts/omie_client.py nfe_detalhar numero=1234
```

#### Estoque
```bash
python3 scripts/omie_client.py estoque_posicao [pagina] [por_pagina]
python3 scripts/omie_client.py estoque_produto codigo=1234567
```

## Webhook

O Omie pode enviar eventos para um endpoint HTTP. Configurar em:
Omie → Configurações → Integrações → Webhooks

Eventos suportados:
- `pedido.incluido` / `pedido.alterado`
- `nfe.emitida` / `nfe.cancelada`
- `financas.recebido` / `financas.pago`
- `cliente.incluido` / `cliente.alterado`

Para iniciar o receptor de webhooks:
```bash
python3 scripts/omie_webhook.py --port 8089
```

## Limites da API
- **Rate limit:** 3 requisições/segundo por app
- **Paginação:** máximo 500 registros por página
- **Timeout:** 30 segundos

Overview

This skill integrates with the Omie ERP API to manage clients, products, sales orders, invoices (NF-e), financials, and stock. It also supports receiving real-time webhook events from Omie for changes in orders, invoices, payments, and clients. Use it to query ERP data, run basic operations, and subscribe to event-driven updates.

How this skill works

The skill calls Omie REST endpoints using configured app key and secret to list, search, and retrieve details for clients, products, orders, invoices, financial entries, and stock positions. It supports paginated listing, rate limiting awareness, and a local webhook receiver to process incoming Omie events in real time. A Python client script exposes command-line commands for the most common operations.

When to use it

Query client records or lookup by CNPJ/CPF or internal code
Fetch product listings or product stock and position
Retrieve sales orders, order status, or detailed order data
List invoices (NF-e) and fetch invoice details
Get financial summaries, accounts receivable/payable items
Receive real-time updates via webhooks for orders, invoices, payments, and client changes

Best practices

Set OMIE_APP_KEY and OMIE_APP_SECRET in environment variables before use
Respect API rate limit (3 requests/second) and use pagination up to 500 records per page
Use detailed commands for targeted lookups to avoid large bulk requests
Run the webhook receiver behind a reverse proxy or process manager and secure the endpoint
Handle API timeouts (30s) and retry transient failures with exponential backoff

Example use cases

Sync client master data into a local CRM by searching and listing clients
Update inventory counts by querying estoque_posicao and per-product stock endpoints
Automate invoice reconciliation by listing NF-e and matching with payment receipts
Monitor sales pipeline by listing orders and subscribing to pedido.incluido and pedido.alterado webhooks
Build a financial dashboard using resumo_financeiro and accounts receivable/payable endpoints

FAQ

How do I authenticate requests?

Set OMIE_APP_KEY and OMIE_APP_SECRET as environment variables and the client will include them in API calls.

How do I receive real-time events from Omie?

Configure webhooks in Omie settings and run the webhook receiver script on a public endpoint; supported events include orders, invoices, payments, and client changes.

What are common limits to plan for?

The API allows 3 requests per second per app, pages up to 500 records, and a 30‑second timeout; implement rate limiting and pagination in integrations.