sk_api_schema 0.10.6 → 0.11.0

data/json/v2.0/address.json

@@ -1,19 +1,20 @@
-{ "type":"object",
+{
+  "$schema": "http://json-schema.org/draft-04/schema#",
+  "type":"object",
   "title": "address",
-  "name": "address",
   "description":"An address in SK is maintained within it's parent object(client, company). The first address(default_address) is used inside the address field of new documents. With multiple addresses sorting(first) is done by date, newest first. So if you add a new adddress it will be the new default one. See order and type property for details about ordering and accessing parcel work or home addresses.",
+  "required": ["city"],
   "properties":{
     "id":{
       "description":"Unique identifier - UUID",
       "identity":true,
-      "readonly":true,
+      "readOnly":true,
       "type":"string",
       "maxLength": 22,
       "minLength":22
     },
     "city":{
       "description": "City for the address. Must at least be present for an address.",
-      "required":true,
       "type":"string",
       "maxLength": 100
     },
@@ -50,13 +51,13 @@
     "created_at":{
       "description": "Date the object was created in SK. Never changes afterwards",
       "format":"date-time",
-      "readonly":true,
+      "readOnly":true,
       "type":"string"
     },
     "updated_at":{
       "description": "Date the object was edited in SK.",
       "format":"date-time",
-      "readonly":true,
+      "readOnly":true,
       "type":"string"
     },
     "address_type":{

data/json/v2.0/attachment.json

@@ -1,54 +1,55 @@
-{ "type":"object",
+{
+  "$schema": "http://json-schema.org/draft-04/schema#",
+  "type":"object",
   "title": "attachment",
-  "name": "attachment",
   "description":"An file attachment",
+  "required": ["related_object_type", "related_object_id"],
   "properties":{
     "id":{
       "description": "uuid of the object.",
       "identity":true,
-      "readonly":true,
+      "readOnly":true,
+      "type":"string",
+      "maxLength": 22,
+      "minLength":22
+    },
+    "company_id":{
+      "description":"Company",
+      "readOnly":true,
       "type":"string",
       "maxLength": 22,
       "minLength":22
     },
     "filename":{
       "description": "The filename as set when uploaded",
-      "readonly":true,
+      "readOnly":true,
       "type":"string",
       "maxLength": 255
     },
     "disk_filename":{
       "description": "Unique filename set by SK",
-      "readonly":true,
+      "readOnly":true,
       "type":"string",
       "maxLength": 255
     },
-    "url":{
-      "description": "DEPRECATED use attachments/ID/download",
-      "readonly":true,
-      "type":"string",
-      "format": "uri"
-    },
     "related_object_type":{
       "description": "Object type of the attachment parent. A base class name: Document(for invoice, credit_note) Contact, Message(for email), Template(for email, pdf template)",
-      "required":true,
       "type":"string"
     },
     "related_object_id":{
       "description": "uuid of the attachment parent object.",
-      "required":true,
       "type":"string",
       "maxLength": 22,
       "minLength":22
     },
     "content_type":{
       "description": "Auto detected on upload. Might not always reflect the real content type",
-      "readonly":true,
+      "readOnly":true,
       "type":"string"
     },
     "size":{
       "description": "Filesize in kb. Auto detected on upload.",
-      "readonly":true,
+      "readOnly":true,
       "type":"integer"
     },
     "is_signed":{
@@ -58,7 +59,7 @@
     "created_at":{
       "description": "Date the object was created in SK. Never changes afterwards",
       "format":"date-time",
-      "readonly":true,
+      "readOnly":true,
       "type":"string"
     },
     "team_id":{

data/json/v2.0/auth_permission.json

@@ -1,12 +1,13 @@
-{"type":"object",
+{
+  "$schema": "http://json-schema.org/draft-04/schema#",
+  "type":"object",
   "title": "auth_permission",
-  "name": "auth_permission",
   "description": "A Permission authorises someone to execute actions(grants privileges) in the scope of a context. The context is a resource f.ex: clients, and the privileges a group of actions like: index, show, edit, update. A permission to read invoices has the context: invoices and as privileges: index,show.",
   "properties":{
     "id":{
       "description":"Unique identifier - UUID",
       "identity":true,
-      "readonly":true,
+      "readOnly":true,
       "type":"string",
       "maxLength": 22,
       "minLength":22
@@ -23,14 +24,14 @@
     },
     "context_name":{
       "description": "The context for the permission, being a resource: clients, emails",
-      "readonly":true,
+      "readOnly":true,
       "type":"string",
       "maxLength": 255
     },
     "privilege_list":{
       "description": "A permission has many privileges which define the actions someone can execute. Such actions are resource methods like index, update, edit, show",
       "type":"string",
-      "readonly":true,
+      "readOnly":true,
       "maxLength": 255
     }
   },

data/json/v2.0/comment.json

@@ -1,29 +1,35 @@
-{ "type":"object",
+{
+  "$schema": "http://json-schema.org/draft-04/schema#",
+  "type":"object",
   "title": "comment",
-  "name": "comment",
   "description":"An comment in SK must always be related to an object.",
+  "required": ["related_object_type", "related_object_id", "text"],
   "properties":{
     "id":{
       "description":"Unique identifier - UUID",
       "identity":true,
-      "readonly":true,
+      "readOnly":true,
+      "type":"string",
+      "maxLength": 22,
+      "minLength":22
+    },
+    "company_id":{
+      "description":"Company",
+      "readOnly":true,
       "type":"string",
       "maxLength": 22,
       "minLength":22
     },
     "text":{
       "description": "The comment himself.",
-      "required":true,
       "type":"string"
     },
     "related_object_type":{
       "description": "Object type of the comments parent. Is the camelcased base class name: Document for invoice, credit_note, contact",
-      "required":true,
       "type":"string"
     },
     "related_object_id":{
       "description": "uuid of the comments parent object.",
-      "required":true,
       "type":"string",
       "maxLength": 22,
       "minLength":22
@@ -31,18 +37,18 @@
     "created_at":{
       "description": "Date the object was created in SK. Never changes afterwards",
       "format":"date-time",
-      "readonly":true,
+      "readOnly":true,
       "type":"string"
     },
     "updated_at":{
       "description": "Date the object was edited in SK.",
       "format":"date-time",
-      "readonly":true,
+      "readOnly":true,
       "type":"string"
     },
     "team_id":{
       "description": "A team uuid taken from the related object. If set only the team and its parent teams can see the record.",
-      "readonly" :true,
+      "readOnly" :true,
       "type":"string",
       "maxLength": 22,
       "minLength":22

data/json/v2.0/company.json

@@ -1,12 +1,13 @@
-{ "type":"object",
+{
+  "$schema": "http://json-schema.org/draft-04/schema#",
+  "type":"object",
   "title": "company",
-  "name": "company",
   "description": "A company is the main entity, so any data belongs to a company. It is identified by the current subdomain and cannot be edited via API atm",
   "properties":{
     "id":{
       "description":"Unique identifier - UUID",
       "identity":true,
-      "readonly":true,
+      "readOnly":true,
       "type":"string",
       "maxLength": 22,
       "minLength":22
@@ -36,7 +37,7 @@
       "description": "Link to a company's SalesKing account.",
       "type":"string",
       "format":"uri",
-      "readonly":true
+      "readOnly":true
     },
     "time_zone":{
       "description": "Default time zone, used for new users",
@@ -45,7 +46,6 @@
     },
     "email":{
       "description": "Email address",
-      "required":true,
       "type":"string",
       "maxLength": 100
     },
@@ -77,7 +77,10 @@
     "addresses":{
       "description": "A company can have many addresses, sorted by date descending(new first). Default address used in placeholder is the most recent one.",
       "type":"array",
-      "properties" : {"$ref":"./addresses.json#properties"}
+      "items": {
+        "type": "object",
+        "$ref": "./address.json#"
+      }
     },
     "vat_number":{
       "description": "VAT number, for a company entitled to pay value added taxes.",
@@ -122,13 +125,13 @@
     "created_at":{
       "description": "Date the record was created in SK. Never changes afterwards.",
       "format":"date-time",
-      "readonly":true,
+      "readOnly":true,
       "type":"string"
     },
     "updated_at":{
       "description": "Last date when the record was edited.",
       "format":"date-time",
-      "readonly":true,
+      "readOnly":true,
       "type":"string"
     }
   },

data/json/v2.0/contact.json

@@ -1,12 +1,21 @@
-{"type":"object",
+{
+  "$schema": "http://json-schema.org/draft-04/schema#",
+  "type":"object",
   "title": "contact",
-  "name": "contact",
-  "description": "A contact can be a lead, client or supplier, depending on its type field. Use the filter[type] parameter to show only contacts of a kind. Use this resource instead of clients, as they are deprecated and dropped in the future.",
+  "description": "A contact can be a lead, client or supplier, depending on its type field. Use the filter[type] parameter to show only contacts of a kind.",
+  "required" : ["type"],
   "properties":{
     "id":{
       "description":"Unique identifier - UUID",
       "identity":true,
-      "readonly":true,
+      "readOnly":true,
+      "type":"string",
+      "maxLength": 22,
+      "minLength":22
+    },
+    "company_id":{
+      "description":"Company",
+      "readOnly":true,
       "type":"string",
       "maxLength": 22,
       "minLength":22
@@ -20,9 +29,8 @@
     "type":{
       "description": "Type of contact",
       "enum":["Client", "Lead", "Supplier"],
-      "required" : true,
       "type":"string",
-      "maxLength": 50
+      "default":"Lead"
     },
     "is_employee":{
       "description": "An employee gets number, organisation, tax and vat_number from its parent. If you set any of these, they are overwritten. When changing a parent-contact the fields on his direct child-employees are updated too.",
@@ -30,18 +38,17 @@
       "default": false
     },
     "number":{
-      "description": "Unique number, auto-created by SK for new contacts(client, supplier) without number.",
+      "description": "Unique number, auto-set, if empty, for new Client and Suppliers from SK's contact number schema.",
       "type":"string",
       "maxLength": 50
     },
     "organisation":{
-      "description": "Name of a company. This or lastname must be present",
-      "required" : true,
+      "description": "Name of a company. This or lastname MUST be present",
       "type":"string",
       "maxLength": 100
     },
     "last_name":{
-      "description": "Last name of a person. At least this or the organisation field must be filled for new records",
+      "description": "Last name of a person. This or the organisation field must be present for new records",
       "type":"string",
       "maxLength": 50
     },
@@ -58,7 +65,7 @@
     "notes":{
       "description": "Notes for a contact. For day to day information you should use comments instead.",
       "type":"string",
-      "format": "text"
+      "format": "string"
     },
     "position":{
       "description": "Position of a person in a company.",
@@ -102,13 +109,13 @@
     "created_at":{
       "description": "Date the record was created in SK. Never changes afterwards.",
       "format":"date-time",
-      "readonly":true,
+      "readOnly":true,
       "type":"string"
     },
     "updated_at":{
       "description": "Last date when the record was edited.",
       "format":"date-time",
-      "readonly":true,
+      "readOnly":true,
       "type":"string"
     },
     "language":{
@@ -179,6 +186,7 @@
     },
     "lock_version":{
       "description": "Increased on every edit, so SK can detect/prevent a concurrent edit by another user. First save wins.",
+      "readOnly":true,
       "type":"integer"
     },
     "cash_discount":{
@@ -186,18 +194,21 @@
       "type":"number"
     },
     "due_days":{
-      "description": "Default due days for new invoices.",
+      "description": "Default due days for new documents.",
       "type":"integer"
     },
     "address_field":{
       "description": "Returns the address field used on new docs. Consist of Organisation name and default(first) address",
-      "readonly":true,
+      "readOnly":true,
       "type":"string"
     },
     "addresses":{
       "description": "A client can have many addresses, sorted by date descending(new first). Default address is the most recent one.",
-      "type":"array",
-      "properties" : {"$ref":"./address.json#properties"}
+      "type": "array",
+      "items": {
+        "type": "object",
+        "$ref" : "./address.json#"
+      }
     },
     "team_id":{
       "description": "A team uuid. If set only the team and its parent teams can see the record. The team is set for all new documents and related objects like comments, attachments, emails. When changed ALL related objects are updated with the new team!!",
@@ -233,8 +244,14 @@
     },
     "expected_revenue":{
       "description": "Product of the probability and sales potential. e.g how much of the sales_potential can we get?",
-      "readonly":true,
+      "readOnly":true,
       "type":"number"
+    },
+    "tax_exemption_id":{
+      "description": "ID of a tax exemption. New documents inherit the tax exemption and will be created without any taxes.",
+      "type":"string",
+      "maxLength": 22,
+      "minLength":22
     }
   },
   "links":[
@@ -364,55 +381,34 @@
       "method": "POST"
     },
     { "rel": "documents",
-      "href": "contacts/{id}/documents"
+      "href": "documents?filter[contact_ids]={id}"
     },
     { "rel": "attachments",
-      "href": "contacts/{id}/attachments"
+      "href": "attachments?filter[related_object_ids]={id}"
     },
     { "rel": "invoices",
-      "href": "contacts/{id}/invoices"
+      "href": "invoices?filter[contact_ids]={id}"
     },
     { "rel": "estimates",
-      "href": "contacts/{id}/estimates"
+      "href": "estimates?filter[contact_ids]={id}"
     },
     { "rel": "orders",
-      "href": "contacts/{id}/orders"
+      "href": "orders?filter[contact_ids]={id}"
     },
     { "rel": "credit_notes",
-      "href": "contacts/{id}/credit_notes"
+      "href": "credit_notes?filter[contact_ids]={id}"
     },
     { "rel": "recurrings",
-      "href": "contacts/{id}/recurrings"
+      "href": "recurrings?filter[contact_ids]={id}"
     },
     { "rel": "payment_reminders",
-      "href": "contacts/{id}/payment_reminders"
+      "href": "payment_reminders?filter[contact_ids]={id}"
     },
     { "rel": "comments",
-      "href": "contacts/{id}/comments"
+      "href": "comments?filter[related_object_ids]={id}"
     },
     { "rel": "emails",
-      "href": "contacts/{id}/emails"
-    },
-    { "rel": "emails create",
-      "href": "contacts/{id}/emails",
-      "method": "POST",
-      "properties" : {
-        "template_id":{
-          "title" : "Template",
-          "description": "UUID of an email template to use. If present template fields like subject, body, attachments are used for the current email.",
-          "type":"string",
-          "maxLength": 22,
-          "minLength":22
-        },
-        "send":{
-          "title" : "Send email",
-          "description": "Schedule email for sending. Omit this parameter or set value to 0 or false(String or Integer) to keep email as draft."
-        },
-        "archived_pdf":{
-          "title" : "Attach archived pdf",
-          "description": "Adds the archived pdf from the related resource(if it has one)."
-        }
-      }
+      "href": "emails?filter[related_object_ids]={id}"
     }
   ]
 }