Directo abi

Kasutaja tarvikud

Lehe tööriistad


et:api_direct

Erinevused

Siin näed erinevusi valitud versiooni ja hetkel kehtiva lehekülje vahel.

Lõlita võrdlemise vaatele

Both sides previous revisionPrevious revision
Next revision		Previous revision
et:api_direct [2026/07/07 10:31] – [Base URL & Versioning] toomaset:api_direct [2026/10/21 08:16] (Hetkel kehtiv) – [📦 API Resources & Endpoints] toomas
Rida 10: Rida 10:
   * API key (obtain from your Directo administrator)   * API key (obtain from your Directo administrator)
   * Basic understanding of REST APIs and HTTP methods   * Basic understanding of REST APIs and HTTP methods
-  * API Resources and Endpint can be found in Postman collection. Response field list managed in Directo ERP. Postman collection can be downloaded here: {{:et:toomas20260702-122402.json|POSTMAN}}+  * API Resources and Endpint can be found in Postman collection. Response field list managed in Directo ERP. Postman collection can be downloaded here: [[:et:api_direct:postman|POSTMAN]]
 ==== Quick Start Guide ==== ==== Quick Start Guide ====
  
Rida 17: Rida 17:
   - **Choose Format**: Set the Accept header to application/json or application/xml   - **Choose Format**: Set the Accept header to application/json or application/xml
   - **Make Your First Request**: Try the "All items" request to retrieve your item catalog   - **Make Your First Request**: Try the "All items" request to retrieve your item catalog
 +  - **Call GET /v1/openapi.json** to see which resources and fields are enabled for your key.
  
 ==== Base URL & Versioning ==== ==== Base URL & Versioning ====
Rida 27: Rida 28:
 **Current Configuration:** **Current Configuration:**
  
