sk_api_schema 0.10.6 → 0.11.0

data/json/v2.0/pdf_template.json

@@ -1,30 +1,36 @@
-{ "type":"object",
+{
+  "$schema": "http://json-schema.org/draft-04/schema#",
+  "type":"object",
   "title": "pdf_template",
-  "name": "pdf_template",
   "description":"An PDF template. For now this is a read-only resource ONLY returning your own templates. It fits the most important use-case: A user can select a print template.",
   "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
     },
     "name":{
       "description": "Name of the template as shown to the user.",
-      "required":true,
       "type":"string",
       "maxLength": 50
     },
     "description":{
       "description": "Additional information about the template.",
       "type":"string",
-      "format":"text"
+      "format":"string"
     },
     "kind":{
       "description": "Kind of object the template can be used for.",
-      "required":true,
       "enum": ["invoice", "estimate", "credit_note", "payment_reminder", "order"],
       "type":"string"
     },
@@ -36,13 +42,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"
     },
     "team_id":{

data/json/v2.0/product.json

@@ -1,12 +1,21 @@
-{ "type":"object",
+{
+  "$schema": "http://json-schema.org/draft-04/schema#",
+  "type":"object",
   "title": "product",
-  "name": "product",
   "description": "A product in SK",
+  "required": ["price", "name"],
   "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
@@ -19,13 +28,12 @@
     "name":{
       "description": "The name of the product",
       "type":"string",
-      "required":true,
       "maxLength": 50
     },
     "description":{
       "description": "Product description",
       "type":"string",
-      "format":"text"
+      "format":"string"
     },
     "tag_list":{
       "description": "Space separated list of tags. Are split and saved as Tag objects on create, update.",
@@ -33,8 +41,7 @@
     },
     "price":{
       "description": "Net price of a single product. Max 6 decimal places.",
-      "type":"number",
-      "required":true
+      "type":"number"
     },
     "cost":{
       "description": "Cost price of a single product. Max 6 decimal places.",
@@ -57,13 +64,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"
     },
     "team_id":{
@@ -71,10 +78,6 @@
       "type":"string",
       "maxLength": 22,
       "minLength":22
-    },
-    "lock_version":{
-      "description": "Increased on every edit, so SK can detect/prevent a concurrent edit by another user. First save wins.",
-      "type":"integer"
     }
   },
   "links":[

data/json/v2.0/recurring.json

@@ -1,12 +1,21 @@
-{ "type":"object",
+{
+  "$schema": "http://json-schema.org/draft-04/schema#",
+  "type":"object",
   "title": "recurring",
-  "name": "recurring",
   "description": "An recurring is used as an template for new invoices.",
+  "required": ["number", "date", "final_date", "frequency" ],
   "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
@@ -14,7 +23,6 @@
     "number":{
       "description": "Unique name to identify the document. Unlike all other document this one has no number schema and not auto assign",
       "type":"string",
-      "required":true,
       "maxLength": 50
     },
     "address_field":{
@@ -24,8 +32,7 @@
     "date":{
       "description": "First date the recurring is issued. Not allowed to be in the past. YYYY-MM-DD",
       "format":"date",
-      "type":"string",
-      "required":true
+      "type":"string"
     },
     "due_days":{
       "description": "Used to calculate the due date of the recurring. Useless if date and due date are present.",
@@ -34,14 +41,12 @@
     "final_date":{
       "description": "The last date the recurring is executed. YYYY-MM-DD",
       "format":"date",
-      "type":"string",
-      "required":true
+      "type":"string"
     },
     "frequency":{
       "description": "Recurring frequency",
       "enum":["yearly", "monthly", "weekly", "quarterly", "biweekly", "sixmonthly"],
-      "type":"string",
-      "required":true
+      "type":"string"
     },
     "payment_method":{
       "description": "How the document is being payed. Used in new payments.",
@@ -61,12 +66,12 @@
     "notes_before":{
       "description": "Notes shown before the line items. Normally contains salutation and other introductional information. SK placeholders can be used.",
       "type":"string",
-      "format":"text"
+      "format":"string"
     },
     "notes_after":{
       "description": "Notes shown after the line items. Can contain information about payments, bank account or a thank-you message. SK placeholders can be used.",
       "type":"string",
-      "format":"text"
+      "format":"string"
     },
     "tag_list":{
       "description": "Space separated list of tags. Are split and saved as Tag objects on create, update.",
@@ -98,23 +103,11 @@
       "type":"string",
       "enum":["FRST","OOFF","RCUR","FNAL"]
     },
-    "client":{
-      "description": "DEPRECATED: use contact",
-      "readonly":true,
-      "type":"object",
-      "properties":{"$ref":"./client.json#properties"}
-    },
-    "client_id":{
-      "description": "DEPRECATED: use contact_id",
-      "type":"string",
-      "maxLength": 22,
-      "minLength":22
-    },
     "contact":{
       "description": "The contact for the document. Use contact_id field to set a contact.",
-      "readonly":true,
+      "readOnly":true,
       "type":"object",
-      "properties":{"$ref":"./contact.json#properties"}
+      "$ref":"./contact.json#"
     },
     "contact_id":{
       "description": "The contact uuid. When assigning a contact its language, currency, address_field (due days, cash discount) values are used for the document if those doc-fields are not set.",
@@ -124,74 +117,83 @@
     },
     "team_id":{
       "description": "A team uuid taken from the contact. If set only the team and its parent teams can see the record.",
-      "readonly" :true,
+      "readOnly" :true,
       "type":"string",
       "maxLength": 22,
       "minLength":22
     },
-    "line_items":{
-      "description": "DEPRECATED use items",
-      "type":"array",
-      "properties":{"$ref":"./line_item.json#properties"}
-    },
     "items":{
-      "description": "Items for the document. Access items of all types including divider and sub_total items. GOTCHAs when using items instead of line_items: You MUST set the type field(CamelCasesItem class name) on each item. You cannot use both, the line_items array is stronger for backward compat.",
+      "description": "Items for the document, including divider and sub_total items. You MUST set the type field(CamelCasedItem class name) on each item on creation.",
       "type":"array",
-      "default": "any",
       "minItems": 0,
-      "items": [{ "$ref": "./line_item.json#properties"},
-                { "$ref":  "./divider_item.json#properties"},
-                { "$ref": "./sub_total_item.json#properties"}]
+      "items": {
+        "type" : "object",
+        "anyOf" : [
+          {
+            "title": "line_item",
+            "$ref": "./line_item.json#"
+          },
+          {
+            "title": "divider_item",
+            "$ref": "./divider_item.json#"
+          },
+          {
+            "title": "sub_total_item",
+            "$ref": "./sub_total_item.json#"
+          }
+        ]
+      }
     },
     "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"
     },
     "lock_version":{
-      "description": "Auto-incremented to prevent concurrent updates. First save wins and increments version. ",
+      "description": "Auto-incremented to prevent concurrent updates. First save wins and increments version.",
+      "readOnly":true,
       "type":"integer"
     },
     "gross_total":{
       "description": "Gross total of all line items, 2 decimals places",
-      "readonly":true,
+      "readOnly":true,
       "type":"number"
     },
     "tax_total":{
       "description": "Tax total, 2 decimals places",
-      "readonly":true,
+      "readOnly":true,
       "type":"number"
     },
     "net_total":{
       "description": "Net total, 2 decimals places",
-      "readonly":true,
+      "readOnly":true,
       "type":"number"
     },
     "net_total_base":{
       "description": "Net total, 6 decimal places incl. discount",
-      "readonly":true,
+      "readOnly":true,
       "type":"number"
     },
     "cost_total":{
       "description": "Cost total of all line items, 2 decimals places in document currency.",
-      "readonly":true,
+      "readOnly":true,
       "type":"number"
     },
     "gross_margin_total":{
       "description": "Total gross margin across all line items. Calculated from net_total-cost_total.",
-      "readonly":true,
+      "readOnly":true,
       "type":"number"
     },
     "gross_margin_pct":{
       "description": "Percentage of gross profit to cost of items sold. Calculated from gross_margin_total/net_total*100",
-      "readonly":true,
+      "readOnly":true,
       "type":"number"
     },
     "pdf_template_id":{
@@ -211,6 +213,12 @@
       "default": null,
       "type": "string",
       "enum":["email"]
+    },
+    "tax_exemption_id":{
+      "description": "ID of a tax exemption. When set all item taxes are omitted.",
+      "type":"string",
+      "maxLength": 22,
+      "minLength":22
     }
   },
   "links":[
@@ -269,11 +277,6 @@
           "description": "A list of language codes, comma separated",
           "type" : "string"
         },
-        "filter[client_ids]":{
-          "title" : "Clients",
-          "description": "DEPRECATED use contact_ids",
-          "type" : "string"
-        },
         "filter[contact_ids]":{
           "title" : "Contacts",
           "description": "Find objects belonging to a single or a list of contacts, use ids comma separated.",
@@ -331,10 +334,10 @@
       "href": "invoices?filter[recurring_ids]={id}"
     },
     { "rel": "attachments",
-      "href": "recurrings/{id}/attachments"
+      "href": "attachments?filter[related_object_ids]={id}"
     },
     { "rel": "comments",
-      "href": "recurrings/{id}/comments"
+      "href": "comments?filter[related_object_ids]={id}"
     }
   ]
 }

data/json/v2.0/sub.json

@@ -1,19 +1,27 @@
-{"type":"object",
+{
+  "$schema": "http://json-schema.org/draft-04/schema#",
+  "type":"object",
   "title": "sub",
-  "name": "sub",
   "description": "Subscribe to push notifications(webhooks) about object livecycle events like new, update or delete. Only returns subscription for the current app, so you MUST be using oAuth. When a user removes your app its subs are also deleted. <br/>To register you must supply <br/>- callback_url: receives a base64 encode string containing a JSON object with the object in it's latest state, the user_id & subdomain, company_id, hmac-signed with your app secret.<br/>- channel: defining the event, made up of the SINGULAR object name and the action: invoice.delete, payment.new<br/> - register auth_permissions: An app MUST request non-api permissions f.ex.: clients:create. Perms(on company,app,user,team) are checked before any publishing, so if a user cannot create clients in the interface, his apps will not receive any callbacks.",
+  "required": ["channel", "callback_url"],
   "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
     },
     "channel":{
       "description": "The channel to which to subscribe. See available at subs/channels.",
-      "required":true,
       "type":"string",
       "maxLength": 100
     },
@@ -21,19 +29,18 @@
       "description": "An url receiving the notification. The url MUST be within the url of the current app and receives a POST with a single signed_request parameter containing an base64 encoded JSON object.",
       "type":"string",
       "format":"uri",
-      "required":true,
       "maxLength": 100
     },
     "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/sub_total_item.json

@@ -1,20 +1,21 @@
-{ "type":"object",
+{
+  "$schema": "http://json-schema.org/draft-04/schema#",
+  "type":"object",
   "title": "sub_total_item",
-  "name": "sub_total_item",
   "description": "A sub-total item shows a sum of the previous line items, e.g. to distinguish hardware and service costs on a document.",
+  "required" : ["position"],
   "properties":{
     "id":{
       "description":"Unique identifier - UUID",
       "identity":true,
-      "readonly":true,
+      "readOnly":true,
       "type":"string",
       "maxLength": 22,
       "minLength":22
     },
     "position":{
       "description": "Required since items are sorted by position.",
-      "type":"integer",
-      "required":true
+      "type":"integer"
     },
     "name":{
       "description": "Title of the sub-total e.g. Hardware total",
@@ -29,23 +30,23 @@
     "net_total":{
       "description": "Net sub-total",
       "type":"number",
-      "readonly":true
+      "readOnly":true
     },
     "gross_total":{
       "description": "Gross sub-total",
       "type":"number",
-      "readonly":true
+      "readOnly":true
     },
    "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"
     },
     "_destroy":{