sk_api_schema 0.10.5 → 0.10.6

data/json/v2.0/email.json

@@ -0,0 +1,191 @@
+{ "type":"object",
+  "title": "email",
+  "name": "email",
+  "description":"An email in SK must always be related to an object. Receivers are limited to 5 per address field.",
+  "properties":{
+    "id":{
+      "description":"Unique identifier - UUID",
+      "identity":true,
+      "readonly":true,
+      "type":"string",
+      "maxLength": 22,
+      "minLength":22
+    },
+    "bcc_addr":{
+      "description": "BCC addresses, comma separated. Max 5, format: a@b.de,'George'<georg@sk.eu>",
+      "type":"string",
+      "format":"text"
+    },
+    "cc_addr":{
+      "description": "CC addresses, comma separated. Max 5, format: a@b.de,'George'<georg@sk.eu>",
+      "type":"string",
+      "format":"text"
+    },
+    "from_addr":{
+      "description": "From address. If empty the email of the current user is taken.",
+      "type":"string",
+      "maxLength": 255
+    },
+    "to_addr":{
+      "description": "TO addresses, comma separated. Max 5, format: a@b.de,'George'<georg@sk.eu>",
+      "required":true,
+      "type":"string",
+      "format":"text"
+    },
+    "subject":{
+      "description": "The email subject.",
+      "required":true,
+      "type":"string",
+      "maxLength": 255
+    },
+    "body":{
+      "description": "The email text.",
+      "required":true,
+      "type":"string",
+      "format":"text"
+    },
+    "attachments":{
+      "description": "The emails attachments.",
+      "readonly":true,
+      "type":"array",
+      "properties":{"$ref":"./attachment.json#properties"}
+    },
+    "related_object_type":{
+      "description": "Object type of the emails parent. Is the camelcased base class name: Document for invoice, credit_note, contact,..",
+      "required":true,
+      "type":"string"
+    },
+    "related_object_id":{
+      "description": "uuid of the emails parent object.",
+      "required":true,
+      "type":"string",
+      "maxLength": 22,
+      "minLength":22
+    },
+    "in_progress":{
+      "description": "Is set after an email has been scheduled for sending until it has been sent.",
+      "readonly":true,
+      "type":"boolean"
+    },
+    "log":{
+      "description": "Logs error message when sending failed.",
+      "readonly":true,
+      "type":"text"
+    },
+    "delivered_at":{
+      "description": "Date the email was delivered by SK. If set, the message cannot be edited anymore.",
+      "format":"date-time",
+      "readonly":true,
+      "type":"string"
+    },
+    "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 taken from the related object. If set only the team and its parent teams can see the record.",
+      "readonly" :true,
+      "type":"string",
+      "maxLength": 22,
+      "minLength":22
+    }
+  },
+   "links":[
+    { "rel": "self",
+      "href": "emails/{id}"
+    },
+    { "rel": "instances",
+      "href": "emails",
+      "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 body and subject",
+          "type":"string"
+        },
+        "filter[status]":{
+          "title" : "Emails by status",
+          "description": "Show only sent, draft or emails in progress. The status is virtual and checks the delivered_at and in_progress field values.",
+          "enum":["draft", "sent", "in_progress" ]
+        },
+        "filter[address]":{
+          "title" : "Search in address",
+          "description": "Searches in all address fields: bcc, cc, to, from"
+        },
+        "filter[from]":{
+          "title" : "From date",
+          "description": "All objects updated on/after the date. YYYY-MM-DD",
+          "format" : "date",
+          "type" : "string"
+        },
+        "filter[to]":{
+          "title" : "To date",
+          "description": "All objects updated on/before the date. YYYY-MM-DD",
+          "format" : "date",
+          "type" : "string"
+        },
+        "sort_by":{
+          "title" : "Sort by",
+          "description": "Sort the results by the given field",
+          "enum":["created_at", "updated_at"],
+          "type": "string"
+        },
+        "sort":{
+          "title" : "Sort",
+          "enum":["ASC","DESC"],
+          "description": "Sort the results in ASC or DESC",
+          "type": "string"
+        }
+      }
+    },
+    { "rel": "attachments",
+      "href": "emails/{id}/attachments"
+    },
+    { "rel": "destroy",
+      "href": "emails/{id}",
+      "method": "DELETE"
+    },
+    { "rel": "update",
+      "href": "emails/{id}",
+      "method": "PUT"
+    },
+    { "rel": "create",
+      "href": "emails",
+      "method": "POST",
+      "properties" : {
+        "template_id":{
+          "title" : "Template",
+          "description": "UUID of an email template to use. If present, subject, body and attachments of the template are used for the current email.",
+          "type":"string",
+          "maxLength": 22,
+          "minLength":22
+        },
+        "send":{
+          "title" : "Send email",
+          "description": "Schedule email for sending. Omit this parameter or set value to 0 or false(String or Integer) to keep email as draft."
+        },
+        "archived_pdf":{
+          "title" : "Attach archived pdf",
+          "description": "Adds the archived pdf from the related resource(if it has one)."
+        }
+      }
+    }
+  ]
+}