-  * **baseUrl**: [https://login.directo.ee/apidirect](https://login.directo.ee/apidirect) +  * **baseUrl**: <code>https://login.directo.ee/apidirect</code> 
-  * **version**: 1 (current API version)+  * **version**: <code>1</code> (current API version)
  
 **Example Full URL:** **Example Full URL:**
Rida 48: Rida 49:
  
 ==== Getting Your API Key ==== ==== Getting Your API Key ====
-Contact your Directo system administrator to obtain an API key. Each key is associated with specific permissions and access levels.+If your company doesn't have an API key yet, contact your Directo project manager — they will generate it. 
 + 
 +If a key has already been created, there's no need to request it again: any user with SUPER rights can view it on the employee card under Settings → Integration.
  
 ==== Security Best Practices ==== ==== Security Best Practices ====
Rida 89: Rida 92:
 </code> </code>
  
 +===== 🧭 API Discovery (openapi.json) =====
 +
 +Every API key has a machine-readable description of the API in OpenAPI 3.0 format:
 +
 +<code bash>
 +curl -H "X-Directo-Key: YOUR_API_KEY_HERE" \
 +     https://login.directo.ee/apidirect/v1/openapi.json
 +</code>
 +
 +The description is **key-specific**: it lists only the resources and fields configured
 +for that API key in Directo. If the key configuration changes, the description changes too.
 +
 +==== What the description contains ====
 +
 +^ Section ^ Content ^
 +| ''paths'' | Resources enabled for the key (e.g. ''/v1/items''). All are GET requests. |
 +| ''parameters'' | Fields you can filter by. All are typed as ''string'' because the value is a filter expression (e.g. ''>2025-01-01''). |
 +| ''responses → 200'' | Response fields and their data types (string, number, integer, boolean, date-time), in both JSON and XML. |
 +| ''responses → 400/403/500'' | Possible error messages with examples. |
 +| ''securitySchemes'' | Authentication via the ''X-Directo-Key'' header. |
 +
 +==== Filter parameter naming ====
 +
 +^ Prefix ^ Meaning ^ Example ^
 +| (none) | Header / master record field | ''/invoices?customercode=K001'' |
 +| ''row_'' | Document line field | ''/invoices?row_item=9810'' |
 +| ''data_row_code'', ''data_row_content'', ''data_row_param'' | Custom data field (''datafields'') | ''/items?data_row_code=COLOR'' |
 +| ''row_sumdiscount_'', ''row_campaign_'' | Price formula sum discount and campaign lines | ''/priceformulas?row_campaign_campaign=SUMMER'' |
 +
 +**Note:** You can only filter by fields that are selected for output on the key.
 +Otherwise the API returns ''Filter "x" not selected to output''.
 +The allowed filters are listed under ''parameters'' in ''openapi.json''.
 +
 +==== How to use it ====
 +
 +  * **Postman / Insomnia**: Import → Link. This generates a complete request collection automatically.
 +  * **Swagger UI / Swagger Editor**: browse and test the API in a browser.
 +  * **Code generators** (e.g. openapi-generator): generate client libraries.
 +  * **AI agents and MCP servers**: describe the available tools automatically.
 +
 +<WRAP important>
 +The description shows which data can be retrieved with the key. Treat it with the same care
 +as the key itself: do not publish it, and always send the key in the header, never in the URL.
 +</WRAP>
 ===== 🔍 Advanced Filtering (Key Feature) ===== ===== 🔍 Advanced Filtering (Key Feature) =====
  
Rida 303: Rida 350:
  
 <code> <code>
-GET {{baseUrl}}/v{{version}}/sales_quotations +GET {{baseUrl}}/v{{version}}/openapi.json       # API description – enabled resources, fields 
-GET {{baseUrl}}/v{{version}}/orders +GET {{baseUrl}}/v{{version}}/sales_quotations   # Sales quotations – header and rows 
-GET {{baseUrl}}/v{{version}}/invoices +GET {{baseUrl}}/v{{version}}/orders             # Sales orders – header and rows 
-GET {{baseUrl}}/v{{version}}/purchase_orders +GET {{baseUrl}}/v{{version}}/invoices           # Sales invoices – header and rows 
-GET {{baseUrl}}/v{{version}}/stock_receipts +GET {{baseUrl}}/v{{version}}/purchase_orders    # Purchase orders – header and rows 
-GET {{baseUrl}}/v{{version}}/purchase_invoices +GET {{baseUrl}}/v{{version}}/stock_receipts     # Stock receipts – received goods rows 
-GET {{baseUrl}}/v{{version}}/purchase_payments +GET {{baseUrl}}/v{{version}}/purchase_invoices  # Purchase invoices – header and rows 
-GET {{baseUrl}}/v{{version}}/customers +GET {{baseUrl}}/v{{version}}/purchase_payments  # Outgoing payments – paid purchase invoices 
-GET {{baseUrl}}/v{{version}}/suppliers +GET {{baseUrl}}/v{{version}}/customers          # Customers – card, contacts, datafields 
-GET {{baseUrl}}/v{{version}}/contacts +GET {{baseUrl}}/v{{version}}/suppliers          # Suppliers – card, bank accounts 
-GET {{baseUrl}}/v{{version}}/items +GET {{baseUrl}}/v{{version}}/contacts           # Contact persons – customer contacts 
-GET {{baseUrl}}/v{{version}}/itemclasses +GET {{baseUrl}}/v{{version}}/items              # Items – card, prices, packages 
-GET {{baseUrl}}/v{{version}}/priceformulas +GET {{baseUrl}}/v{{version}}/itemclasses        # Item classes – accounts, VAT settings 
-GET {{baseUrl}}/v{{version}}/stocklevels +GET {{baseUrl}}/v{{version}}/priceformulas      # Price formulas – discounts, campaigns 
-GET {{baseUrl}}/v{{version}}/stocklevels_sn +GET {{baseUrl}}/v{{version}}/stocklevels        # Stock levels – quantity per warehouse 
-GET {{baseUrl}}/v{{version}}/allocations +GET {{baseUrl}}/v{{version}}/stocklevels_sn     # Stock levels – per serial number 
-GET {{baseUrl}}/v{{version}}/accounts +GET {{baseUrl}}/v{{version}}/allocations        # Allocations – reserved and incoming quantities 
-GET {{baseUrl}}/v{{version}}/transactions +GET {{baseUrl}}/v{{version}}/accounts           # Chart of accounts – GL accounts 
-GET {{baseUrl}}/v{{version}}/deleted +GET {{baseUrl}}/v{{version}}/transactions       # GL transactions – debit/credit rows 
-GET {{baseUrl}}/v{{version}}/financial_budgets +GET {{baseUrl}}/v{{version}}/deleted            # Deletion log – deleted records 
-GET {{baseUrl}}/v{{version}}/events +GET {{baseUrl}}/v{{version}}/financial_budgets  # Financial budgets – budget rows 
-GET {{baseUrl}}/v{{version}}/receipts +GET {{baseUrl}}/v{{version}}/events             # Events – CRM events and tasks 
-GET {{baseUrl}}/v{{version}}/deliveries +GET {{baseUrl}}/v{{version}}/receipts           # Incoming payments – paid sales invoices 
-GET {{baseUrl}}/v{{version}}/movements +GET {{baseUrl}}/v{{version}}/deliveries         # Deliveries – shipped goods rows 
-GET {{baseUrl}}/v{{version}}/objects +GET {{baseUrl}}/v{{version}}/movements          # Stock movements – warehouse transfers 
-GET {{baseUrl}}/v{{version}}/projects +GET {{baseUrl}}/v{{version}}/objects            # Objects – accounting dimensions 
-GET {{baseUrl}}/v{{version}}/resources +GET {{baseUrl}}/v{{version}}/projects           # Projects – card and rows 
-GET {{baseUrl}}/v{{version}}/sales_contracts +GET {{baseUrl}}/v{{version}}/resources          # Resources – work and time entries 
-GET {{baseUrl}}/v{{version}}/replacementlogs +GET {{baseUrl}}/v{{version}}/sales_contracts    # Sales contracts – recurring billing terms 
-GET {{baseUrl}}/v{{version}}/users +GET {{baseUrl}}/v{{version}}/replacementlogs    # Replacement log – code replacement history 
-GET {{baseUrl}}/v{{version}}/recipes +GET {{baseUrl}}/v{{version}}/users              # Users – user and employee cards 
-GET {{baseUrl}}/v{{version}}/nettings +GET {{baseUrl}}/v{{version}}/recipes            # Recipes – production bills of materials 
-GET {{baseUrl}}/v{{version}}/usagelogs +GET {{baseUrl}}/v{{version}}/nettings           # Nettings – offset documents 
 +GET {{baseUrl}}/v{{version}}/usagelogs          # API usage log – request history 
 +GET {{baseUrl}}/v{{version}}/expenses           # Expense reports – employee expenses 
 +GET {{baseUrl}}/v{{version}}/approvals          # Approvals – document approval workflow 
 +GET {{baseUrl}}/v{{version}}/absences           # Absences – employee leave records 
 +GET {{baseUrl}}/v{{version}}/assets             # Assets – devices and equipment 
 +GET {{baseUrl}}/v{{version}}/customer_assets    # Customer assets – customer-owned devices 
 +GET {{baseUrl}}/v{{version}}/stocks             # Stocks – warehouse register and settings 
 +GET {{baseUrl}}/v{{version}}/wage_calculations  # Wage Calculations – calculated wages for employees
 </code> </code>
 +This list is general. The resources available to your key are listed in openapi.json.
  
-Postman collection can be downloaded here: e: {{:et:toomas20260702-122402.json|Directo API postman collection}}+Postman collection can be downloaded here: e: [[:et:api_direct:postman|POSTMAN]]
  
  
Rida 590: Rida 645:
 **Objective:** Keep customer data synchronized between Directo and your CRM **Objective:** Keep customer data synchronized between Directo and your CRM
  
-  * **Step 1:** Fetch changed customers ''GET /customers?ts={last_sync}''+  * **Step 1:** Fetch changed customers ''GET /customers?ts=>{last_sync}''
   * **Step 2:** Sync to CRM (Create/Update)   * **Step 2:** Sync to CRM (Create/Update)
-  * **Step 3:** Fetch deleted customers ''GET /deleted?resource_type=customers&ts={last_sync}''+  * **Step 3:** Fetch deleted customers ''GET /deleted?document=klient&ts=>{last_sync}''
   * **Step 4:** Remove deleted customers from CRM   * **Step 4:** Remove deleted customers from CRM
  
Rida 674: Rida 729:
   * Support for major resources: items, customers, orders, invoices, stock levels   * Support for major resources: items, customers, orders, invoices, stock levels
   * JSON/XML support & ERP-style filtering   * JSON/XML support & ERP-style filtering
 +  * added API discovery (openapi.json) 23.09.2026
  
 ===== 🔒 Security & Compliance ===== ===== 🔒 Security & Compliance =====
Rida 715: Rida 771:
   * **Tip 2:** Test filters in ERP interface first.   * **Tip 2:** Test filters in ERP interface first.
   * **Tip 3:** Build filter strings programmatically.   * **Tip 3:** Build filter strings programmatically.
 +  * **Tip 4:** Use openapi.json to discover available fields and filters. It is faster than an unfiltered request, downloads no data and includes field types.
  
 **Example (Python):** **Example (Python):**
Rida 762: Rida 819:
 ==== Essential Endpoints ==== ==== Essential Endpoints ====
 <code> <code>
-Items:        GET /v1/items +API description GET /v1/openapi.json  
-Customers:    GET /v1/customers +Items:          GET /v1/items 
-Orders:       GET /v1/orders +Customers:      GET /v1/customers 
-Invoices:     GET /v1/invoices +Orders:         GET /v1/orders 
-Stock:        GET /v1/stocklevels +Invoices:       GET /v1/invoices 
-Deletions:    GET /v1/deleted+Stock:          GET /v1/stocklevels 
 +Deletions:      GET /v1/deleted
 </code> </code>
  
et/api_direct.1783409480.txt.gz · Viimati muutnud: 2026/07/07 10:31 persoon toomas
Donate Powered by PHP Valid HTML5 Valid CSS Driven by DokuWiki