Table of Contents

Namespace NuvTools.Payment.Omie.ApiClient.Services

Classes

OmieApiClient

Default implementation of the Omie ERP API client.

OmieCategoryProvider

Resolves the category (cCodCateg) a service order carries in Omie. Omie requires the category on inclusion and every account has its own chart of accounts — which is why it is discovered in the registration instead of hardcoded: the categories are listed and the first of the configured preferences is picked by name.

Only accounts that can take a revenue entry are considered: conta_receita = "S", active, not a totalizer (totalizers are just groupings of the chart of accounts) and not a transfer account. Filtering by name alone could land on an expense account with a similar name.

OmieCheckingAccountProvider

Omie checking accounts (geral/contacorrente/) — the list an application offers so the user can pick where the receivable of a service order lands (nCodCC, required on inclusion).

Blocked accounts are left out: Omie lists them but does not accept entries on them.

OmieClientDirectoryProvider

Omie client registration indexed by document (CNPJ/CPF) — the way to discover the client code (codigo_cliente_omie), and the only one: Omie does not look a client up by document, and the typed client (IOmieApiClient) only consults by the very code one is trying to discover. The whole registration is listed (ListarClientes, paginated) and searched by document.

The document is compared by digits only: in Omie it usually comes formatted ("12.345.678/0001-99") while applications tend to store it clean — comparing as text would find nobody.

The listing is expensive, so it is cached for NuvTools.Payment.Omie.ApiClient.Services.OmieClientDirectoryProvider.CacheDuration. A client just registered in Omie may, for that long, still not be found.

OmieContractProvider

Omie Service Contracts, read whole (ListarContratos, paginated) and indexed by the contract number (cNumCtr) — the number a caller's own configuration stores, because it is what the user reads in Omie. A contract is a price registry: it carries the negotiated value and the validity period of one client, and is never billed through.

Listed whole and cached for NuvTools.Payment.Omie.ApiClient.Services.OmieContractProvider.CacheDuration, never consulted one by one. A screen that shows contracts in a grid would otherwise ask Omie once per row, and Omie answers a burst of repeated calls with "Consumo redundante detectado" — which blocks the app_key for every other integration, not just the grid.

OmieDirectApiClient

Raw call to the Omie API, for the registrations IOmieApiClient does not cover or covers without the fields a caller needs. It concentrates three details that any new call would otherwise repeat:

  1. the Content-Type goes without the charset parameter — with it, the Omie gateway answers a SOAP "Bad Request" envelope (and that is exactly what PostAsJsonAsync/JsonContent would send);
  2. business errors come in the body (faultstring) alongside an HTTP 5xx — without reading it, the failure turns into an "InternalServerError" that says nothing;
  3. consumption refusals (REDUNDANT, MISUSE_API_PROCESS) are not request errors and get their own treatment (see IsThrottled(string?)).
OmieServiceCatalogProvider

Omie service catalog, read whole (ListarCadastroServico, paginated) and indexed by the business code (cCodigo) — the code applications store in their own configuration. This is how the nCodServico, the description and the unit price of a service are discovered: Omie exposes no search by cCodigo, so the catalog is listed and searched in memory.

The result is cached for NuvTools.Payment.Omie.ApiClient.Services.OmieServiceCatalogProvider.CacheDuration because Omie refuses repeated ListarCadastroServico calls in a short window ("Consumo redundante detectado") — without the cache, opening a screen and generating a service order right after would drop the second call.

OmieServiceOrderBillingProvider

Invoicing of a single service order in Omie — the documented path to issue the NFS-e of one OS, which IOmieApiClient does not cover and therefore goes through the direct client:

  1. StatusOS (servicos/os/): fiscal state of the order — stage, whether it was cancelled, whether it was already invoiced and the NFS-e that came out of it. It is the query that says whether there is anything to do, and the one that confirms the result afterwards.
  2. ValidarOS (servicos/osp/): Omie's validation before invoicing. It is what points out, in the API's own words, which required data is missing on the order or on the client registration — instead of finding out through the city hall's rejection, after the invoice was already requested.
  3. FaturarOS (servicos/osp/): invoices that order. The equivalent of "Faturar Selecionada" in the Omie UI — not to be confused with FaturarLoteOS (servicos/oslote/), which invoices every order of a stage and, triggered for one client, would take the others along.

None of them invents data: the invoice content is the order's. What is decided here is only when to ask for the invoice.