data/json/v2.0/email_template.json

@@ -0,0 +1,132 @@
+{ "type":"object",
+  "title": "email_template",
+  "name": "email_template",
+  "description":"An email_template is used to simplify the creation of emails. When creating a new email just pass template id and all fields from the template are copied to the new email. The fields are NOT merged with present values in a new email object!",
+  "properties":{
+    "id":{
+      "description":"Unique identifier - UUID",
+      "identity":true,
+      "readonly":true,
+      "type":"string",
+      "maxLength": 22,
+      "minLength":22
+    },
+    "name":{
+      "description": "A meaningful name.",
+      "required":true,
+      "type":"string",
+      "maxLength": 50
+    },
+    "subject":{
+      "description": "Subject containing placeholders, replaced when the template is used.",
+      "required":true,
+      "type":"string",
+      "maxLength": 255
+    },
+    "body":{
+      "description": "Body with placeholders, replaced when the template is used.",
+      "required":true,
+      "type":"string",
+      "format":"text"
+    },
+    "from_addr":{
+      "description": "Default from address. A valid email address. Make sure your server(if custom SMPT settings for the API user) allows sending with this address.",
+      "type":"string",
+      "maxLength": 255
+    },
+    "cc_addr":{
+      "description": "Default copy receivers comma separated valid email addresses.",
+      "type":"string",
+      "maxLength": 255
+    },
+    "bcc_addr":{
+      "description": "Default blind copy receivers comma separated valid email addresses. ",
+      "type":"string",
+      "maxLength": 255
+    },
+    "kind":{
+      "description": "Kind of object the template can be used for.",
+      "required":true,
+      "enum": ["invoice", "estimate", "credit_note", "payment_reminder", "order", "contact"],
+      "type":"string"
+    },
+    "language":{
+      "description": "Should be a valid language short-code: de-DE, fr, en-GB; like defined in your account language menu. A multi-language template must belong to a parent. From then on just choose the parent-template and the localized child version is used if the related object(client, invoice,..) of the email, has the appropriate language.",
+      "type":"string",
+      "maxLength": 10
+    },
+    "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
+    }
+  },
+   "links":[
+    { "rel": "self",
+      "href": "email_templates/{id}"
+    },
+    { "rel": "instances",
+      "href": "email_templates",
+      "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"
+        },
+        "sort_by":{
+          "title" : "Sort by",
+          "description": "Sort the results by the given field",
+          "enum":["created_at", "updated_at"],
+          "type": "string"
+        },
+        "sort":{
+          "title" : "Sort",
+          "enum":["ASC","DESC"],
+          "description": "Sort the results in ASC or DESC",
+          "type":"string"
+        },
+        "filter[q]":{
+          "title" : "Search wildcard",
+          "description": "Searches in name, body, subject",
+          "type":"string"
+        },
+        "filter[kind]":{
+          "title" : "Search by kind",
+          "description": "Kind of object this template can be used for",
+          "enum": ["invoice", "estimate", "credit_note", "payment_reminder", "order", "contact"],
+          "type":"string"
+        }
+      }
+    },
+    { "rel": "destroy",
+      "href": "email_templates/{id}",
+      "method": "DELETE"
+    },
+    { "rel": "update",
+      "href": "email_templates/{id}",
+      "method": "PUT"
+    },
+    { "rel": "create",
+      "href": "email_templates",
+      "method": "POST"
+    }
+  ]
+}

