sk_api_schema 0.10.5 → 0.10.6

data/json/v2.0/product.json

@@ -0,0 +1,144 @@
+{ "type":"object",
+  "title": "product",
+  "name": "product",
+  "description": "A product in SK",
+  "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 product number schema.",
+      "type":"string",
+      "maxLength": 50
+    },
+    "name":{
+      "description": "The name of the product",
+      "type":"string",
+      "required":true,
+      "maxLength": 50
+    },
+    "description":{
+      "description": "Product description",
+      "type":"string",
+      "format":"text"
+    },
+    "tag_list":{
+      "description": "Space separated list of tags. Are split and saved as Tag objects on create, update.",
+      "type":"string"
+    },
+    "price":{
+      "description": "Net price of a single product. Max 6 decimal places.",
+      "type":"number",
+      "required":true
+    },
+    "cost":{
+      "description": "Cost price of a single product. Max 6 decimal places.",
+      "type":"number"
+    },
+    "category_name":{
+      "description": "Name of the product category. A new category is created if it does not exist.",
+      "type":"string",
+      "maxLength": 255
+    },
+    "tax":{
+      "description": "Tax percentage for this product.",
+      "type":"number"
+    },
+    "quantity_unit":{
+      "description": "Unit like kg, days, month.",
+      "type":"string",
+      "maxLength": 30
+    },
+    "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
+    },
+    "lock_version":{
+      "description": "Increased on every edit, so SK can detect/prevent a concurrent edit by another user. First save wins.",
+      "type":"integer"
+    }
+  },
+  "links":[
+    { "rel": "self",
+      "href": "products/{id}"
+    },
+    { "rel": "instances",
+      "href": "products",
+      "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 number, name, description, price",
+          "type":["string", "number"]
+        },
+        "filter[contact_ids]":{
+          "title" : "Contact IDs",
+          "description": "Comma-separated list of contact IDs. While present, it will return payments related to all contacts' documents.",
+          "type" : "string"
+        },
+        "filter[number]":{
+          "title" : "By number",
+          "description": "Search by exact number",
+          "type":"string"
+        },
+        "filter[tags]":{
+          "title" : "Tags",
+          "description": "Filter by a space delimited list of tags",
+          "type":"string"
+        },
+        "sort_by":{
+          "title" : "Sort by",
+          "description": "Sort the results by the given field => number",
+          "enum":["name","number","price", "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": "products/{id}",
+      "method": "DELETE"
+    },
+    { "rel": "update",
+      "href": "products/{id}",
+      "method": "PUT"
+    },
+    { "rel": "create",
+      "href": "products",
+      "method": "POST"
+    }
+  ]
+}

data/json/v2.0/recurring.json

