sk_api_schema 0.10.5 → 0.10.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 9132c50c6ac95daba55a76fec7ef54eb3b9e2205
-  data.tar.gz: 435a1bb9244473eb914c395dbca125a6e7576ca2
+  metadata.gz: abde1b5b42fecd8924f6807b99891be589fd17a0
+  data.tar.gz: 397c6504cd713e94ced42ac68b45951fe9fdeea3
 SHA512:
-  metadata.gz: 93e7a0259df3f37806ddf5798c404f5101bef772fd4101e399386d3729282a64242ea937bee0ce9c28c92c2b978e1eb5d5d2ec3aadb6045623f6a34d94e0953d
-  data.tar.gz: 9d860e071300a8f3178617fd814b6d2ca9fbdf0da0cfc8c41ff23b45563c885d4f999605cedf7a5806c0ea12e7395f46e59f35144b1b0573cb7b624745b82c12
+  metadata.gz: 25bfc2130cb635266c2e9775797881bfb68c2b4e61c72babaab55405441507545746e3598a35c6f20dbf8b83a7d2b1639ada0e8281825f90b2804334f2131df2
+  data.tar.gz: e6e78e2f97eace77224d1f552155912ab29f7355338fe0502b5b0322c7f847a249f477a6b9de858902347ddd843bd0ea9b3471ed2f0f97ba785614dc283e972f

data/CHANGELOG.md