data/json/v2.0/estimate.json

@@ -0,0 +1,408 @@
+{ "type":"object",
+  "title": "estimate",
+  "name": "estimate",
+  "description": "An estimate",
+  "properties":{
+    "id":{
+      "description":"Unique identifier - UUID",
+      "identity":true,
+      "readonly":true,
+      "type":"string",
+      "maxLength": 22,
+      "minLength":22
+    },
+    "number":{
+      "description": "Unique number assigned by SK estimate number schema. Auto-assigned when estimate is opened. Required unless doc status is draft.",
+      "type":"string",
+      "maxLength": 50
+    },
+    "address_field":{
+      "description": "Receiver address, normally shown in envelope window. Defaults to client address_field if empty and client_id present.",
+      "type":"string"
+    },
+    "date":{
+      "description": "Date the estimate is issued. Automatically set when estimate is opened. Required for non-draft documents. YYYY-MM-DD",
+      "format":"date",
+      "type":"string"
+    },
+    "due_days":{
+      "description": "Used to calculate the valid-until date of the estimate. Useless if date and due date are present.",
+      "type":"integer"
+    },
+    "due_date":{
+      "description": "Auto-calculated from date + due days if empty and the estimate is opened. YYYY-MM-DD",
+      "format":"date",
+      "type":"string"
+    },
+    "status":{
+      "description": "Defaults to draft for new documents, unless otherwise stated. For new documents with status 'open' or 'closed' or doc where the status changes away from draft, following fields are set if empty: number(next in number schema), date(today), due date(due_days must be given). Only draft documents can be deleted.",
+      "default":"draft",
+      "enum":["draft","open","closed","rejected","billed" ],
+      "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 estimate [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
+    },
+    "exchange_rate":{
+      "description": "The exchange rate from the foreign document currency(eg. USD) to the company currency(EUR). If the rate is empty we use the exchange rate on the document date or today if doc.date is empty. If there is no rate for this day, say on weekends, the closest previous day is taken(Sunday->Friday). If you open the doc at a later time make sure to manually refresh the rate, as we dont change it. ",
+      "readonly":true,
+      "type":"number"
+    },
+    "gross_total_exchanged":{
+      "description": "Exchanged gross total, in your company currency.",
+      "readonly":true,
+      "type":"number"
+    },
+    "archived_pdf":{
+      "description": "Archived PDF version of the document. Is created when an document is printed and archived. A document can have multiple archived versions. This only returns the most recent one. ",
+      "readonly":true,
+      "type":"object",
+      "properties":{"$ref":"./attachment.json#properties"}
+    },
+    "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 in document currency.",
+      "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"
+    },
+    "probability":{
+      "description": "Percentage of estimated confidence in closing the deal. Estimated Probability percentage of the net total amount",
+      "type":"number"
+    },
+    "expected_revenue":{
+      "description": "Product of the probability and net total. In company currency.",
+      "readonly":true,
+      "type":"number"
+    },
+    "close_date":{
+      "description": "Date when the deal is expected to be closed.",
+      "type":"number"
+    }
+  },
+  "links":[
+    { "rel": "self",
+      "href": "estimates/{id}"
+    },
+    { "rel": "instances",
+      "href": "estimates",
+      "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[status]":{
+          "title" : "Status",
+          "description": "A single or a list of status, comma separated: open,closed,draft, rejected, billed",
+          "type" : "string"
+        },
+        "filter[number]":{
+          "title" : "Number",
+          "description": "Find by exact number",
+          "type":"string"
+        },
+        "filter[tags]":{
+          "title" : "Tags",
+          "description": "Filter by a space delimited list of tags",
+          "type":"string"
+        },
+        "filter[probability_from]":{
+          "title" : "By probability from",
+          "description": "Find documents with a probability greater(>=) than given number. Minimum is 0 for percent fields, max 100",
+          "type":"number"
+        },
+        "filter[probability_to]":{
+          "title" : "By probability to",
+          "description": "Find accounts with a probability smaller(<=) than given number.",
+          "type":"number"
+        },
+        "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. YYYY-MM-DD",
+          "format" : "date",
+          "type" : "string"
+        },
+        "filter[close_date_from]":{
+          "title" : "Close date from",
+          "description": "Objects with a closing date after the date. YYYY-MM-DD",
+          "format" : "date",
+          "type" : "string"
+        },
+        "filter[close_date_to]":{
+          "title" : "Close date to",
+          "description": "Objects with closing date before the date. YYYY-MM-DD",
+          "format" : "date",
+          "type" : "string"
+        },
+        "filter[created_at_from]":{
+          "title" : "Created from",
+          "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" : "Created to",
+          "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[updated_at_from]":{
+          "title" : "Updated from",
+          "description": "Objects updated 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 updated on this day are included. A time should be already utc time",
+          "format" : "date-time",
+          "type" : "string"
+        },
+        "filter[updated_at_to]":{
+          "title" : "Updated to",
+          "description": "Objects updated 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 updated 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", "price_tax", "date", "due_date"],
+          "type": "string"
+        },
+        "sort":{
+          "title" : "Sort",
+          "enum":["ASC","DESC"],
+          "description": "Sort the results in ASC or DESC",
+          "type": "string"
+        }
+      }
+    },
+    { "rel": "destroy",
+      "href": "estimates/{id}",
+      "method": "DELETE"
+    },
+    { "rel": "update",
+      "href": "estimates/{id}",
+      "method": "PUT"
+    },
+    { "rel": "create",
+      "href": "estimates",
+      "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": "attachments",
+      "href": "estimates/{id}/attachments"
+    },
+    { "rel": "comments",
+      "href": "estimates/{id}/comments"
+    },
+    { "rel": "emails",
+      "href": "estimates/{id}/emails"
+    },
+    { "rel": "emails create",
+      "href": "estimates/{id}/emails",
+      "method": "POST",
+      "properties" : {
+        "template_id":{
+          "title" : "Template",
+          "description": "UUID of an email template to use. If present template fields like subject, body, attachments are used for the current email.",
+          "type":"string",
+          "maxLength": 22,
+          "minLength":22
+        },
+        "send":{
+          "title" : "Send email",
+          "description": "Schedule email for sending. Omit this parameter or set value to 0 or false(String or Integer) to keep email as draft."
+        },
+        "archived_pdf":{
+          "title" : "Attach archived pdf",
+          "description": "Adds the archived pdf from the related resource(if it has one)."
+        }
+      }
+    },
+    { "rel": "print",
+      "href": "estimates/{id}/print",
+      "method": "POST",
+      "properties" : {
+        "template_id" : {
+          "title" : "PDF template used for printing",
+          "description": "UUID of a pdf template used to print the document. MUST be present",
+          "required":true
+        },
+        "base64" : {
+          "title" : "Return the created pdf base64 encoded",
+          "description": "If set the new pdf is returned inside the attachment JSON within 'base64' key. Leave empty to save traffic."
+        }
+      }
+    }
+  ]
+}