@@ -0,0 +1,340 @@
+{ "type":"object",
+  "title": "recurring",
+  "name": "recurring",
+  "description": "An recurring is used as an template for new invoices.",
+  "properties":{
+    "id":{
+      "description":"Unique identifier - UUID",
+      "identity":true,
+      "readonly":true,
+      "type":"string",
+      "maxLength": 22,
+      "minLength":22
+    },
+    "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":{
+      "description": "Receiver address, normally shown in envelope window. Defaults to client address_field if empty and client_id given.",
+      "type":"string"
+    },
+    "date":{
+      "description": "First date the recurring is issued. Not allowed to be in the past. YYYY-MM-DD",
+      "format":"date",
+      "type":"string",
+      "required":true
+    },
+    "due_days":{
+      "description": "Used to calculate the due date of the recurring. Useless if date and due date are present.",
+      "type":"integer"
+    },
+    "final_date":{
+      "description": "The last date the recurring is executed. YYYY-MM-DD",
+      "format":"date",
+      "type":"string",
+      "required":true
+    },
+    "frequency":{
+      "description": "Recurring frequency",
+      "enum":["yearly", "monthly", "weekly", "quarterly", "biweekly", "sixmonthly"],
+      "type":"string",
+      "required":true
+    },
+    "payment_method":{
+      "description": "How the document is being payed. Used in new payments.",
+      "enum":["cash","bank_transfer","credit_card","paypal","direct_debit","cheque", "moneybookers", "premium_sms"],
+      "type":"string"
+    },
+    "external_ref":{
+      "description": "Some external reference, whatever this may be.",
+      "type":"string",
+      "maxLength": 255
+    },
+    "title":{
+      "description": "The headline of a document. Use SK placeholders to prevent excessive typing e.g. 'Your recurring [number]'",
+      "type":"string",
+      "maxLength": 255
+    },
+    "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"
+    },
+    "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"
+    },
+    "tag_list":{
+      "description": "Space separated list of tags. Are split and saved as Tag objects on create, update.",
+      "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 document is emailed or printed, a localized version of a multi-language template(email, pdf) will be used if available. Defaults to the clients language, if empty and a client is assigned.",
+      "type":"string",
+      "maxLength": 10
+    },
+    "currency":{
+      "description": "Currency code as defined by the ISO 4217 standard (3-letter UPCASE: EUR, USD)",
+      "type":"string",
+      "maxLength": 3,
+      "minLength": 3
+    },
+    "sepa_mandate_id":{
+      "description": "SEPA mandate identifier needed in direct debit transactions. This is a unique id given by you to the customer beforehand.",
+      "type":"string",
+      "maxLength": 35
+    },
+    "sepa_mandate_signed_at":{
+      "description": "Date the SEPA mandate was signed by your customer. Must not be in the future!",
+      "format":"date",
+      "type":"string"
+    },
+    "sepa_debit_sequence_type":{
+      "description": "SEPA direct debit sequence type. Check with you bank how they handle FRST(first) and FNAL(final) types. When exporting SEPA debit to your bank the type defaults to OOF if blank.",
+      "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,
+      "type":"object",
+      "properties":{"$ref":"./contact.json#properties"}
+    },
+    "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.",
+      "type":"string",
+      "maxLength": 22,
+      "minLength":22
+    },
+    "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,
+      "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.",
+      "type":"array",
+      "default": "any",
+      "minItems": 0,
+      "items": [{ "$ref": "./line_item.json#properties"},
+                { "$ref":  "./divider_item.json#properties"},
+                { "$ref": "./sub_total_item.json#properties"}]
+    },
+    "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"
+    },
+    "lock_version":{
+      "description": "Auto-incremented to prevent concurrent updates. First save wins and increments version. ",
+      "type":"integer"
+    },
+    "gross_total":{
+      "description": "Gross total of all line items, 2 decimals places",
+      "readonly":true,
+      "type":"number"
+    },
+    "tax_total":{
+      "description": "Tax total, 2 decimals places",
+      "readonly":true,
+      "type":"number"
+    },
+    "net_total":{
+      "description": "Net total, 2 decimals places",
+      "readonly":true,
+      "type":"number"
+    },
+    "net_total_base":{
+      "description": "Net total, 6 decimal places incl. discount",
+      "readonly":true,
+      "type":"number"
+    },
+    "cost_total":{
+      "description": "Cost total of all line items, 2 decimals places in document currency.",
+      "readonly":true,
+      "type":"number"
+    },
+    "gross_margin_total":{
+      "description": "Total gross margin across all line items. Calculated from net_total-cost_total.",
+      "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,
+      "type":"number"
+    },
+    "pdf_template_id":{
+      "description": "The PDF template used for printing the invoice when auto sending. Required when auto_send'ing is enabled.",
+      "type":"string",
+      "maxLength": 22,
+      "minLength":22
+    },
+    "email_template_id":{
+      "description": "The Email template used for the email in auto sending. Required when auto_send'ing is enabled.",
+      "type":"string",
+      "maxLength": 22,
+      "minLength":22
+    },
+    "auto_send":{
+      "description": "Enable automatic sending of new invoices created from the recurring. Opens the invoice, creates a PDF and sends an email to the contact. GOTCHA's: check PDF-, Email-Template, SMTP Settings and of course the contacts email address! Since new recurrings which start today directly create new invoices, they are also SEND if auto_send is true!! If something fails, we'll send an error-email to the user who created the recurring. For success infos you can add yourself to the BCC of the email template or",
+      "default": null,
+      "type": "string",
+      "enum":["email"]
+    }
+  },
+  "links":[
+    { "rel": "self",
+      "href": "recurrings/{id}"
+    },
+    { "rel": "instances",
+      "href": "recurrings",
+      "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 title, number, address field",
+          "type":"string"
+        },
+        "filter[tags]":{
+          "title" : "Tags",
+          "description": "Filter by a space delimited list of tags",
+          "type":"string"
+        },
+        "filter[from]":{
+          "title" : "From date",
+          "description": "Objects with a date after the date. YYYY-MM-DD",
+          "format" : "date",
+          "type" : "string"
+        },
+        "filter[to]":{
+          "title" : "To date",
+          "description": "Objects with date before the date",
+          "format" : "date",
+          "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[languages]":{
+          "title" : "Languages",
+          "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.",
+          "type" : "string"
+        },
+        "filter[ids]":{
+          "title" : "Documents",
+          "description": "A single or a list of document uuids, comma separated",
+          "type" : "string"
+        },
+        "filter[creator_ids]":{
+          "title" : "Creator",
+          "description": "Objects created by the given users uuids, comma separated",
+          "type" : "string"
+        },
+        "filter[product_ids]":{
+          "title" : "Products",
+          "description": "Documents using the given product uuids(comma separated) in their line items.",
+          "type" : "string"
+        },
+        "sort_by":{
+          "title" : "Sort by",
+          "description": "Sort the results by the given field => number",
+          "enum":["title", "number", "created_at", "updated_at", "price_total"],
+          "type": "string"
+        },
+        "sort":{
+          "title" : "Sort",
+          "enum":["ASC","DESC"],
+          "description": "Sort the results in ASC or DESC",
+          "type": "string"
+        }
+      }
+    },
+    { "rel": "destroy",
+      "href": "recurrings/{id}",
+      "method": "DELETE"
+    },
+    { "rel": "update",
+      "href": "recurrings/{id}",
+      "method": "PUT"
+    },
+    { "rel": "create",
+      "href": "recurrings",
+      "method": "POST",
+      "properties" : {
+        "source" : {
+          "title" : "Source document id",
+          "description": "Copies the source(excl. number,date) and returns a new draft document. You can pass any document type(e.g. invoice, order). Fields passed with the object(e.g. notes, title, address_field) are not overwritten.",
+          "type" : "string"
+        }
+      }
+    },
+    { "rel": "invoices",
+      "href": "invoices?filter[recurring_ids]={id}"
+    },
+    { "rel": "attachments",
+      "href": "recurrings/{id}/attachments"
+    },
+    { "rel": "comments",
+      "href": "recurrings/{id}/comments"
+    }
+  ]
+}