@@ -1,7 +1,12 @@
 # SalesKing API Changelog
 
 See [commit messages](https://github.com/salesking/sk_api_schema/commits/) for details.
-Also sign up to our [Developer Newsletter](http://www.salesking.eu/dev/newsletter/) to stay up-to-date !!!
+Also sign up to our [Developer Newsletter](http://www.salesking.eu/dev/newsletter/) to stay up-to-date!
+
+##2015-10
+
+* Update description to clarify number field decimal places length
+* Contact fix lead_ref/lead_source to be strings
 
 ##2014-08
 

data/README.rdoc

@@ -27,7 +27,7 @@ Other languages should take advantage of the raw json files.
 == Tutorial & Docs
 
 * {API Browser}[http://sk-api-browser.herokuapp.com/]
-* {API Intro}[http://www.salesking.eu/dev/api/]
+* {API Intro}[https://developer.salesking.eu/articles/tips-tricks/api-documentation]
 * {Ruby SDK - API Client}[https://github.com/salesking/sk_sdk]
 * {PHP SDK - API Client}[https://github.com/salesking/salesking_php_sdk]
 * {Python SDK - API Client}[https://github.com/salesking/salesking_python_sdk]

data/json/v1.0/account.json

@@ -38,11 +38,11 @@
       "type":"number"
     },
     "default_price":{
-      "description": "The default price single for new account entries. Is only used if price single is left empty on create.",
+      "description": "The default price single for new account entries, if price single is empty on create. Max 6 decimal places.",
       "type":"number"
     },
     "default_unit":{
-      "description": "The default quantity unit for new account entries. Is only used if unit is left empty on create.",
+      "description": "The default quantity unit for new account entries, if unit is empty on create.",
       "type":"string",
       "maxLength": 30
     },

data/json/v1.0/contact.json

@@ -207,11 +207,11 @@
     },
     "lead_source":{
       "description": "Lead source describing where a contact came from e.g. a campaign name, website, facebook, URL",
-      "type":"text"
+      "type":"string"
     },
     "lead_ref":{
       "description": "Lead reference e.g. a tracking id, web-url",
-      "type":"text"
+      "type":"string"
     },
     "lead_date":{
       "description": "Lead date e.g. date of first contact with your company. YYYY-MM-DD",

data/json/v1.0/line_item.json

@@ -37,12 +37,12 @@
       "format": "text"
     },
     "price_single":{
-      "description": "Net price of a single item. If a product id is given, price_single is taken from the product if not set.",
+      "description": "Net price of a single item. If a product id is given, price_single is taken from the product if not set. Max 6 decimal places.",
       "type":"number",
       "required" : true
     },
     "cost":{
-      "description": "Cost price for a single item. Used to calculate the gross margin",
+      "description": "Cost price for a single item. Used to calculate the gross margin. Max 6 decimal places.",
       "type":"number"
     },
     "cost_total":{
@@ -84,7 +84,7 @@
       "maxLength": 30
     },
     "quantity":{
-      "description": "Quantity of the item. Must be >= 0",
+      "description": "Quantity of the item. Must be >= 0. Max 6 decimal places.",
       "type":"number",
       "minimum":0,
       "default": 1

data/json/v1.0/product.json

@@ -32,12 +32,12 @@
       "type":"string"
     },
     "price":{
-      "description": "Net price of a single product",
+      "description": "Net price of a single product. Max 6 decimal places.",
       "type":"number",
       "required":true
     },
     "cost":{
-      "description": "Cost price of a single product",
+      "description": "Cost price of a single product. Max 6 decimal places.",
       "type":"number"
     },
     "category_name":{

data/json/v1.0/sub.json

@@ -1,7 +1,7 @@
 {"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.",
+  "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 POST containing a JSON object with the object in it's latest state, the user_id & subdomain, company_id, hmac-signed with your app secret as base64 encode string.<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.",
   "properties":{
     "id":{
       "description":"Unique identifier - UUID",
@@ -18,7 +18,7 @@
       "maxLength": 100
     },
     "callback_url":{
-      "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.",
+      "description": "An url receiving the notification. The url MUST be within the url of the current app and receives a POST having the signed_request parameter containing an base64 encoded JSON object in the body.",
       "type":"string",
       "format":"uri",
       "required":true,
@@ -57,4 +57,4 @@
       "href": "subs/channels"
     }
   ]
-}
+}

data/json/v2.0/account.json

@@ -0,0 +1,172 @@
+{ "type":"object",
+  "title": "account",
+  "name": "account",
+  "description": "BETA An account to track times, expenses, projects, usages, etc. Those are single entry accounts, opposed to double entry accounting in bookkeeping accounts.",
+  "properties":{
+    "id":{
+      "description":"Unique identifier - UUID",
+      "identity":true,
+      "readonly":true,
+      "type":"string",
+      "maxLength": 22,
+      "minLength":22
+    },
+    "number":{
+      "description": "Unique number assigned by you or if empty SK account number schema.",
+      "type":"string",
+      "maxLength": 50
+    },
+    "name":{
+      "description": "The name of the account",
+      "type":"string",
+      "required":true,
+      "maxLength": 100
+    },
+    "description":{
+      "description": "Account description",
+      "type":"string",
+      "format":"text",
+      "maxLength": 255
+    },
+    "balance":{
+      "description": "The account balance is the sum of all entries, also those from sub-accounts.",
+      "type":"number",
+      "readonly":true
+    },
+    "budget":{
+      "description": "If an account is used to track budgetary things f.ex. projects, this fields can be used to perform calculations like: Are we still inside the allowed budget?",
+      "type":"number"
+    },
+    "default_price":{
+      "description": "The default price single for new account entries, if price single is empty on create. Max 6 decimal places.",
+      "type":"number"
+    },
+    "default_unit":{
+      "description": "The default quantity unit for new account entries, if unit is empty on create.",
+      "type":"string",
+      "maxLength": 30
+    },
+    "hide_fields":{
+      "description": "A list of account entry field names. The fields are hidden on account entry lists and forms so one can focus on the important inputs. For example hide: tax,description,billed_at",
+      "type":"string",
+      "maxLength": 255
+    },
+    "contact_id":{
+      "description": "The contacts uuid to which the account is related.",
+      "type":"string",
+      "maxLength": 22,
+      "minLength":22
+    },
+    "document_id":{
+      "description": "Document uuid, related to the account.",
+      "type":"string",
+      "maxLength": 22,
+      "minLength":22
+    },
+    "created_at":{
+      "description": "Date the object was created in SK. Never changes afterwards",
+      "format":"date-time",
+      "readonly":true,
+      "type":"string"
+    },
+    "updated_at":{
+      "description": "Date the object was edited in SK.",
+      "format":"date-time",
+      "readonly":true,
+      "type":"string"
+    },
+    "team_id":{
+      "description": "A team uuid. If set only the team and its parent teams can see the record.",
+      "type":"string",
+      "maxLength": 22,
+      "minLength":22
+    },
+    "creator_id":{
+      "description": "The user uuid who created the record.",
+      "type":"string",
+      "maxLength": 22,
+      "minLength":22,
+      "readonly":true
+    }
+  },
+  "links":[
+    { "rel": "self",
+      "href": "accounts/{id}"
+    },
+    { "rel": "instances",
+      "href": "accounts",
+      "properties" : {
+        "filter[q]":{
+          "title" : "Search",
+          "description": "Wildcard search in number, name, description",
+          "type":"string"
+        },
+        "filter[number]":{
+          "title" : "By number",
+          "description": "Search by exact number",
+          "type":"string"
+        },
+        "filter[balance_from]":{
+          "title" : "By balance from",
+          "description": "Find account with a balance greater(>=) than given number.",
+          "type":"number"
+        },
+        "filter[balance_to]":{
+          "title" : "By balance to",
+          "description": "Find accounts with a balance smaller(<=) than given number.",
+          "type":"number"
+        },
+        "filter[contact_ids]":{
+          "title" : "Contacts",
+          "description": "Find objects belonging to a single or a list of contacts, use ids comma separated.",
+          "type" : "string"
+        },
+        "filter[parent_id]":{
+          "title" : "By parent",
+          "description": "Search children of the given account.",
+          "type":"string"
+        },
+        "page":{
+          "title" : "Page",
+          "description": "In paginated results set the page to look for",
+          "type":"number"
+        },
+        "per_page":{
+          "title" : "Per page",
+          "description": "Results per page. Default is 50, max is 200",
+          "type":"number"
+        },
+        "sort_by":{
+          "title" : "Sort by",
+          "description": "Sort the results by the given field => number",
+          "enum":["name","number","balance", "created_at", "updated_at"],
+          "type": "string"
+        },
+        "sort":{
+          "title" : "Sort",
+          "enum":["ASC","DESC"],
+          "description": "Sort the results in ASC or DESC",
+          "type": "string"
+        }
+      }
+    },
+    { "rel": "destroy",
+      "href": "accounts/{id}",
+      "method": "DELETE"
+    },
+    { "rel": "update",
+      "href": "accounts/{id}",
+      "method": "PUT"
+    },
+    { "rel": "create",
+      "href": "accounts",
+      "method": "POST"
+    },
+    { "rel": "account_entries",
+      "href": "accounts/{id}/account_entries"
+    },
+    { "rel": "account_billings",
+      "href": "accounts/{id}/account_billings"
+    }
+  ]
+}

data/json/v2.0/account_billing.json

@@ -0,0 +1,131 @@
+{ "type":"object",
+  "title": "account_billing",
+  "name": "account_billing",
+  "description": "BETA An account billing serves as the glue between an account a document and their related account entries and line items. It also lets one keep track of who billed what and when. A billing is created from billable account entries, which are turned into line items for a document.",
+  "properties":{
+    "id":{
+      "description":"Unique identifier - UUID",
+      "identity":true,
+      "readonly":true,
+      "type":"string",
+      "maxLength": 22,
+      "minLength":22
+    },
+    "name":{
+      "description": "A note for the billing e.g. happyPDF usage April 2014. The field is wildcard searchable",
+      "type":"string",
+      "maxLength": 100
+    },
+    "account_id":{
+      "description": "The related account. Must be set for entries to be found.",
+      "type":"string",
+      "required":true,
+      "maxLength": 22,
+      "minLength":22
+    },
+    "group_entries_by":{
+      "description": "Group multiple account entries into single line items, when creating a billing+document from entries. Account entries MUST have the SAME price_single and quantity unit, to land in a group. Date base groups also require the SAME entry name.",
+      "type":"string",
+      "enum": ["name", "day", "week", "month", "year"]
+    },
+    "document_type":{
+      "description": "The document type to create. CamelCase document class name. Invoice by default",
+      "type":"string",
+      "default" : "Invoice",
+      "enum": ["Invoice", "CreditNote", "Order", "Estimate"]
+    },
+    "set_billed_at":{
+      "description": "Set billed at date for related account entries.",
+      "type":"boolean",
+      "default" : false
+    },
+    "document_id":{
+      "description": "The document created by the billing.",
+      "type":"string",
+      "readonly": true,
+      "maxLength": 22,
+      "minLength":22
+    },
+    "created_at":{
+      "description": "Date the object was created in SK. Never changes afterwards",
+      "format":"date-time",
+      "readonly":true,
+      "type":"string"
+    },
+    "team_id":{
+      "description": "A team uuid. Is inferred from the accounts team id.",
+      "type":"string",
+      "maxLength": 22,
+      "minLength":22
+    },
+    "creator_id":{
+      "description": "User who created the record.",
+      "type":"string",
+      "maxLength": 22,
+      "minLength":22,
+      "readonly":true
+    }
+  },
+  "links":[
+    { "rel": "self",
+      "href": "account_billings/{id}"
+    },
+    { "rel": "instances",
+      "href": "account_billings",
+      "properties" : {
+        "filter[q]":{
+          "title" : "Search",
+          "description": "Wildcard search in name",
+          "type":"string"
+        },
+        "filter[account_ids]":{
+          "title" : "Accounts",
+          "description": "Find objects belonging to a single or a list of accounts, use ids comma separated.",
+          "type" : "string"
+        },
+        "filter[created_at_from]":{
+          "title" : "From creation date",
+          "description": "Objects with a date eq/after the date. YYYY-MM-DD",
+          "format" : "date",
+          "type" : "string"
+        },
+        "filter[created_at_to]":{
+          "title" : "To creation date",
+          "description": "Objects with a creation until the date(<=). ISO 8601 format YYY-MM-DDThh:mm:ss+z or just a date YYY-MM-DD. If date is given the time is set to the end of the day(23:59:59) so all objects created on that day are included. A time should be already utc time.",
+          "format" : "date",
+          "type" : "string"
+        },
+        "page":{
+          "title" : "Page",
+          "description": "In paginated results set the page to look for",
+          "type":"number"
+        },
+        "per_page":{
+          "title" : "Per page",
+          "description": "Results per page. Default is 50, max is 200",
+          "type":"number"
+        },
+        "sort_by":{
+          "title" : "Sort by",
+          "description": "Sort the results by the given field => number",
+          "enum":["name","number","balance", "created_at", "updated_at"],
+          "type": "string"
+        },
+        "sort":{
+          "title" : "Sort",
+          "enum":["ASC","DESC"],
+          "description": "Sort the results in ASC or DESC",
+          "type": "string"
+        }
+      }
+    },
+    { "rel": "destroy",
+      "href": "account_billings/{id}",
+      "method": "DELETE"
+    },
+    { "rel": "create",
+      "href": "account_billings",
+      "method": "POST"
+    }
+  ]
+}

data/json/v2.0/account_entry.json

@@ -0,0 +1,212 @@
+{ "type":"object",
+  "title": "account_entry",
+  "name": "account_entry",
+  "description": "A entry for an account",
+  "properties":{
+    "id":{
+      "description":"Unique identifier - UUID",
+      "identity":true,
+      "readonly":true,
+      "type":"string",
+      "maxLength": 22,
+      "minLength":22
+    },
+    "account_id":{
+      "description":"Account the entry belongs to.",
+      "required":true,
+      "type":"string",
+      "maxLength": 22,
+      "minLength":22
+    },
+    "document_id":{
+      "description":"Document the entry is related to. This relation is set by an account billing.",
+      "readonly":true,
+      "type":"string",
+      "maxLength": 22,
+      "minLength":22
+    },
+    "item_id":{
+      "description":"Line item on the document the entry is related to. This relation is set by an account billing or when a document is booked onto an account.",
+      "readonly":true,
+      "type":"string",
+      "maxLength": 22,
+      "minLength":22
+    },
+    "name":{
+      "description": "The name of an entry",
+      "type":"string",
+      "maxLength": 50
+    },
+    "description":{
+      "description": "Entry description",
+      "type":"string",
+      "format": "text"
+    },
+    "price_single":{
+      "description": "Net price of a single entry. If a product id is given, price_single is taken from the product if not set.",
+      "type":"number",
+      "required" : true
+    },
+    "net_total":{
+      "description": "Net price of a single entry. Calculated from price_single * quantity",
+      "readonly":true,
+      "type":"number"
+    },
+    "tax":{
+      "description": "Tax percentage",
+      "type":"number"
+    },
+    "quantity_unit":{
+      "description": "Quantity unit e.g: kg, days, month, ..",
+      "type":"string",
+      "maxLength": 30
+    },
+    "quantity":{
+      "description": "Quantity of the entry.",
+      "type":"number",
+      "default": 1
+    },
+    "date":{
+      "description": "Date of the entry. Defaults to today. Entries are sorted by date per default.",
+      "format":"date-time",
+      "type":"string"
+    },
+    "billable":{
+      "description": "True if the entry can be billed.",
+      "type":"boolean",
+      "default": false
+    },
+    "billed_at":{
+      "description": "Date the object was billed. Automatically set when the entry is used on an invoice.",
+      "format":"date-time",
+      "type":"string"
+    },
+    "created_at":{
+      "description": "Date the object was created. Never changes afterwards",
+      "format":"date-time",
+      "readonly":true,
+      "type":"string"
+    },
+    "updated_at":{
+      "description": "Date the object was edited.",
+      "format":"date-time",
+      "readonly":true,
+      "type":"string"
+    },
+    "_destroy":{
+      "description": "When set an existing entry will be deleted. This switch is used for entries passed during batch operations.",
+      "type":"boolean"
+    }
+  },
+  "links":[
+
+    { "rel": "self",
+      "href": "account_entries/{id}"
+    },
+    { "rel": "instances",
+      "href": "account_entries",
+      "properties" : {
+        "page":{
+          "title" : "Page",
+          "description": "In paginated results set the page to look for",
+          "type":"number"
+        },
+        "per_page":{
+          "title" : "Per page",
+          "description": "Results per page. Default is 50, max is 200",
+          "type":"number"
+        },
+        "filter[q]":{
+          "title" : "Search",
+          "description": "Wildcard search in name, description",
+          "type":"string"
+        },
+        "filter[account_ids]":{
+          "title" : "Search by related accounts",
+          "description": "Set multiple account ids comma separated or as array",
+          "type":"string"
+        },
+        "filter[document_ids]":{
+          "title" : "Search by related documents",
+          "description": "Set multiple document ids comma separated or as array",
+          "type":"string"
+        },
+        "filter[ids]":{
+          "title" : "Search by account entry ids",
+          "description": "Set multiple entry ids comma separated or as array",
+          "type":"string"
+        },
+        "filter[unbilled]":{
+          "title" : "Unbilled",
+          "description": "Entries available for billing: marked as billable without a billing date(billed_at) set. False values will skip this filter. To find billed entries simply use filter[billed_at_to] e.g with todays date.",
+          "type":"boolean"
+        },
+        "filter[billable]":{
+          "title" : "Billable",
+          "description": "Billable or not billable entries. Set false(string) or 0(Integer) to get not billable entries. For billable entries use true or 1. Also see filter[unbilled] to find not yet billed entries.",
+          "type":"boolean"
+        },
+        "filter[date_from]":{
+          "title" : "From date",
+          "description": "Objects with a date eq/after the date. YYYY-MM-DD",
+          "format" : "date",
+          "type" : "string"
+        },
+        "filter[date_to]":{
+          "title" : "To date",
+          "description": "Objects with date eq/before the date. YYYY-MM-DD",
+          "format" : "date",
+          "type" : "string"
+        },
+        "filter[billed_at_from]":{
+          "title" : "From billing date",
+          "description": "Objects with a billing date eq/after the date. YYYY-MM-DD",
+          "format" : "date",
+          "type" : "string"
+        },
+        "filter[billed_at_to]":{
+          "title" : "To billing date",
+          "description": "Objects with billing date eq/before the date. YYYY-MM-DD. A set billing date means the entry has been billed, so simply use this filter e.g with date today to find all billed entries.",
+          "format" : "date",
+          "type" : "string"
+        },
+        "filter[created_at_from]":{
+          "title" : "From creation date",
+          "description": "Objects with a date eq/after the date. YYYY-MM-DD",
+          "format" : "date",
+          "type" : "string"
+        },
+        "filter[created_at_to]":{
+          "title" : "To creation date",
+          "description": "Objects with a creation until the date(<=). ISO 8601 format YYY-MM-DDThh:mm:ss+z or just a date YYY-MM-DD. If date is given the time is set to the end of the day(23:59:59) so all objects created on that day are included. A time should be already utc time.",
+          "format" : "date",
+          "type" : "string"
+        },
+        "sort_by":{
+          "title" : "Sort by",
+          "description": "Sort the results by the given field => number",
+          "enum":["name","number","date","quantity","price_single","created_at", "updated_at"],
+          "type": "string"
+        },
+        "sort":{
+          "title" : "Sort",
+          "enum":["ASC","DESC"],
+          "description": "Sort the results in ASC or DESC",
+          "type": "string"
+        }
+      }
+    },
+    { "rel": "destroy",
+      "href": "account_entries/{id}",
+      "method": "DELETE"
+    },
+    { "rel": "update",
+      "href": "account_entries/{id}",
+      "method": "PUT"
+    },
+    { "rel": "create",
+      "href": "account_entries",
+      "method": "POST"
+    }
+  ]
+}