EMDI web API
2.0.1 · openapi.yaml · Swagger
Guide below. For Authorize / Try it out, open the interactive documentation (Swagger) in a new tab. JSON field catalogue: EMDI web API field analysis.
Start here (simple guide)
This API lets your program talk to EMDI web: contacts, items, calendar events, and purchase/sales documents.
There is one base path: /apps/api/. You choose the resource and action with the URL.
1. What you need before calling
- An EMDI web product with the API package enabled.
- Your EMDI web username (the same login you use in the browser).
- An HTTP key from EMDI web: Settings → Purchases/Sales → API (copy the key; keep it secret).
- After changing package or permissions, sign in again in EMDI web so the change applies.
If the package is off, or the key/user is wrong, the API answers with an error (not with data).
2. How every request works
| Piece | What to send |
|---|---|
| Auth | Always ?user=YOUR_USER&key=YOUR_HTTPKEY (or header X-API-Key) |
| List | GET /apps/api/list/{type}.json |
| Get | GET /apps/api/{type}/{id}.json |
| Save | POST /apps/api/save/{type}.json + JSON body |
| Delete | DELETE /apps/api/{type}/{id}.json |
{type} is the resource name (contacts, items, calendar, documents, or a lookup name).
Tiny example (list document types)
|
1 |
curl -sS "https://web.sbzsystems.com/apps/api/list/doc_types.json?user=YOUR_USER&key=YOUR_HTTPKEY" |
Tiny example (read one calendar event)
|
1 |
curl -sS "https://web.sbzsystems.com/apps/api/calendar/5.json?user=YOUR_USER&key=YOUR_HTTPKEY" |
Tiny example (save a contact)
|
1 2 3 |
curl -sS -X POST "https://web.sbzsystems.com/apps/api/save/contacts.json?user=YOUR_USER&key=YOUR_HTTPKEY" \ -H "Content-Type: application/json; charset=utf-8" \ -d '{"id":0,"data":{"code":"C001","name":"John","surname":"Doe"}}' |
Success answer (always this shape)
|
1 2 3 4 5 |
{ "success": true, "id": 5, "data": { } } |
Error answer
|
1 2 3 4 5 6 7 8 |
{ "success": false, "error": { "code": "validation", "message": "id is required", "field": "id" } } |
Common error.code values: auth, validation, not_found, duplicate, in_use, locked_mydata, package_disabled, rate_limited, server.
3. Resources
Lookups (lists of choices)
GET /apps/api/list/{type}.json only.
{type} one of: doc_types, vat_rates, users, contacts_relations, measurement_units, categories, subcategories, payment_methods, calendar_types, cashiers_positions
Main data (CRUD)
| type | Meaning |
|---|---|
contacts |
Customers / suppliers / other contacts |
items |
Products / services |
calendar |
Appointments |
documents |
Purchase / sales documents |
| Action | Method + URL |
|---|---|
| list | GET /apps/api/list/{type}.json (filters as query: limit, offset, …) |
| get | GET /apps/api/{type}/{id}.json |
| save | POST /apps/api/save/{type}.json (id: 0 create, or match: "code" upsert) |
| delete | DELETE /apps/api/{type}/{id}.json |
4. Useful details
- Rate limit: max 60 calls per minute per user + IP.
- List page size:
limitdefaults to 50, maximum 250 (useoffsetfor the next page). - Contacts
balance: like the Balances report (debit − credit). Optionaldate_from/date_toon get/list. - Contacts list search:
?name=on trimmedOnoma+' '+Epiueto;?company=on trimmedEpvnymia— case- and accent-insensitive. Exact if you omit%; add%yourself (e.g.name=PETER MARKS,name=PETER%,company=%SBZ%). Also exactcode,vat_number, plusactive,modified_since. - On save: names like
city,relation,unitcan auto-create. Users and document types must already exist. - Documents: all
pvlhseiscolumns plusgrammeslines inlines. get always includes lines; on list use?include_lines=1. List filters:?series=(Seira, same trim/case/accent/%rules as contactname/company),?number=exact (Ariumospar),?related_docs=on trimmedSxetika. Totals use FirebirdCALC_LINE_*. No myDATA upload from this API. - myDATA lock / in_use: locked documents cannot change; contacts/items in use cannot delete.
- Field analysis: EMDI web API field analysis — every JSON key per resource.