ERP.net Technical Reference
Tool families, gating, and Domain API conventions
A compact reference for people (and AI agents) who need the exact mechanics.
Terminology
| Term | Meaning |
|---|---|
| Instance | One ERP.net installation you connect to, identified by its base address |
| Domain API | ERP.net's data API that Operator reads and writes through |
| Repository name | Dotted entity name, e.g. Crm.Sales.SalesOrders |
| OData name | The same entity in URL form, e.g. Crm_Sales_SalesOrders |
| DisplayText | Human-readable representation available on every entity |
| Current model | Your instance's live model, including custom and calculated attributes |
Tool families and their gates
Data tools unlock only after the corresponding prerequisite tool has been called in the conversation:
| Prerequisite | Unlocks |
|---|---|
search_entity_schema or get_entity_by_repository_name |
query_erp_data |
get_update_data_instructions |
create_erp_record, update_erp_record, delete_erp_record |
get_working_with_documents_instructions |
change_document_state, void_document, get_document_printout, enterprise-context tools |
get_file_management_instructions |
list_object_files, get_file_from_object, attach_file_to_object |
get_import_export_info |
import_erp_data, export_erp_data |
Ungated ERP.net tools include search_instance_index (hybrid search over products, companies, and document types) and search_document_types.
Query options
query_erp_data accepts: entity, filter, select, top (1–100, default 10), skip, expand, language.
Results include _webClientUrl per record and a _navigatorUrl for the result set, so answers can link back into the ERP.net Web Client.
Filter syntax rules that matter
The Domain API is OData v4, with a few conventions that trip up generated queries:
Id eq c1c10ef1-21c0-445b-b275-3a9f80cfd07f ✓ bare GUID
Id eq guid'c1c10ef1-...' ✗ no guid prefix
DocumentDate ge 2026-07-19T00:00:00 ✓ no trailing Z
DocumentDate ge 2026-07-19T00:00:00Z ✗
Customer eq 'Crm.Sales.Customers(c1c10ef1-...)' ✓ reference filters are quoted
References are set with entity bindings on write, not with bare identifiers. Multi-language fields are objects keyed by language code, e.g. { "en": "Test", "bg": "Тест" }.
Custom properties (CustomProperty_*) are scalar values — put them in select, never in expand.
Document states
New → Planned → FirmPlanned → Released → Completed → Closed
States move forward; intermediate states may be skipped (New → Released is valid). Voiding is separate and irreversible, takes a required reason, and can optionally cascade to sub-documents.
Many document operations require an enterprise company (and sometimes location) context to be set for the instance.
Enforcement points
| Layer | Where it applies |
|---|---|
| ERP.net roles and object security | Every request, always |
Operator Permission Policies (read / update per namespace or entity, wildcards supported) |
Every query and every write tool |
| Agent capabilities | Which tools exist in the conversation at all |
| Confirmation | Destructive tools pause for human approval |
update access implies read, update, and delete. A user with no policy assigned has unrestricted Operator-side access, with ERP.net security still applying.
Apps
Apps call operator.fetch(path, options) with a relative Domain API path. The token is attached server-side, calls are serialised into a FIFO queue to avoid ERP.net's concurrency limits, and failures come back as errors carrying the ERP.net message, status, and details.
operator.me() returns the Operator account, the ERP.net user for the current instance (when available), and the instance itself.