sk_api_schema 0.10.5 → 0.10.6

data/json/v2.0/address.json

@@ -0,0 +1,85 @@
+{ "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.",
+  "properties":{
+    "id":{
+      "description":"Unique identifier - UUID",
+      "identity":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
+    },
+    "address1":{
+      "description": "Should contain the street or otherwise primary address information.",
+      "type":"string",
+      "maxLength": 100
+    },
+    "address2":{
+      "description": "Additional address information, like floor number",
+      "type":"string",
+      "maxLength": 100
+    },
+    "pobox":{
+      "description": "Post office box number",
+      "type":"string",
+      "maxLength": 10
+    },
+    "zip":{
+      "description": "Zip number of the city. Length must be between 4..10",
+      "type":"string",
+      "maxLength": 10
+    },
+    "state":{
+      "description": "Country state of address",
+      "type":"string",
+      "maxLength": 100
+    },
+    "country":{
+      "description": "Country of the address.",
+      "type":"string",
+      "maxLength": 100
+    },
+    "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"
+    },
+    "address_type":{
+      "description": "Type of the address, as seen by vCard definition. There can only be one type. Inside of SK you can use placeholders like client.parcel_address.city to access the first parcel adr(Same for work_ / home_). <br/>Besides the placeholder default_address, always returns the first address found. Sorting is done by the order(if set) else by date, newest first.",
+      "enum":["work","home", "parcel"],
+      "type":"string"
+    },
+    "order":{
+      "description": "Addresses are normally sorted by date, newest first. If you need to strongly rely on their sorting e.g. default_address (always first) or have multiple addresses of one type(3 parcel), use this field for all adrs. <br/>Single adrs are used in placeholders like: addresses.2.city, returning the second adr found(not necessarily one with order=2).",
+      "type":"integer"
+    },
+    "lat":{
+      "description": "Geo-Location latitude",
+      "type":"number"
+    },
+    "long":{
+      "description": "Geo-Location longitude",
+      "type":"number"
+    },
+    "_destroy":{
+      "description": "When set an existing address will be deleted. This switch is only used when addresses are passed-in nested inside their parent object(a contact).",
+      "type":"boolean"
+    }
+  },
+  "links":[]
+}

data/json/v2.0/attachment.json

@@ -0,0 +1,133 @@
+{ "type":"object",
+  "title": "attachment",
+  "name": "attachment",
+  "description":"An file attachment",
+  "properties":{
+    "id":{
+      "description": "uuid of the object.",
+      "identity":true,
+      "readonly":true,
+      "type":"string",
+      "maxLength": 22,
+      "minLength":22
+    },
+    "filename":{
+      "description": "The filename as set when uploaded",
+      "readonly":true,
+      "type":"string",
+      "maxLength": 255
+    },
+    "disk_filename":{
+      "description": "Unique filename set by SK",
+      "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,
+      "type":"string"
+    },
+    "size":{
+      "description": "Filesize in kb. Auto detected on upload.",
+      "readonly":true,
+      "type":"integer"
+    },
+    "is_signed":{
+      "description": "True if the file(pdf) has been digitally signed.",
+      "type":"boolean"
+    },
+    "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. If set only the team and its parent teams can see the record.",
+      "type":"string",
+      "maxLength": 22,
+      "minLength":22
+    }
+
+  },
+  "links":[
+    { "rel": "self",
+      "href": "attachments/{id}"
+    },
+    { "rel": "download",
+      "href": "attachments/{id}/download"
+    },
+    { "rel": "instances",
+      "href": "attachments",
+      "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": "Search in filename",
+          "type":"string"
+        },
+        "filter[from]":{
+          "title" : "From date",
+          "description": "All objects created at and after the date",
+          "format" : "date",
+          "type" : "string"
+        },
+        "filter[to]":{
+          "title" : "To date",
+          "description": "All objects created at and before the date. YYYY-MM-DD",
+          "format" : "date",
+          "type" : "string"
+        },
+        "filter[related_object_type]":{
+          "title" : "Related object type",
+          "description": "All objects belonging to the given object type. The singular base class name like: Document, Contact, Export, Message",
+          "type" : "string"
+        },
+        "sort_by":{
+          "title" : "Sort by",
+          "description": "Sort the results by the given field",
+          "enum":["filename","related_object_id","related_object_type", "created_at"],
+          "type": "string"
+        },
+        "sort":{
+          "title" : "Sort",
+          "enum":["ASC","DESC"],
+          "description": "Sort the results in ASC or DESC",
+          "type": "string"
+        }
+      }
+    },
+    { "rel": "destroy",
+      "href": "attachments/{id}",
+      "method": "DELETE"
+    }
+  ]
+}

