Nama ERP Docs

English

العربية

English

العربية

Appearance

العربية

Integration Scenarios Between Nama and Other Systems ​

Introduction ​

We receive — on an almost daily basis — a question from customers and colleagues in sales, implementation, and technical support teams that goes something like:

"Can we integrate Nama with such-and-such system?"

The question usually arrives without details, so answering it with a quick "yes" or "no" is inaccurate. Whether integration is possible — and how costly it might be — depends not only on Nama's capabilities, but also on the other system's capabilities, the direction of data flow between the two systems, and whether the other party provides documented APIs.

For this reason, we present in this document a systematic framework for answering that question — one that allows our colleagues in sales and implementation teams, and even the customer themselves, to ask the right questions before requesting a technical or financial proposal. This saves many rounds of back-and-forth and leads to a sound decision in less time.

Quick Summary

Nama is open by default for integration with other systems via a fully documented REST API following the OpenAPI 3.0 specification, available to every customer at no additional cost. Any additional cost — if it exists at all — typically originates from the other system's side, not ours.

The Central Question: In Which Direction Does the Data Flow? ​

Before exploring technical feasibility, we need to precisely identify the direction of flow. Each direction has its own requirements, and the party bearing the technical and financial burden differs accordingly. There are four main scenarios:

#ScenarioSourceDestinationParty Responsible for Providing the API
1Other system reads from NamaNamaOther systemNama (already available)
2Other system writes to NamaOther systemNamaNama (already available)
3Nama writes to the other systemNamaOther systemOther system
4Nama reads from the other systemOther systemNamaOther system (or its database)

Before answering the customer's question, we must know which of these scenarios they mean — or which combination of them — since integration often requires more than one direction at once (for example: syncing items from Nama to an e-commerce store + receiving orders from the store into Nama).

Scenario 1: The Other System Reads from Nama ​

This is the easiest and most common scenario. Nama already provides a complete REST API covering all system entities, with automatic documentation in OpenAPI 3.0 format and an interactive Swagger UI for exploring and testing the API directly.

Therefore, the near-ready answer in this scenario is:

Yes; the other system can read from Nama directly via our existing REST API, with no additional development on our part and no additional cost to the customer.

It is sufficient for the other system's team to review the Nama ERP REST API guide, retrieve an API key from the "API Credentials" screen, and start calling the endpoints directly.

When do we need additional development?

If the other system requires a non-standard shape of data — such as a custom field grouping, or a composite endpoint that merges data from multiple entities into a single response — then we need to develop a custom API, which falls under paid services (see the "Additional Costs" section below).

Questions to Ask the Customer in This Scenario ​

  1. What entities does the other system need to read? (Sales invoices, items, customers, stock balances, …)
  2. Will the reading be on-demand, periodic (polling), or event-driven (Webhook)?
  3. Does it need full data, or only new/updated records?

Scenario 2: The Other System Writes to Nama ​

This scenario is also fully supported without additional development on our part. The same REST API supports Create, Update, and Delete operations for all entities, with data validation, reference field management, and everything else documented in the API guide.

The answer here is also — in most cases:

Yes; the other system can write to Nama directly via the REST API, with no additional development and no additional costs.

Keep in Mind

Every write operation passes through Nama's existing permissions and validation system (business rules, mandatory field checks, approvals…). If the other system sends incomplete data or data that violates business rules, the write will be rejected just as it would be if a user entered it manually. The other party's team should be informed of this so they understand the error messages they may receive.

Questions to Ask the Customer in This Scenario ​

  1. What entities will the other system write?
  2. What fields does it have for each entity? Are they sufficient to meet Nama's requirements (mandatory fields, reference fields…)?
  3. How will error messages be handled? Does the other system have a retry mechanism, or will it rely on human intervention?

Scenario 3: Nama Writes to the Other System ​

Here the equation changes fundamentally. Since Nama is the caller, it needs a ready and well-defined API on the other system's side to send data to. The most important question now is directed at the other party, not us:

Do you have a ready REST API to receive this data? What is its documentation?

The best form — and the fastest to implement — is for the other party to have an OpenAPI specification (whether OpenAPI 3.0 or the earlier Swagger 2.0). Such a specification answers — automatically — most of the technical questions that may arise during development: What endpoints are available? What fields are in each request? What are the data types? What are the possible response codes? What is the authentication mechanism? And so on.

Why do we specifically insist on OpenAPI?

Because Nama generates OpenAPI for all its entities as mentioned in the API guide, and we believe this is the correct professional approach for describing APIs in our current era. When both parties have a clear OpenAPI specification, integration time shrinks from weeks to days — even to hours in some cases.

If No OpenAPI Specification is Available ​

The absence of OpenAPI does not mean integration is impossible, but it does mean the other party must provide us with:

  1. Complete written documentation for each endpoint (URL, HTTP method, request headers, body schema, response schema, error codes).
  2. Practical examples of successful and failed requests (Request / Response samples).
  3. A documented authentication mechanism (Bearer Token, API Key, OAuth2…).
  4. A test environment (Sandbox / Staging) that we can test against before moving to production.

