sk_api_schema 0.10.5 → 0.10.6

data/json/v2.0/payment.json

@@ -0,0 +1,148 @@
+{ "type":"object",
+  "title": "payment",
+  "name": "payment",
+  "description":"An payment must always be related to an document, so you must use the nested URL e.g. POST invoices/ID/payments. In this case the related_object_id/type are automatically set.",
+  "properties":{
+    "id":{
+      "description":"Unique identifier - UUID",
+      "identity":true,
+      "readonly":true,
+      "type":"string",
+      "maxLength": 22,
+      "minLength":22
+    },
+    "amount":{
+      "description": "The payment amount",
+      "required":true,
+      "type":"number"
+    },
+    "cash_discount":{
+      "description": "The cash discount amount. If a client withdraws a cash discount say 2% of 100€, he pays 98€ used in amount and 2€ in cash_discount. Handled separate for correction of sales,vat accounts in bookkeeping.",
+      "type":"number"
+    },
+    "is_partial":{
+      "description": "If set the related document is NOT closed.",
+      "type":"boolean",
+      "default": false
+    },
+    "external_ref":{
+      "description": "Reference number f.ex. issued by the bank.",
+      "type":"string",
+      "maxLength": 255
+    },
+    "date":{
+      "description": "Date the payment was made. YYYY-MM-DD",
+      "required":true,
+      "format":"date",
+      "type":"string"
+    },
+    "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"
+    },
+    "amount_exchanged":{
+      "description": "The exchanged amount.",
+      "readonly":true,
+      "type":"number"
+    },
+    "payment_method":{
+      "description": "How the payment was made.",
+      "enum":["cash","bank_transfer","credit_card","paypal","direct_debit","cheque", "moneybookers", "premium_sms"],
+      "type":"string"
+    },
+    "late_fee":{
+      "description": "Add a late fee if an invoice has payment reminders. We create a second payment for the last reminder and close all others. Set to 0, if you want to waive the fee(has not been paid). In this case all reminders are closed and we also correct the sales+debtor account with the open fees. This is a pure setter-method used in creation!",
+      "type":"number"
+    },
+    "related_object_type":{
+      "description": "Object type of the payments parent. Is the camel-cased base class name: Document for invoice, credit_note. Is auto-set when using the nested URL POST invoices/ID/payments",
+      "required":true,
+      "type":"string"
+    },
+    "related_object_id":{
+      "description": "uuid of the payments parent object. Is auto-set when using the nested URL POST invoices/ID/payments",
+      "required":true,
+      "type":"string",
+      "maxLength": 22,
+      "minLength":22
+    },
+    "team_id":{
+      "description": "A team uuid taken from the related object(e.g.invoice). If set only the team and its parent teams can see the record.",
+      "readonly" :true,
+      "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"
+    }
+  },
+   "links":[
+    { "rel": "self",
+      "href": "payments/{id}"
+    },
+    { "rel": "instances",
+      "href": "payments",
+      "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[from]":{
+          "title" : "From date",
+          "description": "All objects with a date after the date. YYYY-MM-DD",
+          "format" : "date",
+          "type" : "string"
+
+        },
+        "filter[to]":{
+          "title" : "To date",
+          "description": "All objects with date before the date. YYYY-MM-DD",
+          "format" : "date",
+          "type" : "string"
+        },
+        "sort_by":{
+          "title" : "Sort by",
+          "description": "Sort the results by the given field => number",
+          "enum":["amount","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": "payments/{id}",
+      "method": "DELETE"
+    },
+    { "rel": "create",
+      "href": "payments",
+      "method": "POST"
+    }
+  ]
+}

data/json/v2.0/payment_reminder.json

@@ -0,0 +1,301 @@
+{ "type":"object",
+  "title": "payment_reminder",
+  "name": "payment_reminder",
+  "description": "A payment reminder belongs to an invoice and inherits it's line items from the invoice total(first item) and late fee settings(second item).",
+  "properties":{
+    "id":{
+      "description":"Unique identifier - UUID",
+      "identity":true,
+      "readonly":true,
+      "type":"string",
+      "maxLength": 22,
+      "minLength":22
+    },
+    "invoice_id":{
+      "description": "The invoice for the reminder. If set assumes all other fields are set to custom values, instead of filling them from the invoice. POSTing to invoices/:id/payment_reminders, automatically set this and all other fields.",
+      "required": true,
+      "type":"string",
+      "maxLength": 22,
+      "minLength":22
+    },
+    "address_field":{
+      "description": "Receiver address, shown in envelope window. Defaults to invoice.client.address_field if created from invoice.",
+      "type":"string"
+    },
+    "date":{
+      "description": "Date the payment_reminder is issued. Automatically set when created from invoice. Defaults to today. YYYY-MM-DD",
+      "format":"date",
+      "required": true,
+      "type":"string"
+    },
+    "due_days":{
+      "description": "Used to calculate the due date of the payment_reminder. Useless if date and due date are present. Taken from settings when created from invoice",
+      "type":"integer"
+    },
+    "due_date":{
+      "description": "Auto-calculated from date + due days if empty and the payment_reminder is opened. YYYY-MM-DD",
+      "format":"date",
+      "type":"string"
+    },
+    "status":{
+      "description": "Defaults to open for new reminders, unless otherwise stated. Beware that the overdue-status is virtual as it depends on the real status=open and the document due_date.",
+      "default":"open",
+      "enum":["draft","open","closed","overdue"],
+      "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 payment_reminder [number]'. Defaults to values from settings",
+      "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. Defaults to values from settings",
+      "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. Defaults to values from settings",
+      "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. Is assigned through the related invoice.",
+      "readonly":true,
+      "type":"object",
+      "properties":{"$ref":"./contact.json#properties"}
+    },
+    "contact_id":{
+      "description": "The contact uuid. Is assigned through the related invoice.",
+      "readonly":true,
+      "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. GOTCHAs: you should NOT create items manually since we create them. The first item contains the invoice total and the optional second one the late_fee.",
+      "type":"array",
+      "default": "any",
+      "minItems": 1,
+      "items": { "$ref": "./line_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": "DEPRECATED use net_total bcs there are no taxes applied",
+      "readonly":true,
+      "type":"number"
+    },
+    "net_total":{
+      "description": "Net total, 2 decimals places",
+      "readonly":true,
+      "type":"number"
+    }
+  },
+  "links":[
+    { "rel": "self",
+      "href": "payment_reminders/{id}"
+    },
+    { "rel": "instances",
+      "href": "payment_reminders",
+      "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": "All objects with a date after the date. YYYY-MM-DD",
+          "format" : "date",
+          "type" : "string"
+        },
+        "filter[to]":{
+          "title" : "To date",
+          "description": "All objects with date before the date. YYYY-MM-DD",
+          "format" : "date",
+          "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[status]":{
+          "title" : "Status",
+          "description": "A single or a list of status, comma separated: open,closed,overdue,draft",
+          "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": "payment_reminders/{id}",
+      "method": "DELETE"
+    },
+    { "rel": "update",
+      "href": "payment_reminders/{id}",
+      "method": "PUT"
+    },
+    { "rel": "create",
+      "href": "payment_reminders",
+      "method": "POST"
+    },
+    { "rel": "attachments",
+      "href": "payment_reminders/{id}/attachments"
+    },
+    { "rel": "emails",
+      "href": "payment_reminders/{id}/emails"
+    },
+    { "rel": "emails create",
+      "href": "payment_reminders/{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": "payment_reminders/{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."
+        }
+      }
+    }
+  ]
+}

data/json/v2.0/pdf_template.json

@@ -0,0 +1,99 @@
+{ "type":"object",
+  "title": "pdf_template",
+  "name": "pdf_template",
+  "description":"An PDF template. For now this is a read-only resource ONLY returning your own templates. It fits the most important use-case: A user can select a print template.",
+  "properties":{
+    "id":{
+      "description":"Unique identifier - UUID",
+      "identity":true,
+      "readonly":true,
+      "type":"string",
+      "maxLength": 22,
+      "minLength":22
+    },
+    "name":{
+      "description": "Name of the template as shown to the user.",
+      "required":true,
+      "type":"string",
+      "maxLength": 50
+    },
+    "description":{
+      "description": "Additional information about the template.",
+      "type":"string",
+      "format":"text"
+    },
+    "kind":{
+      "description": "Kind of object the template can be used for.",
+      "required":true,
+      "enum": ["invoice", "estimate", "credit_note", "payment_reminder", "order"],
+      "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 should belong to a parent. From then on just choose the parent-template and the localized child version is used for printing if the related object(order, invoice,..) 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": "pdf_templates/{id}"
+    },
+    { "rel": "instances",
+      "href": "pdf_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",
+          "default":"name",
+          "enum":["created_at", "updated_at", "name", "kind"],
+          "type": "string"
+        },
+        "sort":{
+          "title" : "Sort",
+          "description": "Sort the results in ASC or DESC",
+          "type":"string",
+          "enum":["ASC","DESC"]
+        },
+        "filter[q]":{
+          "title" : "Search wildcard",
+          "description": "Searches in name, description",
+          "type":"string"
+        },
+        "filter[kind]":{
+          "title" : "Search by kind",
+          "description": "Kind of object this template can be used for: invoice, order",
+          "type":"string",
+          "enum":["invoice","estimate", "credit_note", "payment_reminder", "order"]
+        }
+      }
+    }
+  ]
+}