data/json/v2.0/auth_permission.json

@@ -0,0 +1,75 @@
+{"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,
+      "type":"string",
+      "maxLength": 22,
+      "minLength":22
+    },
+    "full_name":{
+      "description": "Context_name and name localized: API Clients read - API Kunden anzeigen",
+      "type":"string",
+      "maxLength": 255
+    },
+    "name":{
+      "description": "Name for the permission. Since a permission groups multiple privileges the name reflects what someone is allowed to do: read, update, delete. With 'read' granting acccess to the 'index' and 'show' actions of a resource.",
+      "type":"string",
+      "maxLength": 255
+    },
+    "context_name":{
+      "description": "The context for the permission, being a resource: clients, emails",
+      "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,
+      "maxLength": 255
+    }
+  },
+
+  "links":[
+    { "rel": "instances",
+      "href": "auth_permissions",
+      "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": "Search in name and context names",
+          "type":"string"
+        },
+        "sort_by":{
+          "title" : "Sort by",
+          "description": "Sort the results by the given field => number",
+          "enum":["auth_permission.name", "auth_context.name"],
+          "type": "string"
+        },
+        "sort":{
+          "title" : "Sort",
+          "enum":["ASC","DESC"],
+          "description": "Sort the results in ASC or DESC",
+          "type": "string"
+        }
+      }
+    },
+    { "rel": "self",
+      "href": "auth_permissions/{id}"
+    }
+  ]
+}

data/json/v2.0/client.json

@@ -0,0 +1,318 @@
+{"type":"object",
+  "title": "client",
+  "name": "client",
+  "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",
+      "identity":true,
+      "readonly":true,
+      "type":"string",
+      "maxLength": 22,
+      "minLength":22
+    },
+    "number":{
+      "description": "Unique number, auto-created by SK for new client 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":{
+      "description": "The birthday. YYYY-MM-DD",
+      "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
+    }
+  },
+  "links":[
+    { "rel": "self",
+      "href": "clients/{id}"
+    },
+    { "rel": "instances",
+      "href": "clients",
+      "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 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" : "Clients",
+          "description": "A single or a list of client uuids, comma separated",
+          "type" : "string"
+        },
+        "filter[created_at_from]":{
+          "title" : "From date",
+          "description": "Objects with a creation on/after 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 start of the day(00:00:00) so all objects created on this day are included. A time should be already utc time",
+          "format" : "date-time",
+          "type" : "string"
+        },
+        "filter[created_at_to]":{
+          "title" : "To 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-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. YYYY-MM-DD",
+          "format" : "date",
+          "type" : "string"
+        },
+        "filter[birthday_to]":{
+          "title" : "To birthday date",
+          "description": "Contacts with a birthday date before and on the date. YYYY-MM-DD",
+          "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"
+        },
+        "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"
+        }
+      }
+    },
+    { "rel": "destroy",
+      "href": "clients/{id}",
+      "method": "DELETE"
+    },
+    { "rel": "update",
+      "href": "clients/{id}",
+      "method": "PUT"
+    },
+    { "rel": "create",
+      "href": "clients",
+      "method": "POST"
+    },
+    { "rel": "documents",
+      "href": "clients/{id}/documents"
+    },
+    { "rel": "attachments",
+      "href": "clients/{id}/attachments"
+    },
+    { "rel": "invoices",
+      "href": "clients/{id}/invoices"
+    },
+    { "rel": "estimates",
+      "href": "clients/{id}/estimates"
+    },
+    { "rel": "orders",
+      "href": "clients/{id}/orders"
+    },
+    { "rel": "credit_notes",
+      "href": "clients/{id}/credit_notes"
+    },
+    { "rel": "recurrings",
+      "href": "clients/{id}/recurrings"
+    },
+    { "rel": "payment_reminders",
+      "href": "clients/{id}/payment_reminders"
+    },
+    { "rel": "comments",
+      "href": "clients/{id}/comments"
+    },
+    { "rel": "emails",
+      "href": "clients/{id}/emails"
+    }
+  ]
+}