sk_api_schema 0.6.1 → 0.7.0

data/CHANGELOG.md

@@ -1,8 +1,26 @@
-# Changelog for SalesKing API Schema
+# SalesKing API Changelog
 
-A more detailed view of the changes can be found in the {commit messages}[https://github.com/salesking/sk_api_schema/commits/]
+See [commit messages](https://github.com/salesking/sk_api_schema/commits/) for details.
+Also signup to our [Developer Newsletter](http://www.salesking.eu/dev/newsletter/) to stay up-to-date !!!
 
-2013-01
+##2013-01
+
+Contacts/Client changes
+* New contact resource sporting client, lead, supplier contact types
+* mark contact as employee, getting number, organisation, vat/tax number from his parent
+* nested contacts
+* add contact, contact_id to all documents
+* add parent_id to contact, for contact nesting
+* remove client_id from param sort_by for doc list views (it makes no sense to sort by a UUID)
+* export_template, email_template.kind uses contact instead of client
+
+DEPRECATED removed ~ 08.2013 prior notice via [Developer Newsletter](http://www.salesking.eu/dev/newsletter/)
+* client resource
+* document.client, document.client_id => doc.contact, doc.contact_id
+* documents?filter\[client_ids] => filter\[contact_ids]
+* oAuth scope for api/clients
+
+Others
 * add external_ref for line item
 * email "send" parameter can be set to false or 0 to prevent sending
 * email "from_addr" is not required
@@ -11,21 +29,21 @@ A more detailed view of the changes can be found in the {commit messages}[https:
 * add filter\[tags] to products, mark price as required
 * add name-key to all objects containing the lowercased_underscored-name, PLEASE start using it instead of the title-field, which will be changed to its CamelCasedObjectName
 
-2012-12
+##2012-12
 * add search filter to pdf_template, email_template
 * filter clients by ids - search for a list of comma separated uuids
 
-2012-11
+##2012-11
 * add currency fields for documents, client, company and payment
 * add PDF template resource
 * drop 'method' from payment in favour of payment_method
 
-2012-07
+##2012-07
 * maxLength for all string properties with limits
 * add "format":"text" to plain-text fields
 * search products by number
 
-2012-06
+##2012-06
 * line item discount can be negative
 * tax and discount values with up to four decimal places
 * add payments link to invoice, credit_note
@@ -33,35 +51,35 @@ A more detailed view of the changes can be found in the {commit messages}[https:
 * Deprecate payment.method in favour of payment.payment_method bcs 'method' is a keyword in programming
 * test with travis-ci.org
 
-2012-05
+##2012-05
 * fix date type definitions
 * add empty links sections for address, line_item
 * add payment_method to order
 * deprecate gross_total for payment reminder
 
-2012-01
+##2012-01
 * add notes field for client
 
-2012-05
+##2012-05
 
 * add missing payment method to order
 * fix date & date-time type definitions
 * add empty links section to address, line item
 
-2011-10
+##2011-10
 * added created_at search filter to clients and documents
 * added creator(user) search filter to clients and documents
 
-2011-9
+##2011-9
 * search documents by number
 * maxLength information for client and address properties
 * allow tags edit, destroy
 
-2011-7
+##2011-7
 * allow new documents with status closed
 * auto-set number+date for new open/closed documents
 
-2011-6
+##2011-6
 * added language field to document, client, email-template
 * added filter\[languages] for documents and clients, to search by one or more languages
 * added filter\[client_ids] to documents, to search by one or multiple clients
@@ -69,10 +87,10 @@ A more detailed view of the changes can be found in the {commit messages}[https:
 * changed _delete property to _destroy for address, line_item
 * removed client_id requirement for documents
 
-2011-05
+##2011-05
 * new hash_clean method for ruby schema reader class
 
-2011-04
+##2011-04
 * added tags
 * added documents
 * reduced default objects in list to 10, max is 100
@@ -80,11 +98,11 @@ A more detailed view of the changes can be found in the {commit messages}[https:
 * added created_at & number filtering to client
 * added _delete field to line_item & address, to be able to destroy them since both are transfered within their parent object
 
-2011-03
+##2011-03
 * added subscriptions
 * added memoizing to ruby schema reader
 
-2011-02
+##2011-02
 * added moneybookers, premium_sms to payment methods
 * added auth_permission
 * added external_ref to documents
@@ -92,5 +110,5 @@ A more detailed view of the changes can be found in the {commit messages}[https:
 * added recurring
 * added source param to copy documents
 
-2010-11 - 2011-01
+##2010-11 - 2011-01
 * initial version

data/README.rdoc

@@ -6,7 +6,7 @@ Our API (objects,resources) is described with JSON Schema (http://json-schema.or
 Each Object has its own description, with those top-level keys:
 
   {
-    "name": "client",      // object type
+    "type": "contact",      // object type
     "properties": { .. },   // field descriptions
     "links": [ .. ]         // CRUD actions, relationships to other resources
   }
@@ -21,9 +21,11 @@ Other languages should take advantage of the raw json files.
 
 == Tutorial & Docs
 
-* {API Browser visualized JSON Schema}[http://sk-api-browser.heroku.com/]
-* {API Intro}[http://dev.blog.salesking.eu/api/]
+* {API Browser}[http://sk-api-browser.heroku.com/]
+* {API Intro}[http://www.salesking.eu/dev/api/]
 * {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]
 
 == Object Basic's
 
@@ -32,13 +34,13 @@ Primary object types in SK are:
 * Contacts
 * Products
 
-Secondary objects are always tied to a primary(related) object
+Secondary objects, tied to a primary(related) object
 * Attachments
 * Comments
 * Messages
 * Tags
 
-The third kind are supportive objects
+Supportive objects
 * Company
 * Users
 * Exports
@@ -53,8 +55,8 @@ of each schema.
     # GET invoices tagged with hosting and important
     /invoices?filter[tags]=important,hosting
 
-    # GET orders for given client ids
-    /orders?filter[client_ids]=:client_id,:client_id
+    # GET orders for given contact ids
+    /orders?filter[contact_ids]=:contact_id,:contact_id
 
     # GET products second page with 100 in list, only id+name
     /products?per_page=100&page=2&fields=id,name
@@ -62,11 +64,11 @@ of each schema.
     # all comments for an invoice
     /invoices/:id/comments
 
-    # all documents of a client
-    /clients/:id/documents
+    # all documents of a contact
+    /contacts/:id/documents
 
-    # all invoices of a client
-    /clients/:id/invoices
+    # all invoices of a contact
+    /contacts/:id/contact
 
 == Field types & formats
 
@@ -114,11 +116,11 @@ changes(breaking backwards compatibility), the version number will remain.
 
 You can see the current schema at:
   my.salesking.eu/api/schema
-  my.salesking.eu/api/clients/schema
+  my.salesking.eu/api/contacts/schema
 
 The schema main version(NOT the gem version) can be set with the "v" url parameter
 in any call, but is pretty useless as long as we are in v1.0
-  my.salesking.eu/api/clients?v='1.0'
+  my.salesking.eu/api/contacts?v='1.0'
 
 The gem has its own version number. A new gem version indicates a change, but
 we first try it on our staging environment before any live instances are
@@ -133,9 +135,9 @@ To see the current gem version use:
 By default the API returns an object with all available properties(fields). You
 can limit those by passing comma-separated string(or array) in the fields
 parameter:
-  my.salesking.eu/api/clients?fields=id,organisation
+  my.salesking.eu/api/contacts?fields=id,organisation
 
-  my.salesking.eu/api/clients?fields[]=id&fields[]=organisation
+  my.salesking.eu/api/contacts?fields[]=id&fields[]=organisation
 
 Please try to only request the fields you really need, to save computing power!
 

data/json/v1.0/attachment.json

@@ -30,7 +30,7 @@
       "format": "uri"
     },
     "related_object_type":{
-      "description": "Object type of the attachment parent. Is the camelcased base class name: Document for invoice, credit_note,.., Contact for client",
+      "description": "Object type of the attachment parent. Is the camelcased base class name: Document for invoice, credit_note, contact, ..",
       "required":true,
       "type":"string"
     },
@@ -112,7 +112,8 @@
         "sort":{
           "title" : "Sort",
           "enum":["ASC","DESC"],
-          "description": "Sort the results in ASC or DESC"
+          "description": "Sort the results in ASC or DESC",
+          "type": "string"
         }
       }
     },

data/json/v1.0/auth_permission.json

@@ -63,7 +63,8 @@
         "sort":{
           "title" : "Sort",
           "enum":["ASC","DESC"],
-          "description": "Sort the results in ASC or DESC"
+          "description": "Sort the results in ASC or DESC",
+          "type": "string"
         }
       }
     },

data/json/v1.0/client.json

@@ -1,7 +1,7 @@
 {"type":"object",
   "title": "client",
   "name": "client",
-  "description": "A client as seen by SalesKing",
+  "description": "A client as seen by SalesKing. This resource is DEPRECATED please use contacts instead with type-field set 'Client'",
   "properties":{
     "id":{
       "description":"Unique identifier - UUID",

data/json/v1.0/comment.json

@@ -17,7 +17,7 @@
       "type":"string"
     },
     "related_object_type":{
-      "description": "Object type of the comments parent. Is the camelcased base class name: Document for invoice, credit_note,.., Contact for client",
+      "description": "Object type of the comments parent. Is the camelcased base class name: Document for invoice, credit_note, contact",
       "required":true,
       "type":"string"
     },
@@ -90,7 +90,8 @@
         "sort":{
           "title" : "Sort",
           "enum":["ASC","DESC"],
-          "description": "Sort the results in ASC or DESC"
+          "description": "Sort the results in ASC or DESC",
+          "type": "string"
         }
       }
     },

data/json/v1.0/contact.json

@@ -0,0 +1,357 @@
+{"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.",
+  "properties":{
+    "id":{
+      "description":"Unique identifier - UUID",
+      "identity":true,
+      "readonly":true,
+      "type":"string",
+      "maxLength": 22,
+      "minLength":22
+    },
+    "parent_id":{
+      "description": "ID of a parent contact.",
+      "type":"string",
+      "maxLength": 22,
+      "minLength":22
+    },
+    "type":{
+      "description": "Type of contact",
+      "enum":["Client", "Lead", "Supplier"],
+      "required" : true,
+      "type":"string",
+      "maxLength": 50
+    },
+    "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.",
+      "type": "boolean",
+      "default": false
+    },
+    "number":{
+      "description": "Unique number, auto-created by SK for new contacts(client, supplier) without number.",
+      "type":"string",
+      "maxLength": 50
+    },
+    "organisation":{
+      "description": "Name of a company. This or lastname must be present",
+      "required" : true,
+      "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",
+      "type":"string",
+      "maxLength": 50
+    },
+    "first_name":{
+      "description": "First name of a person.",
+      "type":"string",
+      "maxLength": 50
+    },
+    "gender":{
+      "description": "Can be empty for a company. Is used in salutation",
+      "enum":["male", "female"],
+      "type":"string"
+    },
+    "notes":{
+      "description": "Notes for a contact. For day to day information you should use comments instead.",
+      "type":"string",
+      "format": "text"
+    },
+    "position":{
+      "description": "Position of a person in a company.",
+      "type":"string",
+      "maxLength": 50
+    },
+    "title":{
+      "description": "Academical title of a person e.g. Dr., Prof",
+      "type":"string",
+      "maxLength": 50
+    },
+    "tax_number":{
+      "description": "Tax number, normally applies to a private person",
+      "type":"string",
+      "maxLength": 30
+    },
+    "vat_number":{
+      "description": "VAT number, for a company or person paying value added taxes.",
+      "type":"string",
+      "maxLength": 30
+    },
+    "email":{
+      "description": "Email address of the contact.",
+      "type":"string",
+      "maxLength": 100
+    },
+    "url":{
+      "description": "An url associated with the person, e.g its company website.",
+      "type":"string",
+      "maxLength": 255
+    },
+    "birthday":{
+      "format":"date",
+      "type":"string"
+    },
+    "tag_list":{
+      "description": "Space separated list of tags. Are split and saved as Tag objects on create, update.",
+      "type":"string"
+    },
+    "created_at":{
+      "description": "Date the record was created in SK. Never changes afterwards.",
+      "format":"date-time",
+      "readonly":true,
+      "type":"string"
+    },
+    "updated_at":{
+      "description": "Last date when the record was edited.",
+      "format":"date-time",
+      "readonly":true,
+      "type":"string"
+    },
+    "language":{
+      "description": "Should be a valid language short-code: de-DE, fr, en-GB; like defined in your account language menu. When the client is emailed, a localized version of a multi-language template(email, pdf) will be used if available. The language will also be set for new documents.",
+      "type":"string",
+      "maxLength": 10
+    },
+    "currency":{
+      "description": "Currency code as defined by the ISO 4217 standard(3-letter UPCASE: EUR, USD). If set the currency is taken for new documents.",
+      "type":"string",
+      "maxLength": 3,
+      "minLength": 3
+    },
+    "payment_method":{
+      "description": "Default payment method for used for new documemts",
+      "enum":["cash","bank_transfer","credit_card","paypal","direct_debit","cheque", "moneybookers", "premium_sms"],
+      "type":"string"
+    },
+    "bank_name":{
+      "description": "Bank name",
+      "type":"string",
+      "maxLength": 70
+    },
+    "bank_number":{
+      "description": "Bank number",
+      "type":"string",
+      "maxLength": 35
+    },
+    "bank_account_number":{
+      "description": "Bank account number.",
+      "type":"string",
+      "maxLength": 35
+    },
+    "bank_iban":{
+      "description": "IBAN Number of the bank account. Is validated",
+      "type":"string",
+      "maxLength": 35
+    },
+    "bank_swift":{
+      "description": "SWIFT BIC-  Bank Identifier Code",
+      "type":"string",
+      "maxLength": 11
+    },
+    "bank_owner":{
+      "description": "Bank account owner",
+      "type":"string",
+      "maxLength": 70
+    },
+    "phone_fax":{
+      "description": "Fax number",
+      "type":"string",
+      "maxLength": 30
+    },
+    "phone_office":{
+      "description": "Office phone number",
+      "type":"string",
+      "maxLength": 30
+    },
+    "phone_home":{
+      "description": "Private phone number",
+      "type":"string",
+      "maxLength": 30
+    },
+    "phone_mobile":{
+      "description": "Mobile phone number",
+      "type":"string",
+      "maxLength": 30
+    },
+    "lock_version":{
+      "description": "Increased on every edit, so SK can detect/prevent a concurrent edit by another user. First save wins.",
+      "type":"integer"
+    },
+    "cash_discount":{
+      "description": "Default cash discount for new invoices.",
+      "type":"number"
+    },
+    "due_days":{
+      "description": "Default due days for new invoices.",
+      "type":"integer"
+    },
+    "address_field":{
+      "description": "Returns the address field used on new docs. Consist of Organisation name and default(first) address",
+      "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"}
+    },
+    "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
+    },
+    "lead_source":{
+      "description": "Lead source describing where a contact came from e.g. a campaign name, website, facebook, URL",
+      "type":"string",
+      "maxLength": 255
+    },
+    "lead_ref":{
+      "description": "Lead reference e.g. a tracking id, web-url",
+      "type":"string",
+      "maxLength": 255
+    },
+    "converted_at":{
+      "description": "Date the contact converted from lead to client or any other contact type (supplier)",
+      "format":"date-time",
+      "type":"string"
+    }
+  },
+  "links":[
+    { "rel": "self",
+      "href": "contacts/{id}"
+    },
+    { "rel": "instances",
+      "href": "contacts",
+      "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 10, max is 100",
+          "type":"number"
+        },
+        "filter[q]":{
+          "title" : "Search",
+          "description": "Wildcard search in first, last_name, organisation, email, number",
+          "type":"string"
+        },
+        "filter[tags]":{
+          "title" : "Tags",
+          "description": "Filter by a space delimited list of tags",
+          "type":"string"
+        },
+        "filter[ids]":{
+          "title" : "Contacts",
+          "description": "A single or a list of contacts uuids, comma separated",
+          "type" : "string"
+        },
+        "filter[created_at_from]":{
+          "title" : "From date",
+          "description": "Objects with a creation date after the date, including given datetime. ISO 8601 format YYY-MM-DDThh:mm:ss+z",
+          "format" : "date-time",
+          "type" : "string"
+        },
+        "filter[created_at_to]":{
+          "title" : "To date",
+          "description": "Objects with a creation date before the date, including given datetime. ISO 8601 format YYY-MM-DDThh:mm:ss+z",
+          "format" : "date-time",
+          "type" : "string"
+        },
+        "filter[birthday_from]":{
+          "title" : "From birthday date",
+          "description": "Contacts with a birthday after and on the date. Leave the birthday-to date blank to only search on this day.",
+          "format" : "date",
+          "type" : "string"
+        },
+        "filter[birthday_to]":{
+          "title" : "To birthday date",
+          "description": "Contacts with a birthday date before and on the date.",
+          "format" : "date",
+          "type" : "string"
+        },
+        "filter[creator_ids]":{
+          "title" : "Creator",
+          "description": "Objects created by the given users uuids, comma separated",
+          "type" : "string"
+        },
+        "filter[number]":{
+          "title" : "By number",
+          "description": "Search by number where the number is matched from the start: number%",
+          "type" : "string"
+        },
+        "filter[languages]":{
+          "title" : "Languages",
+          "description": "A single or a list of language codes, comma separated",
+          "type" : "string"
+        },
+        "filter[type]":{
+          "title" : "Type",
+          "description": "Type of the contact: ",
+          "enum":["Client", "Lead", "Supplier"],
+          "type" : "string"
+        },
+        "sort_by":{
+          "title" : "Sort by",
+          "description": "Sort the results by the given field => number",
+          "enum":["organisation", "number","email","first_name","last_name", "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": "contacts/{id}",
+      "method": "DELETE"
+    },
+    { "rel": "update",
+      "href": "contacts/{id}",
+      "method": "PUT"
+    },
+    { "rel": "create",
+      "href": "contacts",
+      "method": "POST"
+    },
+    { "rel": "documents",
+      "href": "contacts/{id}/documents"
+    },
+    { "rel": "attachments",
+      "href": "contacts/{id}/attachments"
+    },
+    { "rel": "invoices",
+      "href": "contacts/{id}/invoices"
+    },
+    { "rel": "estimates",
+      "href": "contacts/{id}/estimates"
+    },
+    { "rel": "orders",
+      "href": "contacts/{id}/orders"
+    },
+    { "rel": "credit_notes",
+      "href": "contacts/{id}/credit_notes"
+    },
+    { "rel": "recurrings",
+      "href": "contacts/{id}/recurrings"
+    },
+    { "rel": "payment_reminders",
+      "href": "contacts/{id}/payment_reminders"
+    },
+    { "rel": "comments",
+      "href": "contacts/{id}/comments"
+    },
+    { "rel": "emails",
+      "href": "contacts/{id}/emails"
+    }
+  ]
+}