Omie on Orkestia: Brazilian books, one connection

Orkestia is the backbone that connects software, AI, and the real world. For a lot of Brazilian SMBs the books already live in Omie. This post is how you connect that company once, then list clients, products, payables and receivables, create a party, and settle a title from the console, the API, or an AI client, without exporting a CSV.

Omie is a catalog domain. It is not a homepage product card. The live types are on the catalog. Everything below is written against the platform as it works today.

What you connect

One Orkestia connection is one Omie company. You create an application in Omie Developer, copy the APP_KEY and the APP_SECRET, and paste both into Orkestia. The host is fixed at Omie's public API. There is no URL for you to type, and the secret stays on the connection. An agent that starts omie.* workflows never holds the key.

The connection test asks Omie for the company and records the código, razão social, and CNPJ. If that test fails, the keys are wrong. If it succeeds, the catalog can use the connection.

Create an account, subscribe, then add Omie from Connections. Pricing for the seats that run it is on the pricing page.

What a workflow does here

A capability in Orkestia is a typed workflow: declared inputs, named states, and a history of who ran it. The same object serves the console, the API, and MCP. For Omie that means:

• List companies, clients, products, contas a pagar, and contas a receber.
• Create a cliente or fornecedor. The integration code you send is a declared identity, the id you already have in the other system, not an email join.
• Post and settle payables and receivables, including a title that arrived in USD and needs a BRL amount on the Omie date.

Reads and writes go through the same access control as every other domain. Retry a failed run from where it stopped. Open the history when someone asks who posted the title.

From an AI client

Paste the MCP server, sign in, then confirm identity before you touch the books.

https://mcp.orkestia.dev/mcp

whoami()
list_workflow_types(prefix="omie.")
get_workflow_schema("omie.clientes.list")

If the schema comes back with has_prerequisites: true, call get_workflow_prerequisites first. The usual prerequisite is the Omie connection itself. The setup guide already has Orkestia's side filled in.

Start a list with the connection you just created. Read the state data when the run finishes. A green status is not the list. The payload is.

The same loop posts a title and settles it. Read the schema for every mutate before you start it. read_only on the schema is the cheapest safety rail on the platform.

The general first-run path, not Omie-specific, is Connect your AI tool, then run your first workflow. Claude, Cursor, and Codex take the same URL: Orkestia for Claude, Orkestia for Cursor, Orkestia for Codex.

Omie and Stripe together

When a customer already exists in Stripe, keep Stripe as the source and Omie as the ledger. The code you send Omie is the Stripe customer id you already have, not the email address. Email can live on the cadastro. It is not how the two systems join.

Stripe itself is a separate connection. See Stripe on Orkestia.

A first afternoon on the books

1. Create the Omie developer app. Add the connection. Confirm the company name on the test is the company you meant.
2. From MCP, list_workflow_types(prefix="omie."). Start omie.clientes.list or whichever list schema you opened. Read the payload.
3. Create one party with a declared integration code you already have, for example a Stripe cus_. Do not use email as the join. Do not reuse a probe CNPJ you found on a blog.
4. List contas a pagar. Read one title. Only then post or settle, after get_workflow_schema on that mutate.

If a write fails, wait and read the error in the run. Retrying the same failed call in a tight loop is how you lock the method on Omie's side. List still works while you wait. History is the artefact you keep.

What not to do

Do not put the APP_SECRET in chat, in a Staff env file, or in initial_data. It belongs on the connection.

Do not invent a second ledger. If the books are in Omie, list and write them there. Bling is a different ERP, with its own connection, covered in Bling on Orkestia.

Do not assume a homepage card. Open Omie from the catalog, or ask the connected assistant to list omie. types.

What to read next

• The capability catalog, filter by Omie.
• Documentation.
• Pricing.

If you get stuck, write to hello@orkestia.dev. A real person reads it.