Without these elements, the work becomes guesswork, and time and cost estimates balloon unjustifiably.

Questions to Ask the Customer in This Scenario ​

  1. Does the other system provide a REST API that receives the required data?
  2. Does it have documentation in OpenAPI / Swagger format? If not, what is the alternative?
  3. What authentication mechanism is required? Does it need prior activation or agreement with the other party?
  4. Are there rate limits on API calls?
  5. Is there a test environment?

Scenario 4: Nama Reads from the Other System ​

This scenario follows the same logic as Scenario 3 — Nama is the caller and a well-defined interface on the other side is required. However, there is a special case worth elaborating on: an older system that has no REST API at all.

Special Case: A Legacy System with No REST API — Integration via Database ​

In the market — especially in large organizations — there are established legacy systems that provide no modern APIs (REST/SOAP); such as older versions of Oracle E-Business Suite and some custom-built ERPs written in older languages. In such cases, the customer may request that integration be done directly via the database.

The Two Fundamental Conditions for Accepting This Type of Integration ​

  1. The customer must provide database access — preferably via a dedicated user account for Nama, with permissions limited to only the tables it actually needs.
  2. The other system's technical team must assist us in understanding the tables and schema: Which tables do we read from? What are the relationships between them? What does each column mean? What flags indicate that a record is approved, cancelled, or in draft status?

Direct Writing to Another System's Database: A Red Line

We avoid — as a matter of principle — having Nama write directly into another system's database. Doing so bypasses all business rules, validations, and logical triggers built by that system's engineers, and typically leads to data corruption that is difficult to detect until it is too late.

We only accept this type of integration when two conditions are met simultaneously:

  1. The other system's technical team explicitly states that this is their approved method for writing.
  2. That same team assists us with the implementation details: Which tables do we write to? What are the mandatory columns? What are the computed fields? Are there triggers that must fire before/after writing? Are there sequences that must be called before insertion?

In most cases we end up doing read-only access from the other system's database, then writing appropriately back into Nama.

Practical Example ​

One of the common scenarios when integrating with older Oracle EBS versions: Nama reads invoice transactions and supplier balances directly from EBS tables, then uses this data to enrich reports and screens inside Nama, without writing anything back.

Questions to Ask the Customer in the Database Integration Case ​

  1. What is the database type and version? (Oracle, SQL Server, MySQL, …)
  2. Is there documentation for the schema of the relevant tables?
  3. Does the other system's technical team have the capacity to support us during analysis?
  4. Will we be given secure access (VPN, IP Whitelisting, restricted user account…)?
  5. Does the data we need update in real time, or is periodic synchronization sufficient?

Who Bears the Cost? ​

In light of the above, the financial policy for integrating Nama with other systems can be summarized as follows:

What is Available at No Additional Cost ​

  • Using Nama's standard REST API for all entities and all CRUD operations: available to every customer who has the system, at no additional cost, with no development required on our part.
  • API documentation in OpenAPI 3.0 format and Swagger UI: available automatically within the system.
  • Quick and simple technical assistance for the other party's team (answering a question here and there, clarifying a specific request structure): we provide this free of charge in most cases as a matter of good technical partnership.

What Requires a Financial Proposal ​

There are three common cases that require a separate financial proposal:

  1. Requesting specialized training for the other party's development team; for example, the customer requests a full workshop explaining the integration mechanism and best practices.
  2. Developing a new custom API in a specific shape not supported by the standard API; for example, the customer requests a composite endpoint that merges data from multiple entities into a single response in a custom format.
  3. Namasoft taking full responsibility for developing the calling side (Scenario 3 or 4); meaning we — not the customer's team — write the code that calls the other party's API or reads from their database. This is full development work requiring analysis, design, implementation, and testing, and therefore falls under paid services.

A Note on the Third Case

The cost of this case varies significantly depending on the quality of the other party's documentation. Integration with a system that has a clear OpenAPI Spec and a Sandbox environment may take a few days, while integration with a legacy system with no documentation may take weeks or months. Therefore, when building a financial proposal for this case, we should first ask the customer to provide the other party's documentation, so that the estimate is based on real information rather than assumptions.

A Quick Checklist for Colleagues Before Responding to the Customer ​

Before responding to the customer about whether integration is possible, and before building any financial proposal, we should clarify the following answers:

  1. Direction of flow: Who reads from whom? And who writes to whom? (One of the four scenarios above, or a combination)
  2. Entities involved: What entities will data flow through? (Invoices, items, customers, accounting entries, …)
  3. Timing frequency: Real-time synchronization, periodic (Batch), or event-driven (Webhook)?
  4. Other party's capabilities: Does it have a REST API? Does it have an OpenAPI Spec? Does it have a test environment?
  5. Authentication mechanism: Supported by both sides? Does it require prior agreement?
  6. Other party's technical team: Cooperative and available for discussion, or difficult to reach?
  7. Does it require database integration (which should be treated as an exception, not the rule)?

Once we have complete answers to these questions, we can — with full confidence — give the customer a precise answer about integration feasibility, the estimated timeline, and the cost if any.