├── .prettierignore ├── .ruby-version ├── .gitignore ├── mise.toml ├── favicon.ico ├── favicon.png ├── _sass └── color_schemes │ └── moco.scss ├── _includes └── head_custom.html ├── moco-api-postman.png ├── sections ├── account.md ├── purchase_budgets.md ├── profile.md ├── user_roles.md ├── purchase_categories.md ├── account │ ├── fixed_costs.md │ ├── internal_hourly_rates.md │ ├── hourly_rates.md │ ├── task_templates.md │ ├── expense_templates.md │ ├── custom_properties.md │ └── catalog_services.md ├── purchase_drafts.md ├── offer_customer_approval.md ├── project_groups.md ├── invoice_bookkeeping_exports.md ├── deal_categories.md ├── purchase_bookkeeping_exports.md ├── tags │ ├── tags.md │ └── taggings.md ├── vat_codes.md ├── units.md ├── project_contracts.md ├── holidays.md ├── work_time_adjustments.md ├── project_tasks.md ├── web_hooks.md ├── employments.md ├── purchase_payments.md ├── project_payment_schedules.md ├── schedules.md ├── invoice_payments.md ├── contacts.md ├── planning_entries.md ├── invoice_reminders.md ├── deals.md ├── presences.md ├── comments.md ├── reports.md ├── receipts.md ├── project_recurring_expenses.md ├── companies.md ├── activities.md ├── users.md ├── project_expenses.md ├── purchases.md ├── projects.md └── offers.md ├── Gemfile ├── README.md ├── _config.yml ├── authentication.md ├── custom_fields.md ├── .github └── workflows │ └── jekyll-gh-pages.yml ├── webhooks.md ├── entities.md ├── index.md └── Gemfile.lock /.prettierignore: -------------------------------------------------------------------------------- 1 | *.md -------------------------------------------------------------------------------- /.ruby-version: -------------------------------------------------------------------------------- 1 | 3.2.5 2 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | .idea 2 | _site 3 | -------------------------------------------------------------------------------- /mise.toml: -------------------------------------------------------------------------------- 1 | [tools] 2 | ruby = "3.4" 3 | -------------------------------------------------------------------------------- /favicon.ico: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/everii-Group/mocoapp-api-docs/HEAD/favicon.ico -------------------------------------------------------------------------------- /favicon.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/everii-Group/mocoapp-api-docs/HEAD/favicon.png -------------------------------------------------------------------------------- /_sass/color_schemes/moco.scss: -------------------------------------------------------------------------------- 1 | @import "./color_schemes/light"; 2 | 3 | $link-color: #38b5eb; -------------------------------------------------------------------------------- /_includes/head_custom.html: -------------------------------------------------------------------------------- 1 | -------------------------------------------------------------------------------- /moco-api-postman.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/everii-Group/mocoapp-api-docs/HEAD/moco-api-postman.png -------------------------------------------------------------------------------- /sections/account.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: default 3 | title: Account 4 | parent: Entities 5 | has_children: true 6 | --- 7 | 8 | # Account -------------------------------------------------------------------------------- /Gemfile: -------------------------------------------------------------------------------- 1 | # frozen_string_literal: true 2 | 3 | source "https://rubygems.org" 4 | 5 | gem "jekyll" 6 | gem "just-the-docs" 7 | 8 | group :development do 9 | gem "webrick" 10 | end 11 | 12 | group :jekyll_plugins do 13 | gem "github-pages" 14 | gem "jekyll-default-layout" 15 | end 16 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | --- 2 | nav_exclude: true 3 | --- 4 | 5 | # Moco API Documentation 6 | 7 | This is the official API documentation for mocoapp.com 8 | 9 | The documentation itself is published here: https://everii-group.github.io/mocoapp-api-docs/ 10 | 11 | (👉 [we are hiring](https://www.mocoapp.com/unternehmen/jobs)). -------------------------------------------------------------------------------- /sections/purchase_budgets.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: default 3 | parent: Purchases 4 | grand_parent: Entities 5 | --- 6 | 7 | # Purchase Budgets 8 | 9 | German: "Ausgaben – Budgets" 10 | 11 | - TOC 12 | {:toc} 13 | 14 | ## Attributes 15 | 16 | The purchase budget representation is: 17 | 18 | ```json 19 | { 20 | "id": "2", 21 | "year": 2024, 22 | "title": "Betrieb – Hosting", 23 | "active": true, 24 | "target": 84000, 25 | "exhaused": 66483, 26 | "planned": 4494, 27 | "remaining": 13023 28 | } 29 | ``` 30 | 31 | ## GET /purchases/budgets 32 | 33 | Retrieve budgets for given year: 34 | 35 | ```bash 36 | curl -X GET \ 37 | 'https://{domain}.mocoapp.com/api/v1/purchases/budgets?year=2023' \ 38 | -H 'Authorization: Token token=YOUR_API_KEY' 39 | ``` 40 | 41 | This returns an array with complete budget information (see attributes). 42 | 43 | The following parameters can be supplied: 44 | - **year** – 2023 45 | 46 | -------------------------------------------------------------------------------- /sections/profile.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: default 3 | parent: Entities 4 | --- 5 | 6 | # Profile 7 | 8 | German: "Profil" 9 | 10 | - TOC 11 | {:toc} 12 | 13 | ## GET /profile 14 | 15 | Get the current user's profile. If [impersonation](../index#impersonation) is used, it's the impersonated user. 16 | 17 | ```bash 18 | curl -X GET \ 19 | 'https://{domain}.mocoapp.com/api/v1/profile' \ 20 | -H 'Authorization: Token token=YOUR_API_KEY' 21 | ``` 22 | 23 | The profile returned: 24 | 25 | ```json 26 | { 27 | "id": 237852983, 28 | "email": "janine.kuesters@meinefirma.de", 29 | "full_name": "Janine Küsters", 30 | "first_name": "Janine", 31 | "last_name": "Küsters", 32 | "active": true, 33 | "external": false, 34 | "avatar_url": "https://data.mocoapp.com/objects/6bf3db0a-895a-46a1-8006-6280af04b9c0.jpg", 35 | "unit": { 36 | "id": 436796, 37 | "name": "Design" 38 | }, 39 | "created_at": "2018-10-17T09:33:46Z", 40 | "updated_at": "2022-08-02T14:21:56Z" 41 | } 42 | ``` -------------------------------------------------------------------------------- /_config.yml: -------------------------------------------------------------------------------- 1 | domain: everii-group.github.io 2 | title: MOCO API docs 3 | description: mocoapp.com REST API documentation 4 | theme: just-the-docs 5 | 6 | url: https://everii-group.github.io 7 | baseurl: /mocoapp-api-docs 8 | logo: "https://www.mocoapp.com/custom-assets/logo_moco.svg" 9 | 10 | color_scheme: moco 11 | 12 | aux_links: # remove if you don't want this link to appear on your pages 13 | Github: https://github.com/everii-group/mocoapp-api-docs 14 | heading_anchors: true 15 | kramdown: 16 | toc_levels: "2,3" 17 | 18 | callouts: 19 | warning: 20 | title: Warning 21 | color: red 22 | note: 23 | title: Note 24 | color: yellow 25 | 26 | plugins: 27 | - jekyll-default-layout 28 | 29 | # Footer "Edit this page on GitHub" link text 30 | gh_edit_link: true # show or hide edit this page link 31 | gh_edit_link_text: "Edit this page on GitHub" 32 | gh_edit_repository: "https://github.com/everii-group/mocoapp-api-docs" # the github URL for your repo 33 | gh_edit_branch: "master" # the branch that your docs is served from 34 | gh_edit_view_mode: "tree" # "tree" or "edit" if you want the user to jump into the editor immediately 35 | -------------------------------------------------------------------------------- /sections/user_roles.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: default 3 | parent: Entities 4 | --- 5 | 6 | # User permission roles 7 | 8 | German: "Benutzerrollen" 9 | 10 | - TOC 11 | {:toc} 12 | 13 | ## Attributes 14 | 15 | The representation contains among the standard fields also: 16 | 17 | - permission (the permission granted with this role) 18 | 19 | ```json 20 | { 21 | "id": 42, 22 | "name": "Entwickler", 23 | "is_default": false, 24 | "is_admin": false, 25 | "permission": { 26 | "report": "none", 27 | "companies": "full", 28 | "contacts": "full", 29 | "people": "none", 30 | "purchases": "none", 31 | "settings": "none", 32 | "sales": "none", 33 | "projects": "full", 34 | "calendar": "full", 35 | "time_tracking": "full", 36 | "invoicing": "none" 37 | }, 38 | "created_at": "2024-10-17T09:33:46Z", 39 | "updated_at": "2024-10-17T09:33:46Z" 40 | } 41 | ``` 42 | 43 | ## GET /users/roles 44 | 45 | Retrieve all the roles: 46 | 47 | ```bash 48 | curl -X GET \ 49 | 'https://{domain}.mocoapp.com/api/v1/users/roles' \ 50 | -H 'Authorization: Token token=YOUR_API_KEY' 51 | ``` 52 | 53 | This returns an array with complete role information (see Attributes). 54 | -------------------------------------------------------------------------------- /sections/purchase_categories.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: default 3 | parent: Purchases 4 | grand_parent: Entities 5 | --- 6 | 7 | # Purchase Categories 8 | 9 | German: "Ausgaben – Kategorien" 10 | 11 | - TOC 12 | {:toc} 13 | 14 | ## Attributes 15 | 16 | The purchase category representation is: 17 | 18 | ```json 19 | { 20 | "id": 123, 21 | "name": "Travel expenses", 22 | "credit_account": "6640", 23 | "active": true, 24 | "created_at": "2018-10-17T09:33:46Z", 25 | "updated_at": "2018-10-17T09:33:46Z" 26 | } 27 | ``` 28 | 29 | ## GET /purchases/categories 30 | 31 | Retrieve all categories: 32 | 33 | ```bash 34 | curl -X GET \ 35 | 'https://{domain}.mocoapp.com/api/v1/purchases/categories' \ 36 | -H 'Authorization: Token token=YOUR_API_KEY' 37 | ``` 38 | 39 | This returns an array with complete category information (see attributes). 40 | 41 | The following parameters can be supplied: 42 | 43 | - [Global filters apply](../entities#global-filters) 44 | 45 | ## GET /purchases/categories/{id} 46 | 47 | Retrieve a single category: 48 | 49 | ```bash 50 | curl -X GET \ 51 | 'https://{domain}.mocoapp.com/api/v1/purchases/categories/{id}' \ 52 | -H 'Authorization: Token token=YOUR_API_KEY' 53 | ``` 54 | 55 | The response is a single category representation. 56 | -------------------------------------------------------------------------------- /sections/account/fixed_costs.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: default 3 | title: Fixed Costs 4 | parent: Account 5 | grand_parent: Entities 6 | --- 7 | 8 | # Fixed Costs 9 | 10 | German: "Fixkosten" 11 | 12 | - TOC 13 | {:toc} 14 | 15 | ## Attributes 16 | 17 | The representation contains, among the standard fields, also: 18 | 19 | ```json 20 | { 21 | "id": 123, 22 | "title": "Salaries", 23 | "description": "Monhtly total salaries for the company", 24 | "costs": [ 25 | { 26 | "year": 2020, 27 | "month": 1, 28 | "amount": 100000.0 29 | }, 30 | { 31 | "year": 2020, 32 | "month": 2, 33 | "amount": 100000.0 34 | }, 35 | { 36 | "year": 2020, 37 | "month": 3, 38 | "amount": 100000.0 39 | } 40 | ], 41 | "created_at": "2018-10-17T09:33:46Z", 42 | "updated_at": "2018-10-17T09:33:46Z" 43 | } 44 | ``` 45 | 46 | ## GET /account/fixed_costs 47 | 48 | Retrieve all fixed costs 49 | 50 | ```bash 51 | curl -X GET \ 52 | 'https://{domain}.mocoapp.com/api/v1/account/fixed_costs' \ 53 | -H 'Authorization: Token token=YOUR_API_KEY' 54 | ``` 55 | 56 | This returns complete fixed cost information (see Attributes). 57 | 58 | Additionally, the following parameters can be supplied: 59 | 60 | - **year** – 2020 (limit costs to a specific year) 61 | -------------------------------------------------------------------------------- /sections/purchase_drafts.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: default 3 | parent: Purchases 4 | grand_parent: Entities 5 | --- 6 | 7 | # Purchase Drafts 8 | 9 | German: "Ausgaben – Entwürfe" 10 | 11 | - TOC 12 | {:toc} 13 | 14 | ## Attributes 15 | 16 | The purchase draft representation is: 17 | 18 | ```json 19 | { 20 | "id": 123, 21 | "title": "Ticket", 22 | "email_from": "john@example.com", 23 | "email_body": "here the ticket", 24 | "user": { 25 | "id": 933590696, 26 | "firstname": "John", 27 | "lastname": "Doe" 28 | }, 29 | "file_url": "https://...", 30 | "created_at": "2021-10-17T09:33:46Z", 31 | "updated_at": "2021-10-17T09:33:46Z" 32 | } 33 | ``` 34 | 35 | ## GET /purchases/drafts 36 | 37 | Retrieve all drafts: 38 | 39 | ```bash 40 | curl -X GET \ 41 | 'https://{domain}.mocoapp.com/api/v1/purchases/drafts' \ 42 | -H 'Authorization: Token token=YOUR_API_KEY' 43 | ``` 44 | 45 | This returns an array with complete draft information (see attributes). 46 | 47 | The following parameters can be supplied: 48 | 49 | - [Global filters apply](../entities#global-filters) 50 | 51 | ## GET /purchases/drafts/{id} 52 | 53 | Retrieve a single draft: 54 | 55 | ```bash 56 | curl -X GET \ 57 | 'https://{domain}.mocoapp.com/api/v1/purchases/drafts/{id}' \ 58 | -H 'Authorization: Token token=YOUR_API_KEY' 59 | ``` 60 | 61 | The response is a single draft representation. 62 | 63 | ## GET /purchases/drafts/{id}.pdf 64 | 65 | Retrieve the draft document: 66 | 67 | ```bash 68 | curl -X GET \ 69 | 'https://{domain}.mocoapp.com/api/v1/purchases/drafts/{id}.pdf' \ 70 | -H 'Authorization: Token token=YOUR_API_KEY' 71 | ``` 72 | 73 | This returns this draft's document if it's a PDF. Otherwise it responds with 204 No Content. 74 | -------------------------------------------------------------------------------- /authentication.md: -------------------------------------------------------------------------------- 1 | # Authentication 2 | 3 | There's two ways to authenticate against MOCO: 4 | 5 | 1. **User API key**. Can be found under the "Integrations" tab on the profile page. 6 | 2. **Account API key**. Has to be created in Settings > Extensions > API & Webhooks, with either read-only or full access on all endpoints. 7 | 8 | Both kinds of keys are provided as an Authorization header. 9 | 10 | ```bash 11 | curl -X GET \ 12 | 'https://{domain}.mocoapp.com/api/v1/projects.json' \ 13 | -H 'Authorization: Token token=YOUR_API_KEY' 14 | ``` 15 | 16 | This key can also be requested via API for user-specific keys: 17 | 18 | ```bash 19 | curl -X POST \ 20 | https://{domain}.mocoapp.com/api/v1/session \ 21 | -H 'Accept: application/json' \ 22 | -H 'Content-Type: application/json' \ 23 | -d '{ 24 | "email": "max@muster.de", 25 | "password": "secret" 26 | }' 27 | ``` 28 | 29 | It's also possible to verify if the API key is still valid: 30 | 31 | ```bash 32 | curl https://{domain}.mocoapp.com/api/v1/session \ 33 | -H 'Accept: application/json' \ 34 | -H 'Content-Type: application/json' 35 | ``` 36 | 37 | If the key is valid, the response code id `200 ok` and the body is: 38 | 39 | ```json 40 | { 41 | "id": 123, 42 | "uuid": "aec324a2-4832-11eb-b378-0242ac130002" 43 | } 44 | ``` 45 | 46 | otherwise the response code is `401 unauthorized`. 47 | 48 | ## Postman example 49 | 50 | There are a few tools to try out the MOCO API. All the examples in this documentation use `curl` to demonstrate the API endpoint. 51 | A popular graphical UI for REST is [Postman](https://www.postman.com/). Here's an example request for the projects list including the authentication: 52 | 53 | ![Postman example request](moco-api-postman.png "Postman example request") 54 | -------------------------------------------------------------------------------- /sections/account/internal_hourly_rates.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: default 3 | title: Internal Hourly Rates 4 | parent: Account 5 | grand_parent: Entities 6 | --- 7 | 8 | # Internal Hourly Rates 9 | 10 | German: "Interne Stundensätze" 11 | 12 | - TOC 13 | {:toc} 14 | 15 | ## GET /account/internal_hourly_rates 16 | 17 | Retrieve internal hourly rates: 18 | 19 | ```bash 20 | curl -X GET \ 21 | 'https://{domain}.mocoapp.com/api/v1/account/internal_hourly_rates' \ 22 | -H 'Authorization: Token token=YOUR_API_KEY' 23 | ``` 24 | 25 | The following parameters can be supplied: 26 | 27 | - **years** – 2021 or 2020,2021 (single year or multiple years comma-separated) 28 | - **unit_id** – 1234 29 | - **include_archived** - include deactivated users 30 | 31 | returns: 32 | 33 | ```json 34 | [ 35 | { 36 | "id": 933589613, 37 | "full_name": "Daniela Demo", 38 | "rates": [ 39 | { 40 | "year": 2020, 41 | "rate": 120.0 42 | }, 43 | { 44 | "year": 2021, 45 | "rate": 130.0 46 | } 47 | ] 48 | }, 49 | { 50 | "id": 933618769, 51 | "full_name": "Max Muster", 52 | "rates": [ 53 | { 54 | "year": 2020, 55 | "rate": 110.0 56 | }, 57 | { 58 | "year": 2021, 59 | "rate": 120.0 60 | } 61 | ] 62 | } 63 | ] 64 | ``` 65 | 66 | ## PATCH /account/internal_hourly_rates 67 | 68 | Update internal hourly rates 69 | 70 | ```bash 71 | curl -X PUT \ 72 | 'https://{domain}.mocoapp.com/api/v1/account/internal_hourly_rates' \ 73 | -H 'Authorization: Token token=YOUR_API_KEY' \ 74 | -H 'Content-Type: application/json' \ 75 | -d '{ 76 | "year": 2021, 77 | "rates": [ 78 | { 79 | "user_id": 933589613, 80 | "rate": 140.0 81 | }, 82 | { 83 | "user_id": 933618769, 84 | "rate": 130.0 85 | } 86 | ] 87 | }' 88 | ``` 89 | -------------------------------------------------------------------------------- /sections/offer_customer_approval.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: default 3 | parent: Offers 4 | grand_parent: Entities 5 | --- 6 | 7 | # Offer Customer Approval 8 | 9 | German: "Kundenfreigabe" 10 | 11 | - TOC 12 | {:toc} 13 | 14 | ## Attributes 15 | 16 | ```json 17 | { 18 | "id": 123, 19 | "approval_url": "https://.../offers/456/customer_approvals/abcdefhijklmnopqrstuvwxyz1234567890", 20 | "offer_document_url": "https://.../offers/456/customer_approvals/abcdefhijklmnopqrstuvwxyz1234567890/document.pdf", 21 | "active": false, 22 | "customer_full_name": null, 23 | "customer_email": null, 24 | "signature_url": null, 25 | "signed_at": null, 26 | "created_at": "2024-04-10T08:41:48Z", 27 | "updated_at": "2024-04-10T09:49:43Z" 28 | } 29 | ``` 30 | 31 | ## GET /offers/{id}/customer_approval 32 | 33 | Retrieve an activated customer_approval: 34 | 35 | ```bash 36 | curl -X GET \ 37 | 'https://{domain}.mocoapp.com/api/v1/offers/{id}/customer_approval' \ 38 | -H 'Authorization: Token token=YOUR_API_KEY' 39 | ``` 40 | 41 | This returns the customer approval information (see Attributes) or a 404 if not yet activated. 42 | Evaluate the `signed_at` field to verify if approval was given. 43 | 44 | ## POST /offers/{id}/customer_approval/activate 45 | 46 | Activate a customer approval to generate the `offer_document_url` which can be shared with the customer. 47 | 48 | ```bash 49 | curl -X POST \ 50 | 'https://{domain}.mocoapp.com/api/v1/offers/{id}/customer_approval/activate' \ 51 | -H 'Authorization: Token token=YOUR_API_KEY' 52 | ``` 53 | 54 | This returns the customer approval information (see Attributes). 55 | 56 | ## POST /offers/{id}/customer_approval/deactivate 57 | 58 | Deactivate a customer approval to prevent access/signing. 59 | 60 | ```bash 61 | curl -X PUT \ 62 | 'https://{domain}.mocoapp.com/api/v1/offers/{id}/customer_approval/deactivate' \ 63 | -H 'Authorization: Token token=YOUR_API_KEY' \ 64 | ``` 65 | 66 | This returns the updated customer approval information (see Attributes). 67 | -------------------------------------------------------------------------------- /custom_fields.md: -------------------------------------------------------------------------------- 1 | # Custom Fields 2 | 3 | MOCO supports saving custom fields to many of its resources. These custom fields are readable and writable via the `custom_properties` field. 4 | 5 | {: .note } 6 | Custom fields must first be defined in the MOCO settings. 7 | 8 | {: .note } 9 | The size of the custom_properties field is limitted to 12 kB. 10 | 11 | ```json 12 | "custom_properties": { 13 | "UID": "123-UID-456", 14 | "Line of business": "Automotive" 15 | } 16 | ``` 17 | 18 | Parameters are sent with their name as key: 19 | 20 | ```bash 21 | curl -X POST \ 22 | https://{domain}.mocoapp.com/api/v1/customers \ 23 | -H 'Authorization: Token token=YOUR_API_KEY' \ 24 | -H 'Content-Type: application/json' \ 25 | -d '{ 26 | "name": "Beispiel AG", 27 | "currency": "CHF", 28 | "custom_properties": { 29 | "Line of business": "Automotive" 30 | } 31 | }' 32 | ``` 33 | 34 | All values are encoded as strings, expect for Multiple Choice, which is encoded as an array. 35 | 36 | ```bash 37 | curl -X POST \ 38 | https://{domain}.mocoapp.com/api/v1/customers \ 39 | -H 'Authorization: Token token=YOUR_API_KEY' \ 40 | -H 'Content-Type: application/json' \ 41 | -d '{ 42 | "custom_properties": { 43 | "Line of business": ["Automotive", "Banking"] 44 | } 45 | }' 46 | ``` 47 | 48 | - Single-line input – "Automotive" 49 | - Mehrzeilige Eingabe – "A multiline input..." 50 | - Link – "https://www..." 51 | - Date – "2021-12-31" 52 | - Yes/No – "0", "1" (0 = No, 1 = Yes) 53 | - Single choice – "Value" 54 | - Multiple choice – ["Value 1", "Value 2"] 55 | 56 | 57 | {: .note } 58 | The provided custom properties are merged with the existing custom properties of the entity. That is, only the provided custom properties are updated and the other custom properties of the entity are left unchanged. 59 | 60 | ## Filtering by Custom Fields 61 | 62 | It is possible to filter entities by custom fields, as described in 63 | [Global filters](./entities#filter-by-custom-fields-–-custom_properties) 64 | -------------------------------------------------------------------------------- /sections/project_groups.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: default 3 | parent: Projects 4 | grand_parent: Entities 5 | --- 6 | 7 | # Project Group 8 | 9 | German: "Projektgruppen" 10 | 11 | - TOC 12 | {:toc} 13 | 14 | {: .note } 15 | Assigning projects to a group is possible via the [projects endpoint](projects#put-projectsidassign_project_group) 16 | 17 | ## Attributes 18 | 19 | The project group representation contains, among the standard fields, also: 20 | 21 | - projects 22 | - company 23 | - user 24 | 25 | ```json 26 | { 27 | "id": 234, 28 | "name": "Project Group Name", 29 | "user": { 30 | "id": 933613686, 31 | "firstname": "Jane", 32 | "lastname": "Doe" 33 | }, 34 | "company": { 35 | "id": 760553185, 36 | "name": "Acme Inc." 37 | }, 38 | "budget": 42000.0, 39 | "currency": "EUR", 40 | "info": "An info text", 41 | "custom_properties": {}, 42 | "customer_report_url": "https://mycompany.mocoapp.com/project_groups/961779869/customer_report/1142853e926ee7c4dd7e", 43 | "projects": [ 44 | { 45 | "id": 944958556, 46 | "identifier": "P1234", 47 | "name": "Project Name", 48 | "active": true, 49 | "budget": 10000.0 50 | } 51 | ], 52 | "created_at": "2024-08-16T08:36:44Z", 53 | "updated_at": "2024-08-16T08:36:44Z" 54 | } 55 | ``` 56 | 57 | ## GET /projects/groups 58 | 59 | Retrieve all projects: 60 | 61 | ```bash 62 | curl -X GET \ 63 | 'https://{domain}.mocoapp.com/api/v1/projects/groups' \ 64 | -H 'Authorization: Token token=YOUR_API_KEY' 65 | ``` 66 | 67 | This returns an array with complete project group information (see Attributes). 68 | 69 | The following parameters can be supplied: 70 | 71 | - [Global filters apply](../entities#global-filters) 72 | - **user_id** – 123456 73 | - **company_id** – 123456 74 | 75 | ## GET /projects/groups/{id} 76 | 77 | Retrieve a single project group: 78 | 79 | ```bash 80 | curl -X GET \ 81 | 'https://{domain}.mocoapp.com/api/v1/projects/groups/{id}' \ 82 | -H 'Authorization: Token token=YOUR_API_KEY' 83 | ``` 84 | 85 | This returns a single project group representation. 86 | -------------------------------------------------------------------------------- /.github/workflows/jekyll-gh-pages.yml: -------------------------------------------------------------------------------- 1 | # This workflow uses actions that are not certified by GitHub. 2 | # They are provided by a third-party and are governed by 3 | # separate terms of service, privacy policy, and support 4 | # documentation. 5 | 6 | # Sample workflow for building and deploying a Jekyll site to GitHub Pages 7 | name: Deploy Jekyll site to Pages 8 | 9 | on: 10 | push: 11 | branches: ["master"] 12 | 13 | # Allows you to run this workflow manually from the Actions tab 14 | workflow_dispatch: 15 | 16 | # Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages 17 | permissions: 18 | contents: read 19 | pages: write 20 | id-token: write 21 | 22 | # Allow one concurrent deployment 23 | concurrency: 24 | group: "pages" 25 | cancel-in-progress: true 26 | 27 | jobs: 28 | # Build job 29 | build: 30 | runs-on: ubuntu-latest 31 | steps: 32 | - name: Checkout 33 | uses: actions/checkout@v4 34 | - name: Setup Ruby 35 | uses: ruby/setup-ruby@v1 36 | with: 37 | # ruby-version: "3.3" # Not needed with a .ruby-version file 38 | bundler-cache: true # runs 'bundle install' and caches installed gems automatically 39 | cache-version: 0 # Increment this number if you need to re-download cached gems 40 | - name: Setup Pages 41 | id: pages 42 | uses: actions/configure-pages@v5 43 | with: 44 | enablement: true 45 | - name: Build with Jekyll 46 | # Outputs to the './_site' directory by default 47 | run: bundle exec jekyll build --baseurl "${{ steps.pages.outputs.base_path }}" 48 | env: 49 | JEKYLL_ENV: production 50 | - name: Upload artifact 51 | # Automatically uploads an artifact from the './_site' directory by default 52 | uses: actions/upload-pages-artifact@v3 53 | 54 | # Deployment job 55 | deploy: 56 | environment: 57 | name: github-pages 58 | url: ${{ steps.deployment.outputs.page_url }} 59 | runs-on: ubuntu-latest 60 | needs: build 61 | steps: 62 | - name: Deploy to GitHub Pages 63 | id: deployment 64 | uses: actions/deploy-pages@v4 65 | -------------------------------------------------------------------------------- /sections/account/hourly_rates.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: default 3 | title: Hourly Rates 4 | parent: Account 5 | grand_parent: Entities 6 | --- 7 | 8 | # Hourly Rates 9 | 10 | German: "Stundensätze" 11 | 12 | - TOC 13 | {:toc} 14 | 15 | ## GET /account/hourly_rates 16 | 17 | Retrieve hourly rates: 18 | 19 | ```bash 20 | curl -X GET \ 21 | 'https://{domain}.mocoapp.com/api/v1/account/hourly_rates' \ 22 | -H 'Authorization: Token token=YOUR_API_KEY' 23 | ``` 24 | 25 | The following parameters can be supplied: 26 | 27 | - **company_id** – 123456 (if overwritten: customer hourly rates, if not: global hourly rates) 28 | - **include_archived_users** – true (also show deactivated users, default is false) 29 | 30 | returns: 31 | 32 | ```json 33 | { 34 | "defaults_rates": [ 35 | { "currency": "CHF", "hourly_rate": 160.0 }, 36 | { "currency": "EUR", "hourly_rate": 150.0 }, 37 | { "currency": "USD", "hourly_rate": 160.0 } 38 | ], 39 | "tasks": [ 40 | { 41 | "id": 5004, 42 | "name": "Grafik", 43 | "rates": [ 44 | { "currency": "CHF", "hourly_rate": 160.0 }, 45 | { "currency": "EUR", "hourly_rate": 150.0 }, 46 | { "currency": "USD", "hourly_rate": 160.0 } 47 | ] 48 | }, 49 | { 50 | "id": 5005, 51 | "name": "Entwicklung", 52 | "rates": [ 53 | { "currency": "CHF", "hourly_rate": 160.0 }, 54 | { "currency": "EUR", "hourly_rate": 150.0 }, 55 | { "currency": "USD", "hourly_rate": 160.0 } 56 | ] 57 | }, 58 | { 59 | "id": 5006, 60 | "name": "Projektleitung", 61 | "rates": [ 62 | { "currency": "CHF", "hourly_rate": 170.0 }, 63 | { "currency": "EUR", "hourly_rate": 160.0 }, 64 | { "currency": "USD", "hourly_rate": 170.0 } 65 | ] 66 | } 67 | ], 68 | "users": [ 69 | { 70 | "id": 933589840, 71 | "full_name": "Max Muster", 72 | "rates": [ 73 | { "currency": "CHF", "hourly_rate": 160.0 }, 74 | { "currency": "EUR", "hourly_rate": 150.0 }, 75 | { "currency": "USD", "hourly_rate": 160.0 } 76 | ] 77 | }, 78 | { 79 | "id": 933589844, 80 | "full_name": "Peter Müller", 81 | "rates": [ 82 | { "currency": "CHF", "hourly_rate": 180.0 }, 83 | { "currency": "EUR", "hourly_rate": 170.0 }, 84 | { "currency": "USD", "hourly_rate": 180.0 } 85 | ] 86 | } 87 | ] 88 | } 89 | ``` 90 | -------------------------------------------------------------------------------- /sections/invoice_bookkeeping_exports.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: default 3 | parent: Invoices 4 | grand_parent: Entities 5 | --- 6 | 7 | # Invoice Bookkeeping Exports 8 | 9 | German: "Rechnungen / Buchhaltungsexporte" 10 | 11 | - TOC 12 | {:toc} 13 | 14 | ## Attributes 15 | 16 | ```json 17 | { 18 | "id": 1101, 19 | "from": "2015-01-01", 20 | "to": "2015-12-31", 21 | "invoice_ids": [ 22 | 2197, 23 | 2189, 24 | 9771, 25 | 2206, 26 | 8841, 27 | 4292, 28 | 2204, 29 | 2195, 30 | 9014, 31 | 6123, 32 | 2205, 33 | 8839, 34 | 2203, 35 | 8837, 36 | 14447, 37 | 2190, 38 | 12641, 39 | 6421, 40 | 8836, 41 | 2192, 42 | 2194, 43 | 8838, 44 | 6124, 45 | 2198, 46 | 2193, 47 | 2202, 48 | 2199, 49 | 2207, 50 | 4337, 51 | 14325, 52 | 8840, 53 | 2191, 54 | 2196, 55 | 2200, 56 | 6122, 57 | 2201 58 | ], 59 | "comment": "2015", 60 | "user": { 61 | "id": 933589840, 62 | "firstname": "Tobias", 63 | "lastname": "Miesel" 64 | }, 65 | "status": "manual", 66 | "created_at": "2021-03-23T05:38:53Z", 67 | "updated_at": "2021-03-23T05:38:53Z" 68 | } 69 | ``` 70 | 71 | ## GET /invoices/bookkeeping_exports 72 | 73 | Retrieve all invoice bookkeeping exports: 74 | 75 | ```bash 76 | curl -X GET \ 77 | 'https://{domain}.mocoapp.com/api/v1/invoices/bookkeeping_exports' \ 78 | -H 'Authorization: Token token=YOUR_API_KEY' 79 | ``` 80 | 81 | ## GET /invoices/bookkeeping_exports/{id} 82 | 83 | Retrieve a single invoice bookkeeping export: 84 | 85 | ```bash 86 | curl -X GET \ 87 | 'https://{domain}.mocoapp.com/api/v1/invoices/bookkeeping_exports/{id}' \ 88 | -H 'Authorization: Token token=YOUR_API_KEY' 89 | ``` 90 | 91 | ## POST /invoices/bookkeeping_exports 92 | 93 | Create an invoice bookkeeping export: 94 | 95 | ```bash 96 | curl -X POST \ 97 | 'https://{domain}.mocoapp.com/api/v1/invoices/bookkeeping_exports' \ 98 | -H 'Authorization: Token token=YOUR_API_KEY' \ 99 | -H 'Content-Type: application/json' \ 100 | -d '{ 101 | "invoice_ids": [123, 234, 345], 102 | }' 103 | ``` 104 | 105 | Mandatory fields are marked with a star (\*): 106 | 107 | - **invoice_ids\*** – [123, 234, 345] 108 | - **trigger_submission** – true/false (e.g. submit also to DATEV; default is true) 109 | - **comment** – "some additional info..." 110 | -------------------------------------------------------------------------------- /sections/deal_categories.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: default 3 | parent: Deals / Leads 4 | grand_parent: Entities 5 | --- 6 | 7 | # Deal Categories 8 | 9 | German: "Akquise-Stufen" 10 | 11 | - TOC 12 | {:toc} 13 | 14 | ## Attributes 15 | 16 | The deal category representation is: 17 | 18 | ```json 19 | { 20 | "id": 123, 21 | "name": "Contact", 22 | "probability": 1, 23 | "created_at": "2018-10-17T09:33:46Z", 24 | "updated_at": "2018-10-17T09:33:46Z" 25 | } 26 | ``` 27 | 28 | ## GET /deal_categories 29 | 30 | Retrieve all categories: 31 | 32 | ```bash 33 | curl -X GET \ 34 | 'https://{domain}.mocoapp.com/api/v1/deal_categories' \ 35 | -H 'Authorization: Token token=YOUR_API_KEY' 36 | ``` 37 | 38 | This returns an array with complete category information (see attributes). 39 | 40 | Additionally, the following parameters can be supplied: 41 | 42 | - [Global filters apply](../entities#global-filters) 43 | 44 | ## GET /deal_categories/{id} 45 | 46 | Retrieve a single category: 47 | 48 | ```bash 49 | curl -X GET \ 50 | 'https://{domain}.mocoapp.com/api/v1/deal_categories/{id}' \ 51 | -H 'Authorization: Token token=YOUR_API_KEY' 52 | ``` 53 | 54 | The response is a single category representation. 55 | 56 | ## POST /deal_categories 57 | 58 | Create a category: 59 | 60 | ```bash 61 | curl -X POST \ 62 | 'https://{domain}.mocoapp.com/api/v1/deal_categories' \ 63 | -H 'Authorization: Token token=YOUR_API_KEY' \ 64 | -H 'Content-Type: application/json' \ 65 | -d '{ 66 | "name": "New Category", 67 | "probability": 15, 68 | }' 69 | ``` 70 | 71 | Mandatory fields are marked with a star (\*): 72 | 73 | - **name\*** – "New Category" 74 | - **probability\*** – 15 75 | 76 | ## PUT /deal_categories/{id} 77 | 78 | Update a category: 79 | 80 | ```bash 81 | curl -X PUT \ 82 | 'https://{domain}.mocoapp.com/api/v1/deal_categories/{id}' \ 83 | -H 'Authorization: Token token=YOUR_API_KEY' \ 84 | -H 'Content-Type: application/json' \ 85 | -d '{ 86 | "name": "New Name" 87 | }' 88 | ``` 89 | 90 | Fields are analogous to the POST request. 91 | 92 | ## DELETE /deal_categories/{id} 93 | 94 | Delete a category. 95 | 96 | ```bash 97 | curl -X DELETE \ 98 | 'https://{domain}.mocoapp.com/api/v1/deal_categories/{id}' \ 99 | -H 'Authorization: Token token=YOUR_API_KEY' 100 | ``` 101 | 102 | Response code is _no-content_ on success. 103 | If the category is in use then the delete fails and response code is _forbidden_. 104 | -------------------------------------------------------------------------------- /sections/purchase_bookkeeping_exports.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: default 3 | parent: Purchases 4 | grand_parent: Entities 5 | --- 6 | 7 | # Purchase Bookkeeping Exports 8 | 9 | German: "Ausgaben / Buchhaltungsexporte" 10 | 11 | - TOC 12 | {:toc} 13 | 14 | ## Attributes 15 | 16 | ```json 17 | { 18 | "id": 1101, 19 | "from": "2015-01-01", 20 | "to": "2015-12-31", 21 | "purchase_ids": [ 22 | 2197, 23 | 2189, 24 | 9771, 25 | 2206, 26 | 8841, 27 | 4292, 28 | 2204, 29 | 2195, 30 | 9014, 31 | 6123, 32 | 2205, 33 | 8839, 34 | 2203, 35 | 8837, 36 | 14447, 37 | 2190, 38 | 12641, 39 | 6421, 40 | 8836, 41 | 2192, 42 | 2194, 43 | 8838, 44 | 6124, 45 | 2198, 46 | 2193, 47 | 2202, 48 | 2199, 49 | 2207, 50 | 4337, 51 | 14325, 52 | 8840, 53 | 2191, 54 | 2196, 55 | 2200, 56 | 6122, 57 | 2201 58 | ], 59 | "comment": "2015", 60 | "user": { 61 | "id": 933589840, 62 | "firstname": "Tobias", 63 | "lastname": "Miesel" 64 | }, 65 | "status": "pending", 66 | "created_at": "2021-03-23T05:38:53Z", 67 | "updated_at": "2021-03-23T05:38:53Z" 68 | } 69 | ``` 70 | 71 | ## GET /purchases/bookkeeping_exports 72 | 73 | Retrieve all purchase bookkeeping exports: 74 | 75 | ```bash 76 | curl -X GET \ 77 | 'https://{domain}.mocoapp.com/api/v1/purchases/bookkeeping_exports' \ 78 | -H 'Authorization: Token token=YOUR_API_KEY' 79 | ``` 80 | 81 | ## GET /purchases/bookkeeping_exports/{id} 82 | 83 | Retrieve a single purchase bookkeeping export: 84 | 85 | ```bash 86 | curl -X GET \ 87 | 'https://{domain}.mocoapp.com/api/v1/purchases/bookkeeping_exports/{id}' \ 88 | -H 'Authorization: Token token=YOUR_API_KEY' 89 | ``` 90 | 91 | ## POST /purchases/bookkeeping_exports 92 | 93 | Create an purchase bookkeeping export: 94 | 95 | ```bash 96 | curl -X POST \ 97 | 'https://{domain}.mocoapp.com/api/v1/purchases/bookkeeping_exports' \ 98 | -H 'Authorization: Token token=YOUR_API_KEY' \ 99 | -H 'Content-Type: application/json' \ 100 | -d '{ 101 | "purchase_ids": [123, 234, 345], 102 | }' 103 | ``` 104 | 105 | Mandatory fields are marked with a star (\*): 106 | 107 | - **purchase_ids\*** – [123, 234, 345] 108 | - **trigger_submission** – true/false (e.g. submit also to DATEV; default is true) 109 | - **archive_after_export** – true/false (if purchases should be archived; default is false) 110 | - **comment** – "some additional info..." 111 | -------------------------------------------------------------------------------- /sections/tags/tags.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: default 3 | title: Tags (Labels) 4 | parent: Entities 5 | has_children: true 6 | --- 7 | 8 | # Tags 9 | 10 | - TOC 11 | {:toc} 12 | 13 | ## Attributes 14 | 15 | ```json 16 | { 17 | "id": 12345678, 18 | "name": "Important", 19 | "color": "#FF0000", 20 | "context": "Project", 21 | "created_at": "2018-10-17T09:33:46Z", 22 | "updated_at": "2018-10-17T09:33:46Z" 23 | } 24 | ``` 25 | 26 | ## GET /tags 27 | 28 | Retrieve the list of tags: 29 | 30 | ```bash 31 | curl -X GET \ 32 | 'https://{domain}.mocoapp.com/api/v1/tags' 33 | ``` 34 | 35 | This returns an array of all tags. 36 | 37 | The following parameters can be supplied: 38 | 39 | - [Global filters apply](../entities#global-filters) 40 | - **context** – one of Company, Contact, Project, Deal, Purchase, Invoice, Offer or User 41 | 42 | ## GET /tags/{id} 43 | 44 | Retrieve a single tag: 45 | 46 | ```bash 47 | curl -X GET \ 48 | 'https://{domain}.mocoapp.com/api/v1/tags/{id}' \ 49 | -H 'Authorization: Token token=YOUR_API_KEY' 50 | ``` 51 | 52 | ## POST /tags 53 | 54 | Create a tag: 55 | 56 | ```bash 57 | curl -X POST \ 58 | 'https://{domain}.mocoapp.com/api/v1/tags' \ 59 | -H 'Authorization: Token token=YOUR_API_KEY' \ 60 | -H 'Content-Type: application/json' \ 61 | -d '{ 62 | "name": "ONHOLD", 63 | "color: "#FFFF00", 64 | "context": "Project" 65 | }' 66 | ``` 67 | 68 | This creates a yellow tag "ONHOLD" for the projects area. 69 | 70 | Mandatory fields are marked with a star (\*): 71 | 72 | - **name\*** – "ONHOLD" 73 | - **context\*** – one of Company, Contact, Project, Deal, Purchase, Invoice, Offer or User 74 | - **color** – must be in hex format `#ABC123`; default is grey 75 | 76 | ## PUT /tags/{id} 77 | 78 | Change a tag: 79 | 80 | ```bash 81 | curl -X PUT \ 82 | 'https://{domain}.mocoapp.com/api/v1/tags/{id}' \ 83 | -H 'Authorization: Token token=YOUR_API_KEY' \ 84 | -H 'Content-Type: application/json' \ 85 | -d '{ 86 | "color": "#FF0000" 87 | }' 88 | ``` 89 | 90 | Only `name` and `color` can be changed (not the context or area in MOCO). 91 | 92 | ## DELETE /tags/{id} 93 | 94 | Selectively remove the tags associated to the entity: 95 | 96 | ```bash 97 | curl -X DELETE \ 98 | 'https://{domain}.mocoapp.com/api/v1/tags/{id}' \ 99 | -H 'Authorization: Token token=YOUR_API_KEY' 100 | ``` 101 | 102 | {: .note } 103 | Pass `merge_tag_id` if you want to replace all tagged entities with another tag. Useful to consolidate many tags into one. 104 | -------------------------------------------------------------------------------- /sections/vat_codes.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: default 3 | parent: Entities 4 | --- 5 | 6 | # VAT Codes 7 | 8 | German: "Steuerschlüssel" 9 | 10 | - TOC 11 | {:toc} 12 | 13 | ## Attributes 14 | 15 | ### VatCode Sale 16 | 17 | ```json 18 | { 19 | "id": 186, 20 | "tax": 7.7, 21 | "reverse_charge": false, 22 | "intra_eu": false, 23 | "active": true, 24 | "print_gross_total": true, 25 | "notice_tax_exemption": "", 26 | "notice_tax_exemption_alt": "", 27 | "code": "9", 28 | "credit_account: "4000" 29 | } 30 | ``` 31 | 32 | ### VatCode Purchase 33 | 34 | ```json 35 | { 36 | "id": 186, 37 | "tax": 7.7, 38 | "reverse_charge": false, 39 | "intra_eu": false, 40 | "active": true, 41 | "code": "9" 42 | } 43 | ``` 44 | 45 | ## GET /vat_code_sales 46 | 47 | Retrieve the list of sale vat codes: 48 | 49 | ```bash 50 | curl -X GET \ 51 | 'https://{domain}.mocoapp.com/api/v1/vat_code_sales' \ 52 | -H 'Authorization: Token token=YOUR_API_KEY' 53 | ``` 54 | 55 | This returns an array with sale vat codes (see Attributes). 56 | 57 | The following parameters can be supplied to filter sale vat codes: 58 | 59 | - [Global filters apply](../entities#global-filters) 60 | - **reverse_charge** – true/false (Umkehr Steuerschuldnerschaft) 61 | - **intra_eu** – true/false (Innergemeinschaftliche Leistung) 62 | - **active** – true/false 63 | 64 | ## GET /vat_code_purchases 65 | 66 | Retrieve the list of purchase vat codes: 67 | 68 | ```bash 69 | curl -X GET \ 70 | 'https://{domain}.mocoapp.com/api/v1/vat_code_purchases' \ 71 | -H 'Authorization: Token token=YOUR_API_KEY' 72 | ``` 73 | 74 | This returns an array with purchase vat codes (see Attributes). 75 | 76 | The following parameters can be supplied to filter purchase vat codes: 77 | 78 | - **ids** – e.g. `123,456` (IDS, comma-separated) 79 | - **reverse_charge** – true/false (Umkehr Steuerschuldnerschaft) 80 | - **intra_eu** – true/false (Innergemeinschaftliche Leistung) 81 | - **active** – true/false 82 | 83 | ## GET /vat_code_sales/{id} 84 | 85 | Retrieve a single sale vat code: 86 | 87 | ```bash 88 | curl -X GET \ 89 | 'https://{domain}.mocoapp.com/api/v1/vat_code_sales/123' \ 90 | -H 'Authorization: Token token=YOUR_API_KEY' 91 | ``` 92 | 93 | Retrieve a single sale vat code. 94 | 95 | ## GET /vat_code_purchases/{id} 96 | 97 | Retrieve a single purchase vat code: 98 | 99 | ```bash 100 | curl -X GET \ 101 | 'https://{domain}.mocoapp.com/api/v1/vat_code_purchases/123' \ 102 | -H 'Authorization: Token token=YOUR_API_KEY' 103 | ``` 104 | 105 | Retrieve a single purchase vat code. 106 | -------------------------------------------------------------------------------- /sections/units.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: default 3 | parent: Entities 4 | --- 5 | 6 | # Units / Teams 7 | 8 | German: "Teams" 9 | 10 | - TOC 11 | {:toc} 12 | 13 | ## Attributes 14 | 15 | The representation contains among the standard fields also: 16 | 17 | - users (staff assigned to this team) 18 | 19 | ```json 20 | { 21 | "id": 909147861, 22 | "name": "C Office", 23 | "users": [ 24 | { 25 | "id": 933590158, 26 | "firstname": "Tobias", 27 | "lastname": "Miesel", 28 | "email": "tobias@domain.com" 29 | }, 30 | { 31 | "id": 933589599, 32 | "firstname": "Sabine", 33 | "lastname": "Schäuble", 34 | "email": "sabine@domain.com" 35 | } 36 | ], 37 | "created_at": "2018-10-17T09:33:46Z", 38 | "updated_at": "2018-10-17T09:33:46Z" 39 | } 40 | ``` 41 | 42 | ## GET /units 43 | 44 | Retrieve all teams: 45 | 46 | ```bash 47 | curl -X GET \ 48 | 'https://{domain}.mocoapp.com/api/v1/units' \ 49 | -H 'Authorization: Token token=YOUR_API_KEY' 50 | ``` 51 | 52 | This returns an array with complete team information (see Attributes). 53 | 54 | Additionally, the following parameters can be supplied: 55 | 56 | - [Global filters apply](../entities#global-filters) 57 | 58 | ## GET /units/{id} 59 | 60 | Retrieve a single team: 61 | 62 | ```bash 63 | curl -X GET \ 64 | 'https://{domain}.mocoapp.com/api/v1/units/{id}' \ 65 | -H 'Authorization: Token token=YOUR_API_KEY' 66 | ``` 67 | 68 | ## POST /units 69 | 70 | Create a unit: 71 | 72 | ```bash 73 | curl -X POST \ 74 | 'https://{domain}.mocoapp.com/api/v1/units' \ 75 | -H 'Authorization: Token token=YOUR_API_KEY' \ 76 | -H 'Content-Type: application/json' \ 77 | -d '{ 78 | "name": "A great new team" 79 | }' 80 | ``` 81 | 82 | {: .note } 83 | Assigning a user is possible by [updating it](users.md#put-usersid) with the `unit_id` attribute. 84 | 85 | ## PUT /units/{id} 86 | 87 | Update a unit: 88 | 89 | ```bash 90 | curl -X PUT \ 91 | 'https://{domain}.mocoapp.com/api/v1/units/{id}' \ 92 | -H 'Authorization: Token token=YOUR_API_KEY' \ 93 | -H 'Content-Type: application/json' \ 94 | -d '{ 95 | "name": "A new name" 96 | }' 97 | ``` 98 | 99 | Fields are analogous to the POST request. 100 | 101 | ## DELETE /users/{id} 102 | 103 | {: .note } 104 | Deleting a unit is only possible if no users are assigned to it. Move existing users to a different unit by [updating them](users.md#put-usersid) with the `unit_id` attribute. 105 | 106 | ```bash 107 | curl -X DELETE \ 108 | 'https://{domain}.mocoapp.com/api/v1/units/{id}' \ 109 | -H 'Authorization: Token token=YOUR_API_KEY' 110 | ``` -------------------------------------------------------------------------------- /sections/project_contracts.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: default 3 | parent: Projects 4 | grand_parent: Entities 5 | --- 6 | 7 | # Project Contracts 8 | 9 | German: "Projekte / Personal" 10 | 11 | - TOC 12 | {:toc} 13 | 14 | ## Attributes 15 | 16 | Assigning staff to a project is defined in Moco as a "contract". 17 | 18 | ```json 19 | { 20 | "id": 760253573, 21 | "user_id": 938487474, 22 | "firstname": "Nicola", 23 | "lastname": "Piccinini", 24 | "billable": true, 25 | "active": true, 26 | "budget": 9900, 27 | "hourly_rate": 110, 28 | "created_at": "2018-10-17T09:33:46Z", 29 | "updated_at": "2018-10-17T09:33:46Z" 30 | } 31 | ``` 32 | 33 | ## GET /projects/{id}/contracts 34 | 35 | Retrieve all staff assignments for a project: 36 | 37 | ```bash 38 | curl -X GET \ 39 | 'https://{domain}.mocoapp.com/api/v1/projects/{id}/contracts' \ 40 | -H 'Authorization: Token token=YOUR_API_KEY' 41 | ``` 42 | 43 | This returns an array of all **active people** with assignment information (see Attributes). 44 | 45 | ## GET /projects/{id}/contracts/{id} 46 | 47 | Retrieve a single staff assignment on a project: 48 | 49 | ```bash 50 | curl -X GET \ 51 | 'https://{domain}.mocoapp.com/api/v1/projects/{id}/contracts/{id}' \ 52 | -H 'Authorization: Token token=YOUR_API_KEY' 53 | ``` 54 | 55 | ## POST /projects/{id}/contracts 56 | 57 | Assign a person to a project: 58 | 59 | ```bash 60 | curl -X POST \ 61 | 'https://{domain}.mocoapp.com/api/v1/projects/{id}/contracts' \ 62 | -H 'Authorization: Token token=YOUR_API_KEY' \ 63 | -H 'Content-Type: application/json' \ 64 | -d '{ 65 | "user_id": 123456, 66 | "budget": 9900 67 | }' 68 | ``` 69 | 70 | Mandatory fields are marked with a star (\*): 71 | 72 | - **user_id\*** – 123456 73 | - **billable** – true/false 74 | - **active** – true/false 75 | - **budget** – 9900 76 | - **hourly_rate** – 120 77 | 78 | ## PUT /projects/{id}/contracts/{id} 79 | 80 | Update a staff assignment to a project: 81 | 82 | ```bash 83 | curl -X PUT \ 84 | 'https://{domain}.mocoapp.com/api/v1/projects/{id}/contracts/{id}' \ 85 | -H 'Authorization: Token token=YOUR_API_KEY' \ 86 | -H 'Content-Type: application/json' \ 87 | -d '{ 88 | "budget": 8800 89 | }' 90 | ``` 91 | 92 | Fields are analogous to the POST request (except `user_id`). 93 | 94 | ## DELETE /projects/{id}/contracts/{id} 95 | 96 | {: .note } 97 | Deleting a staff assignment on a project is only possible as long as no hours are tracked from this person. 98 | 99 | ```bash 100 | curl -X DELETE \ 101 | 'https://{domain}.mocoapp.com/api/v1/projects/{id}/contracts/{id}' \ 102 | -H 'Authorization: Token token=YOUR_API_KEY' 103 | ``` 104 | -------------------------------------------------------------------------------- /sections/account/task_templates.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: default 3 | title: Task Templates 4 | parent: Account 5 | grand_parent: Entities 6 | --- 7 | 8 | # Task Templates 9 | 10 | German: "Standardleistungen" 11 | 12 | - TOC 13 | {:toc} 14 | 15 | ## Attributes 16 | 17 | Item attributes: 18 | 19 | - **name*** 20 | - **description** 21 | - **revenue_category** 22 | - **billable** true / false 23 | - **project_default** true / false - adding to new projects by default 24 | - **index** e.g. 10 - used for ordering 25 | 26 | ```json 27 | { 28 | "id": 1, 29 | "name": "Service A", 30 | "description": "A description", 31 | "revenue_category": { 32 | "id": 4567, 33 | "name": "Revenue category name", 34 | "revenue_account": 1000, 35 | "cost_category": 99 36 | }, 37 | "billable": true, 38 | "project_default": true, 39 | "index": 10, 40 | "created_at": "2025-07-17T18:14:31Z", 41 | "updated_at": "2022-08-18T08:17:55Z" 42 | } 43 | ``` 44 | 45 | ## GET /account/task_templates 46 | 47 | Retrieve task templates: 48 | 49 | ```bash 50 | curl -X GET \ 51 | 'https://{domain}.mocoapp.com/api/v1/account/task_templates' \ 52 | -H 'Authorization: Token token=YOUR_API_KEY' 53 | ``` 54 | 55 | returns an array of task templates. 56 | 57 | The following parameters can be supplied: 58 | 59 | - [Global filters apply](../../entities#global-filters) 60 | 61 | ## GET /account/task_templates/{id} 62 | 63 | Retrieve an task template: 64 | 65 | ```bash 66 | curl -X GET \ 67 | 'https://{domain}.mocoapp.com/api/v1/account/task_templates/{id}' \ 68 | -H 'Authorization: Token token=YOUR_API_KEY' 69 | ``` 70 | 71 | returns a single task template. 72 | 73 | ## POST /account/task_templates 74 | 75 | Create an task template: 76 | 77 | ```bash 78 | curl -X POST \ 79 | 'https://{domain}.mocoapp.com/api/v1/account/task_templates' \ 80 | -H 'Authorization: Token token=YOUR_API_KEY' 81 | -H 'Content-Type: application/json' \ 82 | -d '{ 83 | "name": "Web Development", 84 | "description": "Building the web application", 85 | "revenue_category_id": 4567, 86 | "billable": true, 87 | "project_default": true 88 | }' 89 | ``` 90 | 91 | Mandatory fields are: name. 92 | 93 | ## PUT /account/task_templates/{id} 94 | 95 | Update an task template: 96 | 97 | ```bash 98 | curl -X PUT \ 99 | 'https://{domain}.mocoapp.com/api/v1/account/task_templates/{id}' \ 100 | -H 'Authorization: Token token=YOUR_API_KEY' 101 | -H 'Content-Type: application/json' \ 102 | -d '{ 103 | "title": "Development" 104 | }' 105 | ``` 106 | 107 | ## DELETE /account/task_templates/{id} 108 | 109 | Delete an task template: 110 | 111 | ```bash 112 | curl -X DELETE \ 113 | 'https://{domain}.mocoapp.com/api/v1/account/task_templates/{id}' \ 114 | -H 'Authorization: Token token=YOUR_API_KEY' 115 | ``` 116 | -------------------------------------------------------------------------------- /sections/tags/taggings.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: default 3 | title: Taggings 4 | parent: Tags (Labels) 5 | grand_parent: Entities 6 | --- 7 | 8 | # Taggings (tag associations) 9 | 10 | - TOC 11 | {:toc} 12 | 13 | The API provides a single endpoint to manage the tag associations to different type of entities: 14 | 15 | ``` 16 | /api/v1/taggings/{entity}/{entity_id} 17 | ``` 18 | 19 | The parameter `{entity}` must be one of the following: 20 | Company, Contact, Project, Deal, Purchase, Invoice, Offer, User 21 | 22 | ## GET /taggings 23 | 24 | Retrieve the list of tags associated with the entity: 25 | 26 | ```bash 27 | curl -X GET \ 28 | 'https://{domain}.mocoapp.com/api/v1/taggings/Project/357' 29 | ``` 30 | 31 | Returns an array with tag names: 32 | 33 | ``` 34 | ["cool", "on hold"] 35 | ``` 36 | 37 | ## PATCH /taggings 38 | 39 | Add tags to the entity: 40 | 41 | ```bash 42 | curl -X PATCH \ 43 | 'https://{domain}.mocoapp.com/api/v1/taggings/Project/357' \ 44 | -H 'Authorization: Token token=YOUR_API_KEY' \ 45 | -H 'Content-Type: application/json' \ 46 | -d '{ 47 | "tags": ["cool", "on hold"] 48 | }' 49 | ``` 50 | 51 | This adds the tags "cool" and "on hold" to the project with ID 357 and returns the list of all the tags associated 52 | to the project. Existing tags are preserved, so if the project had the tag "climate", in the end it will have 3 tags: 53 | "climate", "cool" and "on hold". 54 | If a tag is already assigned to the entity, then it's silently ignored. 55 | If a tag doesn't exist, then it's created automatically. 56 | 57 | ## PUT /taggings 58 | 59 | Replace the tags associated to the entity: 60 | 61 | ```bash 62 | curl -X PUT \ 63 | 'https://{domain}.mocoapp.com/api/v1/taggings/Project/357' \ 64 | -H 'Authorization: Token token=YOUR_API_KEY' \ 65 | -H 'Content-Type: application/json' \ 66 | -d '{ 67 | "tags": ["cool", "on hold"] 68 | }' 69 | ``` 70 | 71 | Similar to the previous operation but in this case existing tags are removed if not included in the set of the assigned tags. 72 | So, if the project had the tag "climate", it ends up having only 2 tags: 73 | "cool" and "on hold". 74 | Also in this case, if a tag is already assigned to the entity, then it's silently ignored and if a tag doesn't exist, 75 | then it's created automatically. 76 | 77 | This operation can be used to clean out the tags of an entity just passing an empty array as `tags`. 78 | 79 | ## DELETE /taggings 80 | 81 | Selectively remove the tags associated to the entity: 82 | 83 | ```bash 84 | curl -X DELETE \ 85 | 'https://{domain}.mocoapp.com/api/v1/taggings/Project/357' \ 86 | -H 'Authorization: Token token=YOUR_API_KEY' \ 87 | -H 'Content-Type: application/json' \ 88 | -d '{ 89 | "tags": ["cool"] 90 | }' 91 | ``` 92 | 93 | Other tags are preserved, so if the project had "cool" and "on hold", it ends up having just "on hold". If any mentioned tag 94 | is not associated to the entity, it's silently ignored. 95 | -------------------------------------------------------------------------------- /sections/account/expense_templates.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: default 3 | title: Expense Templates 4 | parent: Account 5 | grand_parent: Entities 6 | --- 7 | 8 | # Expense Templates 9 | 10 | German: "Zusatzleistungs-Katalog" 11 | 12 | - TOC 13 | {:toc} 14 | 15 | ## Attributes 16 | 17 | Item attributes: 18 | 19 | - **title** 20 | - **description** 21 | - **unit** e.g. "hours", "pieces", "month" 22 | - **unit_price** price for a single unit 23 | - **unit_cost** internal cost for 1 unit 24 | - **currency** 25 | 26 | ```json 27 | { 28 | "id": 1, 29 | "title": "Hosting L", 30 | "description": "The large hosting package", 31 | "unit": "month", 32 | "unit_price": "50.0", 33 | "unit_cost": "40.0", 34 | "currency": "EUR", 35 | "revenue_category": { 36 | "id": 124, 37 | "name": "Hosting", 38 | "revenue_account": 30056, 39 | "cost_category": "HO1" 40 | }, 41 | "created_at": "2022-09-17T18:14:31Z", 42 | "updated_at": "2022-06-24T08:17:55Z" 43 | } 44 | ``` 45 | 46 | ## GET /account/expense_templates 47 | 48 | Retrieve expense templates: 49 | 50 | ```bash 51 | curl -X GET \ 52 | 'https://{domain}.mocoapp.com/api/v1/account/expense_templates' \ 53 | -H 'Authorization: Token token=YOUR_API_KEY' 54 | ``` 55 | 56 | returns an array of expense templates. 57 | 58 | The following parameters can be supplied: 59 | 60 | - [Global filters apply](../../entities#global-filters) 61 | 62 | ## GET /account/expense_templates/{id} 63 | 64 | Retrieve an expense template: 65 | 66 | ```bash 67 | curl -X GET \ 68 | 'https://{domain}.mocoapp.com/api/v1/account/expense_templates/{id}' \ 69 | -H 'Authorization: Token token=YOUR_API_KEY' 70 | ``` 71 | 72 | returns a single expense template. 73 | 74 | ## POST /account/expense_templates 75 | 76 | Create an expense template: 77 | 78 | ```bash 79 | curl -X POST \ 80 | 'https://{domain}.mocoapp.com/api/v1/account/expense_templates' \ 81 | -H 'Authorization: Token token=YOUR_API_KEY' 82 | -H 'Content-Type: application/json' \ 83 | -d '{ 84 | "title": "Hosting S", 85 | "description": "The small hosting package", 86 | "unit": "month", 87 | "unit_price": "20.0", 88 | "unit_cost": "15.0", 89 | "currency": "EUR" 90 | }' 91 | ``` 92 | 93 | ## PUT /account/expense_templates/{id} 94 | 95 | Update an expense template: 96 | 97 | ```bash 98 | curl -X PUT \ 99 | 'https://{domain}.mocoapp.com/api/v1/account/expense_templates/{id}' \ 100 | -H 'Authorization: Token token=YOUR_API_KEY' 101 | -H 'Content-Type: application/json' \ 102 | -d '{ 103 | "title": "Hosting Small" 104 | }' 105 | ``` 106 | 107 | ## DELETE /account/expense_templates/{id} 108 | 109 | Delete an expense template: 110 | 111 | ```bash 112 | curl -X DELETE \ 113 | 'https://{domain}.mocoapp.com/api/v1/account/expense_templates/{id}' \ 114 | -H 'Authorization: Token token=YOUR_API_KEY' 115 | ``` 116 | -------------------------------------------------------------------------------- /sections/holidays.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: default 3 | parent: Users 4 | grand_parent: Entities 5 | --- 6 | 7 | # User Holidays 8 | 9 | German: "Urlaubsanspruch" 10 | 11 | - TOC 12 | {:toc} 13 | 14 | ## Attributes 15 | 16 | Holidays contain among the standard fields also: 17 | 18 | - User (creator) 19 | 20 | ```json 21 | { 22 | "id": 12345, 23 | "year": 2019, 24 | "title": "Urlaubsanspruch 80%", 25 | "days": 20, 26 | "hours": 160, 27 | "user": { 28 | "id": 933590696, 29 | "firstname": "John", 30 | "lastname": "Doe" 31 | }, 32 | "creator": { 33 | "id": 933590697, 34 | "firstname": "Jane", 35 | "lastname": "Doe" 36 | }, 37 | "created_at": "2018-10-17T09:33:46Z", 38 | "updated_at": "2018-10-17T09:33:46Z" 39 | } 40 | ``` 41 | 42 | Holiday credits have to be set in days. Holiday days are also converted to hours using the _daily hours_ value that may 43 | be set for every user in the holiday section in MOCO: 10 days at 5h/day = 50 hours and 10 days at 8h/day = 80 hours. 44 | 45 | ## GET /users/holidays 46 | 47 | Retrieve all holidays: 48 | 49 | ```bash 50 | curl -X GET \ 51 | 'https://{domain}.mocoapp.com/api/v1/users/holidays?year=2018' \ 52 | -H 'Authorization: Token token=YOUR_API_KEY' 53 | ``` 54 | 55 | This returns an array of all holidays. 56 | 57 | The following parameters can be supplied: 58 | 59 | - [Global filters apply](../entities#global-filters) 60 | - **year** – 2018 61 | - **user_id** – 123 62 | 63 | ## GET /users/holidays/{id} 64 | 65 | Retrieve a single holiday: 66 | 67 | ```bash 68 | curl -X GET \ 69 | 'https://{domain}.mocoapp.com/api/v1/users/holidays/{id}' \ 70 | -H 'Authorization: Token token=YOUR_API_KEY' 71 | ``` 72 | 73 | ## POST /users/holidays 74 | 75 | Create a holiday: 76 | 77 | ```bash 78 | curl -X POST \ 79 | 'https://{domain}.mocoapp.com/api/v1/users/holidays' \ 80 | -H 'Authorization: Token token=YOUR_API_KEY' \ 81 | -H 'Content-Type: application/json' \ 82 | -d '{ 83 | "user_id": 933590696, 84 | "year": 2019, 85 | "title": "Urlaubsanspruch 80%", 86 | "days": 20, 87 | }' 88 | ``` 89 | 90 | Mandatory fields are marked with a star (\*): 91 | 92 | - **year\*** – 2019 93 | - **title\*** – "Urlaubsanspruch 80%" 94 | - **days\*** – 20 95 | - **user_id\*** – 933590696 96 | - **creator_id** – 933590000 97 | 98 | ## PUT /users/holidays/{id} 99 | 100 | Update a holiday. 101 | 102 | ```bash 103 | curl -X PUT \ 104 | 'https://{domain}.mocoapp.com/api/v1/users/holidays/{id}' \ 105 | -H 'Authorization: Token token=YOUR_API_KEY' \ 106 | -H 'Content-Type: application/json' \ 107 | -d '{ 108 | "days": 22 109 | }' 110 | ``` 111 | 112 | All fields are analogous to the POST request. 113 | 114 | ## DELETE /users/holidays/{id} 115 | 116 | Delete a holiday. 117 | 118 | ```bash 119 | curl -X DELETE \ 120 | 'https://{domain}.mocoapp.com/api/v1/users/holidays/{id}' \ 121 | -H 'Authorization: Token token=YOUR_API_KEY' 122 | ``` 123 | -------------------------------------------------------------------------------- /sections/work_time_adjustments.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: default 3 | parent: Users 4 | grand_parent: Entities 5 | --- 6 | 7 | # User Work Time Adjustments 8 | 9 | German: "Korrekturen Zeiterfassung" 10 | 11 | - TOC 12 | {:toc} 13 | 14 | ## Attributes 15 | 16 | Work time adjustments contain among the standard fields also: 17 | 18 | - User 19 | - Creator 20 | 21 | ```json 22 | { 23 | "id": 1972, 24 | "date": "2022-01-01", 25 | "description": "Overtime from 2021", 26 | "hours": 172.01, 27 | "creator": { 28 | "id": 933590697, 29 | "firstname": "Jane", 30 | "lastname": "Doe" 31 | }, 32 | "user": { 33 | "id": 933590696, 34 | "firstname": "John", 35 | "lastname": "Doe" 36 | }, 37 | "created_at": "2022-01-02T17:31:00Z", 38 | "updated_at": "2022-01-02T17:31:00Z" 39 | } 40 | ``` 41 | 42 | ## GET /users/work_time_adjustments 43 | 44 | Retrieve all work time adjustments: 45 | 46 | ```bash 47 | curl -X GET \ 48 | 'https://{domain}.mocoapp.com/api/v1/users/work_time_adjustments?from=2018-06-01&to=2018-06-30&user_id=933590696' \ 49 | -H 'Authorization: Token token=YOUR_API_KEY' 50 | ``` 51 | 52 | This returns an array of all work time adjustments. 53 | 54 | The following parameters can be supplied: 55 | 56 | - [Global filters apply](../entities#global-filters) 57 | - **from** – "2022-01-01" 58 | - **to** – "2022-01-31" 59 | - **user_id** – 123 60 | 61 | ## GET /users/work_time_adjustments/{id} 62 | 63 | Retrieve a single work time adjustment: 64 | 65 | ```bash 66 | curl -X GET \ 67 | 'https://{domain}.mocoapp.com/api/v1/users/work_time_adjustments/{id}' \ 68 | -H 'Authorization: Token token=YOUR_API_KEY' 69 | ``` 70 | 71 | ## POST /users/work_time_adjustments 72 | 73 | Create a work time adjustment: 74 | 75 | ```bash 76 | curl -X POST \ 77 | 'https://{domain}.mocoapp.com/api/v1/users/work_time_adjustments' \ 78 | -H 'Authorization: Token token=YOUR_API_KEY' 79 | -H 'Content-Type: application/json' \ 80 | -d '{ 81 | "user_id": 123, 82 | "description": "Overtime 2021", 83 | "date": "2022-01-01", 84 | "hours": 42.0 85 | }' 86 | ``` 87 | 88 | Mandatory fields are marked with a star (\*): 89 | 90 | - **user_id\*** – 123 (user ID) 91 | - **description\*** – a short explanation 92 | - **date\*** - 2022-01-01 93 | - **hours\*** - 42.0 (the amount of hours that should be added or subtracted) 94 | 95 | ## PUT /users/work_time_adjustments/{id} 96 | 97 | Update a work time adjustment: 98 | 99 | ```bash 100 | curl -X PUT \ 101 | 'https://{domain}.mocoapp.com/api/v1/users/work_time_adjustments/{id}' \ 102 | -H 'Authorization: Token token=YOUR_API_KEY' 103 | -H 'Content-Type: application/json' \ 104 | -d '{ 105 | "description": "A new description" 106 | }' 107 | ``` 108 | 109 | ## DELETE /users/work_time_adjustments/{id} 110 | 111 | Delete a work time adjustment: 112 | 113 | ```bash 114 | curl -X DELETE \ 115 | 'https://{domain}.mocoapp.com/api/v1/users/work_time_adjustments/{id}' \ 116 | -H 'Authorization: Token token=YOUR_API_KEY' 117 | ``` -------------------------------------------------------------------------------- /sections/project_tasks.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: default 3 | parent: Projects 4 | grand_parent: Entities 5 | --- 6 | 7 | # Project Tasks 8 | 9 | German: "Projekte / Leistungen" 10 | 11 | - TOC 12 | {:toc} 13 | 14 | ## Attributes 15 | 16 | ```json 17 | { 18 | "id": 760253573, 19 | "name": "Projektleitung", 20 | "billable": true, 21 | "active": true, 22 | "budget": 2900, 23 | "hourly_rate": 120, 24 | "revenue_category": { 25 | "id": 126, 26 | "name": "Projektleitung", 27 | "revenue_account": 30058, 28 | "cost_category": "PM1" 29 | }, 30 | "description": "A task description", 31 | "created_at": "2018-10-17T09:33:46Z", 32 | "updated_at": "2018-10-17T09:33:46Z" 33 | } 34 | ``` 35 | 36 | ## GET /projects/{id}/tasks 37 | 38 | Retrieve all tasks on a project: 39 | 40 | ```bash 41 | curl -X GET \ 42 | 'https://{domain}.mocoapp.com/api/v1/projects/{id}/tasks' \ 43 | -H 'Authorization: Token token=YOUR_API_KEY' 44 | ``` 45 | 46 | This returns an array with complete task information (see Attributes). 47 | 48 | ## GET /projects/{id}/tasks/{id} 49 | 50 | Retrieve a single task on a project: 51 | 52 | ```bash 53 | curl -X GET \ 54 | 'https://{domain}.mocoapp.com/api/v1/projects/{id}/tasks/{id}' \ 55 | -H 'Authorization: Token token=YOUR_API_KEY' 56 | ``` 57 | 58 | ## POST /projects/{id}/tasks 59 | 60 | Create a task on a project: 61 | 62 | ```bash 63 | curl -X POST \ 64 | 'https://{domain}.mocoapp.com/api/v1/projects/{id}/tasks' \ 65 | -H 'Authorization: Token token=YOUR_API_KEY' \ 66 | -H 'Content-Type: application/json' \ 67 | -d '{ 68 | "name": "Design / UX", 69 | "billable": true, 70 | "hourly_rate": 120 71 | }' 72 | ``` 73 | 74 | Mandatory fields are marked with a star (\*): 75 | 76 | - **name\*** – "Design / UX" 77 | - **billable** – true/false 78 | - **active** – true/false 79 | - **budget** – 5000 80 | - **hourly_rate** – 120 81 | - **description** – A description of this task 82 | 83 | ## PUT /projects/{id}/tasks/{id} 84 | 85 | Update a task on a project: 86 | 87 | ```bash 88 | curl -X PUT \ 89 | 'https://{domain}.mocoapp.com/api/v1/projects/{id}/tasks/{id}' \ 90 | -H 'Authorization: Token token=YOUR_API_KEY' \ 91 | -H 'Content-Type: application/json' \ 92 | -d '{ 93 | "budget": 5000, 94 | "hourly_rate": 130 95 | }' 96 | ``` 97 | 98 | Fields are analogous to the POST request. 99 | 100 | ## DELETE /projects/{id}/tasks/{id} 101 | 102 | {: .note } 103 | Deleting a task on a project is only possible as long as no hours were tracked on this task. 104 | 105 | ```bash 106 | curl -X DELETE \ 107 | 'https://{domain}.mocoapp.com/api/v1/projects/{id}/tasks/{id}' \ 108 | -H 'Authorization: Token token=YOUR_API_KEY' 109 | ``` 110 | 111 | ## DELETE /projects/{id}/tasks/destroy_all 112 | 113 | {: .warning } 114 | Not deletable tasks on a project will be skipped. 115 | 116 | ```bash 117 | curl -X DELETE \ 118 | 'https://{domain}.mocoapp.com/api/v1/projects/{id}/tasks/destroy_all' \ 119 | -H 'Authorization: Token token=YOUR_API_KEY' 120 | ``` 121 | -------------------------------------------------------------------------------- /sections/web_hooks.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: default 3 | parent: Entities 4 | --- 5 | 6 | # Web Hooks 7 | 8 | - TOC 9 | {:toc} 10 | 11 | ## Attributes 12 | 13 | ```json 14 | { 15 | "id": 123, 16 | "target": "Activity", 17 | "event": "create", 18 | "hook": "https://example.org/do-stuff", 19 | "disabled": false, 20 | "disabled_at": null, 21 | "created_at": "2018-10-17T09:33:46Z", 22 | "updated_at": "2018-10-17T09:33:46Z" 23 | } 24 | ``` 25 | 26 | ## GET /account/web_hooks 27 | 28 | Retrieve all web hooks: 29 | 30 | ```bash 31 | curl -X GET \ 32 | 'https://{domain}.mocoapp.com/api/v1/account/web_hooks' \ 33 | -H 'Authorization: Token token=YOUR_API_KEY' 34 | ``` 35 | 36 | This returns an array with complete web hooks information (see Attributes). 37 | 38 | The following parameters can be supplied: 39 | 40 | - [Global filters apply](../entities#global-filters) 41 | 42 | ## GET /account/web_hooks/{id} 43 | 44 | Retrieve a single web hook: 45 | 46 | ```bash 47 | curl -X GET \ 48 | 'https://{domain}.mocoapp.com/api/v1/account/web_hook/{id}' \ 49 | -H 'Authorization: Token token=YOUR_API_KEY' 50 | ``` 51 | 52 | This returns a single web hook representation. 53 | 54 | ## POST /account/web_hooks 55 | 56 | Create a new web hook: 57 | 58 | ```bash 59 | curl -X POST \ 60 | 'https://{domain}.mocoapp.com/api/v1/account/web_hooks' \ 61 | -H 'Authorization: Token token=YOUR_API_KEY' \ 62 | -H 'Content-Type: application/json' \ 63 | -d '{ 64 | "target": "Activity", 65 | "event": "create", 66 | "hook": "https://example.org/do-stuff" 67 | }' 68 | ``` 69 | 70 | Mandatory fields are marked with a star (\*): 71 | 72 | - **target\*** – "Activity" (Activity/Company/Contact/Project/Invoice/Offer/Deal/Expense) 73 | - **event\*** – "create" (create/update/delete) 74 | - **hook\*** – "https://example.org/do-stuff" 75 | 76 | ## PUT /account/web_hooks/{id} 77 | 78 | Update the web hook: 79 | 80 | ```bash 81 | curl -X PUT \ 82 | 'https://{domain}.mocoapp.com/api/v1/account/web_hooks/{id}' \ 83 | -H 'Authorization: Token token=YOUR_API_KEY' \ 84 | -H 'Content-Type: application/json' \ 85 | -d '{ 86 | "hook": "https://example.org/v2" 87 | }' 88 | ``` 89 | 90 | Only the `hook` field can be updated. 91 | 92 | ## PUT /account/web_hooks/{id}/disable 93 | 94 | Disable the web hook (if already disabled, it does nothing): 95 | 96 | ```bash 97 | curl -X PUT \ 98 | 'https://{domain}.mocoapp.com/api/v1/account/web_hooks/{id}/disable' \ 99 | -H 'Authorization: Token token=YOUR_API_KEY' 100 | ``` 101 | 102 | ## PUT /account/web_hooks/{id}/enable 103 | 104 | Enable the web hook (if already enabled, it does nothing): 105 | 106 | ```bash 107 | curl -X PUT \ 108 | 'https://{domain}.mocoapp.com/api/v1/account/web_hooks/{id}/enable' \ 109 | -H 'Authorization: Token token=YOUR_API_KEY' 110 | ``` 111 | 112 | ## DELETE /account/web_hooks/{id} 113 | 114 | Removes the web hook: 115 | 116 | ```bash 117 | curl -X DELETE \ 118 | 'https://{domain}.mocoapp.com/api/v1/account/web_hooks/{id}' \ 119 | -H 'Authorization: Token token=YOUR_API_KEY' 120 | ``` 121 | -------------------------------------------------------------------------------- /webhooks.md: -------------------------------------------------------------------------------- 1 | # WebHooks 2 | 3 | Check the [MOCO docs](https://www.mocoapp.com/integrationen/35-moco-webhooks) on how to set them up via the web UI. It's also possible to manage them via [API](sections/web_hooks). 4 | 5 | Using WebHooks, integrating any system in real time becomes possible. Events in MOCO can be assigned subscriptions. 6 | Whenever an event triggers, MOCO sends an HTTPS `POST` payload to the WebHook's configured URL with an HMAC SHA265 signature. 7 | This way, MOCOs integrity as a legitimate sender of this information can be verified. Additional headers provide context 8 | for the sent payload. 9 | 10 | - **X-Moco-Target** – Activity, Customer, Project, ... 11 | - **X-Moco-Event** – create, update, delete, archive, ... 12 | - **X-Moco-Timestamp** – Timestamp for this event 13 | - **X-Moco-Signature** – The signature fo this request, see comment below for details 14 | - **X-Moco-User-Id** – The user ID that triggered this hook 15 | - **X-Moco-Account-Url** – The subdomain for the account 16 | - The receiver has to process the request within 10 seconds 17 | 18 | The following example shows a WebHook triggered by an activity creation. 19 | 20 | ``` 21 | X-Moco-Target: Activity 22 | X-Moco-Event: create 23 | X-Moco-Timestamp: 1527170410463 24 | X-Moco-Signature: f457bffc50e9b63f455ab107c55f2f61956550aa5525c2cfe07f574014bd8a9e 25 | X-Moco-User-Id: 933613686 26 | ``` 27 | 28 | - To debug and try out web hooks, we recommend [webhook.site](https://webhook.site) or [requestbin.com](https://requestbin.com/) – this services provides you with temporary 29 | HTTPS URLs that let you inspect any incoming WebHook data. 30 | - WebHooks are only provided to customers after they subscribe to MOCO. 31 | - WebHooks are not guaranteed to be delivered in order. Pay attention to the provided time stamp if this is important 32 | for your use case. 33 | - The signature uses HMAC with SHA256 to sign the whole payload. The key for the signature is the 32 characters 34 | hexadecimal string displayed in the web hook overview. 35 | 36 | ## Calculating the signature 37 | 38 | OpenSSL CLI: 39 | 40 | ```bash 41 | $ echo -n '{"id":111,"description":"a description"}' | openssl sha256 -hmac "1d608b9d72219b90ff2393a1d3ee0ac0" 42 | SHA2-256(stdin)= bf027a86207ef1ca1cb76f5a536b41a14287ab1a0fd5b33bfe86924bc2f48fd1 43 | ``` 44 | 45 | Ruby: 46 | 47 | ```ruby 48 | payload = '{"id":111,"description":"a description"}' 49 | signature_key = "1d608b9d72219b90ff2393a1d3ee0ac0" 50 | payload_signature = OpenSSL::HMAC.hexdigest("SHA256", signature_key, payload) 51 | # => "bf027a86207ef1ca1cb76f5a536b41a14287ab1a0fd5b33bfe86924bc2f48fd1" 52 | ``` 53 | 54 | NodeJS: 55 | 56 | ```javascript 57 | const crypto = require("crypto"); 58 | const hmac = crypto.createHmac("sha256", "1d608b9d72219b90ff2393a1d3ee0ac0"); 59 | const data = hmac.update('{"id":111,"description":"a description"}'); 60 | const digest = data.digest("hex"); 61 | console.log("digest = " + digest); 62 | ``` 63 | 64 | ## Notes 65 | 66 | - We expect a successful response code for the Webhook request (i.e. any 2XX code), otherwise it's considered a failure 67 | and it's retried. 68 | - After a few seconds we cancel your request (timeout), so avoid any heavy/synchronous work and consider pushing to a queue for further processing 69 | - After 500 consecutive failures a Webhook is automatically disabled. 70 | -------------------------------------------------------------------------------- /sections/employments.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: default 3 | parent: Users 4 | grand_parent: Entities 5 | --- 6 | 7 | # User Employments 8 | 9 | German: "Wochenmodell" 10 | 11 | - TOC 12 | {:toc} 13 | 14 | ## Attributes 15 | 16 | Employments contain among the standard fields also: 17 | 18 | - User 19 | 20 | ```json 21 | { 22 | "id": 982237015, 23 | "weekly_target_hours": 29.75, 24 | "pattern": { 25 | "am": [0, 4.25, 4.25, 4.25, 4.25], 26 | "pm": [0, 4.25, 4.25, 4.25, 0] 27 | }, 28 | "from": "2017-01-01", 29 | "to": null, 30 | "user": { 31 | "id": 933590696, 32 | "firstname": "John", 33 | "lastname": "Doe" 34 | }, 35 | "created_at": "2018-10-17T09:33:46Z", 36 | "updated_at": "2018-10-17T09:33:46Z" 37 | } 38 | ``` 39 | 40 | ## GET /users/employments 41 | 42 | Retrieve all employments: 43 | 44 | ```bash 45 | curl -X GET \ 46 | 'https://{domain}.mocoapp.com/api/v1/users/employments' \ 47 | -H 'Authorization: Token token=YOUR_API_KEY' 48 | ``` 49 | 50 | This returns an array of all employments. 51 | 52 | The following parameters can be supplied: 53 | 54 | - [Global filters apply](../entities#global-filters) 55 | - **from, to** – "2018-01-01", "2018-12-31" (`from` has to be provided, `to` can be left blank for all open ended employments) 56 | - **user_id** – 123 57 | 58 | ## POST /users/employments 59 | 60 | Create an employment: 61 | 62 | ```bash 63 | curl -X POST \ 64 | 'https://{domain}.mocoapp.com/api/v1/users/employments' \ 65 | -H 'Authorization: Token token=YOUR_API_KEY' \ 66 | -H 'Content-Type: application/json' \ 67 | -d '{ 68 | "user_id": 123, 69 | "pattern": { 70 | "am": [0, 4.25, 4.25, 4.25, 4.25], 71 | "pm": [0, 4.25, 4.25, 4.25, 0] 72 | }, 73 | "from": "2022-01-01", 74 | "to": "2022-12-31", 75 | }' 76 | ``` 77 | 78 | Mandatory fields are marked with a star (\*): 79 | 80 | - **user_id\*** – 123 81 | - **pattern\*** – `{ "am": [4, 4, 4, 4, 4], "pm": [4, 4, 4, 4, 4] }` the work hours during morning and afternoon on each workday 82 | - **from** – "2022-01-01" when the employment comes/came into effect (default: the current date) 83 | - **to** – "2022-12-31" when the employment stops being in effect (default: unset) 84 | 85 | ## GET /users/employments/{id} 86 | 87 | Retrieve a single employment: 88 | 89 | ```bash 90 | curl -X GET \ 91 | 'https://{domain}.mocoapp.com/api/v1/users/employments/{id}' \ 92 | -H 'Authorization: Token token=YOUR_API_KEY' 93 | ``` 94 | 95 | ## PUT /users/employments/{id} 96 | 97 | Update an employment: 98 | 99 | ```bash 100 | curl -X PUT \ 101 | 'https://{domain}.mocoapp.com/api/v1/users/employments/{id}' \ 102 | -H 'Authorization: Token token=YOUR_API_KEY' \ 103 | -H 'Content-Type: application/json' \ 104 | -d '{ 105 | "pattern": { 106 | "am": [0, 4, 4, 4, 4], 107 | "pm": [0, 4, 4, 4, 4] 108 | } 109 | }' 110 | ``` 111 | 112 | Fields are analogous to the POST request but `user_id` and `pattern` are not mandatory. 113 | 114 | ## DELETE /users/employments/{id} 115 | 116 | Delete an employment: 117 | 118 | ```bash 119 | curl -X DELETE \ 120 | 'https://{domain}.mocoapp.com/api/v1/users/employments/{id}' \ 121 | -H 'Authorization: Token token=YOUR_API_KEY' 122 | ``` 123 | -------------------------------------------------------------------------------- /sections/purchase_payments.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: default 3 | parent: Purchases 4 | grand_parent: Entities 5 | --- 6 | 7 | # Purchase Payments 8 | 9 | German: "Ausgaben / Zahlungen" 10 | 11 | - TOC 12 | {:toc} 13 | 14 | ## Attributes 15 | 16 | The purchase payment representation contains among standard fields also shortened purchase information. 17 | 18 | ```json 19 | { 20 | "id": 123, 21 | "date": "2022-03-01", 22 | "purchase": { 23 | "id": 12345, 24 | "identifier": "E2203-001", 25 | "title": "Purchase – Electronics" 26 | }, 27 | "total": "1999.00", 28 | "created_at": "2022-03-01T09:33:46Z", 29 | "updated_at": "2022-03-01T09:33:46Z" 30 | } 31 | ``` 32 | 33 | ## GET /purchases/payments 34 | 35 | Retrieve all purchase payments: 36 | 37 | ```bash 38 | curl -X GET \ 39 | 'https://{domain}.mocoapp.com/api/v1/purchases/payments' \ 40 | -H 'Authorization: Token token=YOUR_API_KEY' 41 | ``` 42 | 43 | Additionally, these parameters can be used to filter the results set: 44 | 45 | - [Global filters apply](../entities#global-filters) 46 | - **purchase_id** – "123,456" (purchase IDs, can be a single one or comma-separated) 47 | - **date_from** – "2018-01-01" 48 | - **date_to** – "2018-01-31" 49 | 50 | ## GET /purchases/payments/{id} 51 | 52 | Retrieve a single purchase payment: 53 | 54 | ```bash 55 | curl -X GET \ 56 | 'https://{domain}.mocoapp.com/api/v1/purchases/payments/{id}' \ 57 | -H 'Authorization: Token token=YOUR_API_KEY' 58 | ``` 59 | 60 | ## POST /purchases/payments 61 | 62 | Create a purchase payment: 63 | 64 | ```bash 65 | curl -X POST \ 66 | 'https://{domain}.mocoapp.com/api/v1/purchases/payments' \ 67 | -H 'Authorization: Token token=YOUR_API_KEY' \ 68 | -H 'Content-Type: application/json' \ 69 | -d '{ 70 | "date": "2018-10-20", 71 | "purchase_id": 123, 72 | "total": 1000, 73 | }' 74 | ``` 75 | 76 | Mandatory fields are marked with a star (\*): 77 | 78 | - **date\*** – "2017-10-20" 79 | - **total\*** – 1000 80 | - **purchase_id** – 12345 - ⚡ not mandatory, but if not set, `description` must be set. 81 | - **description** – "salaries" - a description of this payment, must only be set if no `purchase_id` is set. 82 | 83 | ## POST /purchases/payments/bulk 84 | 85 | Create multiple purchase payments in bulk: 86 | 87 | ```bash 88 | curl -X POST \ 89 | 'https://{domain}.mocoapp.com/api/v1/purchases/payments/bulk' \ 90 | -H 'Authorization: Token token=YOUR_API_KEY' \ 91 | -H 'Content-Type: application/json' \ 92 | -d '{ 93 | "bulk_data": [ 94 | { 95 | "date": "2018-10-20", 96 | "total": 2000, 97 | "purchase_id": 456, 98 | }, 99 | { 100 | "date": "2018-10-22", 101 | "total": 1000, 102 | "description": "salaries" 103 | } 104 | ] 105 | }' 106 | ``` 107 | 108 | Fields are analogous to the POST request. 109 | 110 | ## PUT purchases/payments/{id} 111 | 112 | Update a purchase payment: 113 | 114 | ```bash 115 | curl -X PUT \ 116 | 'https://{domain}.mocoapp.com/api/v1/purchases/payments/{id}' \ 117 | -H 'Authorization: Token token=YOUR_API_KEY' \ 118 | -H 'Content-Type: application/json' \ 119 | -d '{ 120 | "total": 2000 121 | }' 122 | ``` 123 | 124 | Fields are analogous to the POST request, except for the `purchase_id`. 125 | 126 | ## DELETE /purchases/payments/{id} 127 | 128 | Delete a purchase payment: 129 | 130 | ```bash 131 | curl -X DELETE \ 132 | 'https://{domain}.mocoapp.com/api/v1/purchases/payments/{id}' \ 133 | -H 'Authorization: Token token=YOUR_API_KEY' 134 | ``` 135 | -------------------------------------------------------------------------------- /sections/project_payment_schedules.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: default 3 | parent: Projects 4 | grand_parent: Entities 5 | --- 6 | 7 | # Project Payment Schedules 8 | 9 | German: "Projekte / Geplante Abrechnungen" 10 | 11 | - TOC 12 | {:toc} 13 | 14 | ## Attributes 15 | 16 | Payment schedules for fixed price projects. 17 | 18 | ```json 19 | { 20 | "id": 760153573, 21 | "date": "2017-04-05", 22 | "title": "Erste Anzahlung", 23 | "description": "
A description for this payment schedule
", 24 | "net_total": 1000, 25 | "project": { 26 | "id": 822322322, 27 | "identifier": "P0077", 28 | "name": "New website" 29 | }, 30 | "checked": false, 31 | "billed": false, 32 | "created_at": "2018-10-17T09:33:46Z", 33 | "updated_at": "2018-10-17T09:33:46Z" 34 | } 35 | ``` 36 | 37 | ## GET /projects/payment_schedules 38 | 39 | Retrieve all payment schedules independent of a project: 40 | 41 | ```bash 42 | curl -X GET \ 43 | 'https://{domain}.mocoapp.com/api/v1/projects/payment_schedules' \ 44 | -H 'Authorization: Token token=YOUR_API_KEY' 45 | ``` 46 | 47 | Additionally, these parameters can be supplied: 48 | 49 | - [Global filters apply](../entities#global-filters) 50 | - **from** – "2021-02-01" 51 | - **to** – "2021-02-28" 52 | - **checked** – true / false (show checked off payment schedules or unchecked schedules) 53 | - **company_id** - 1234 54 | - **project_id** - 1234 (There's also `/projects/{id}/payment_schedules`) 55 | 56 | ## GET /projects/{project_id}/payment_schedules 57 | 58 | Retrieve all payment schedules for the project: 59 | 60 | ```bash 61 | curl -X GET \ 62 | 'https://{domain}.mocoapp.com/api/v1/projects/{project_id}/payment_schedules' \ 63 | -H 'Authorization: Token token=YOUR_API_KEY' 64 | ``` 65 | 66 | Additionally, these parameters can be supplied: 67 | 68 | - **from** – "2021-02-01" 69 | - **to** – "2021-02-28" 70 | - **checked** – true / false (show checked off payment schedules or unchecked schedules) 71 | 72 | ## GET /projects/{project_id}/payment_schedules/{id} 73 | 74 | Retrieve a single payment schedule on a project: 75 | 76 | ```bash 77 | curl -X GET \ 78 | 'https://{domain}.mocoapp.com/api/v1/projects/{project_id}/payment_schedules/{id}' \ 79 | -H 'Authorization: Token token=YOUR_API_KEY' 80 | ``` 81 | 82 | ## POST /projects/{project_id}/payment_schedules 83 | 84 | Create a paymennt schedule for the project: 85 | 86 | ```bash 87 | curl -X POST \ 88 | 'https://{domain}.mocoapp.com/api/v1/projects/{project_id}/payment_schedules' \ 89 | -H 'Authorization: Token token=YOUR_API_KEY' \ 90 | -H 'Content-Type: application/json' \ 91 | -d '{ 92 | "net_total": 1800, 93 | "title": "Erste Anzahlung", 94 | "date": "2019-10-28" 95 | }' 96 | ``` 97 | 98 | Mandatory fields are marked with a star (\*): 99 | 100 | - **net_total\*** – 12000 101 | - **date\*** – "2019-10-28" 102 | - **title** – "Erste Anzahlung" 103 | - **checked** – true/false 104 | 105 | ## PUT /projects/{project_id}/payment_schedules/{id} 106 | 107 | Update a payment schedule for a project: 108 | 109 | ```bash 110 | curl -X PUT \ 111 | 'https://{domain}.mocoapp.com/api/v1/projects/{project_id}/payment_schedules/{id}' \ 112 | -H 'Authorization: Token token=YOUR_API_KEY' \ 113 | -H 'Content-Type: application/json' \ 114 | -d '{ 115 | "checked": true 116 | }' 117 | ``` 118 | 119 | Fields are analogous to the POST request. 120 | 121 | ## DELETE /projects/{project_id}/payment_schedules/{id} 122 | 123 | Delete the payment schedule. 124 | 125 | ```bash 126 | curl -X DELETE \ 127 | 'https://{domain}.mocoapp.com/api/v1/projects/{project_id}/payment_schedules/{id}' \ 128 | -H 'Authorization: Token token=YOUR_API_KEY' 129 | ``` 130 | -------------------------------------------------------------------------------- /sections/schedules.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: default 3 | parent: Entities 4 | --- 5 | 6 | # Schedules 7 | 8 | German: "Absenz" 9 | 10 | - TOC 11 | {:toc} 12 | 13 | ## Attributes 14 | 15 | Schedules are now used for absences only. Use [Planning Entries](planning_entries.md) for project schedules. 16 | 17 | The schedule representation contains among the standard fields also: 18 | 19 | - assignment (absence) 20 | - assigned user (staff) 21 | 22 | ```json 23 | { 24 | "id": 123, 25 | "date": "2017-06-14", 26 | "comment": "Half day off", 27 | "am": true, 28 | "pm": true, 29 | "symbol": null, 30 | "assignment": { 31 | "id": 789, 32 | "name": "Holiday", 33 | "code": "4", 34 | "customer_name": "hundertzehn GmbH", 35 | "color": "#BBB", 36 | "type": "Absence" 37 | }, 38 | "user": { 39 | "id": 567, 40 | "firstname": "Sabine", 41 | "lastname": "Schäuble" 42 | }, 43 | "created_at": "2018-10-17T09:33:46Z", 44 | "updated_at": "2018-10-17T09:33:46Z" 45 | } 46 | ``` 47 | 48 | ## GET /schedules 49 | 50 | Retrieve all absences (paged): 51 | 52 | ```bash 53 | curl -X GET \ 54 | 'https://{domain}.mocoapp.com/api/v1/schedules?from=2018-10-01&to=2018-10-31' \ 55 | -H 'Authorization: Token token=YOUR_API_KEY' 56 | ``` 57 | 58 | This returns an array with complete schedule information (see Attributes). 59 | 60 | Additionally, the following parameters can be supplied: 61 | 62 | - [Global filters apply](../entities#global-filters) 63 | - **from** – "2017-05-01" 64 | - **to** – "2017-05-31" 65 | - **user_id** – 123 66 | - **absence_code** – 1, 2, 3, 4, 5 (unplannable absence, public holiday, sick day, holiday, absence) – (also multiple values, comma-separated) 67 | - **holiday_request_id** – 123 (the ID of the holiday request filters all holiday absences for this request) 68 | 69 | ## GET /schedules/{id} 70 | 71 | Retrieve a single planning entry: 72 | 73 | ```bash 74 | curl -X GET \ 75 | 'https://{domain}.mocoapp.com/api/v1/schedules/{id}' \ 76 | -H 'Authorization: Token token=YOUR_API_KEY' 77 | ``` 78 | 79 | ## POST /schedules 80 | 81 | Create a planning entry: 82 | 83 | The entry is always created with the user that's executing the request (authorization token) if no `user_id` is supplied. 84 | 85 | ```bash 86 | curl -X POST \ 87 | 'https://{domain}.mocoapp.com/api/v1/schedules' \ 88 | -H 'Authorization: Token token=YOUR_API_KEY' \ 89 | -H 'Content-Type: application/json' \ 90 | -d '{ 91 | "date": "2018-10-01", 92 | "absence_code": "4" 93 | }' 94 | ``` 95 | 96 | Mandatory fields are marked with a star (\*): 97 | 98 | - **date\*** – "2017-06-11" 99 | - **absence_code\*** – 1, 2, 3, 4, 5 (unplannable absence, public holiday, sick day, holiday, absence) 100 | - **user_id** – 234567 (user ID for active staff) 101 | - **am** – true, false (morning yes/no) 102 | - **pm** – true, false (afternoon yes/no) 103 | - **comment** – "A comment..." 104 | - **symbol** – 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12 (home, building, car, graduation cap, cocktail, bells, baby carriage, users, moon, info circle, dot circle, exlamation mark) 105 | - **overwrite** – true, false (override existing entry) 106 | 107 | ## PUT /schedules/{id} 108 | 109 | Update a planning entry: 110 | 111 | ```bash 112 | curl -X PUT \ 113 | 'https://{domain}.mocoapp.com/api/v1/schedules/{id}' \ 114 | -H 'Authorization: Token token=YOUR_API_KEY' \ 115 | -H 'Content-Type: application/json' \ 116 | -d '{ 117 | "comment": "A comment", 118 | }' 119 | ``` 120 | 121 | Fields are analogous to the POST request. 122 | 123 | ## DELETE /schedules/{id} 124 | 125 | ```bash 126 | curl -X DELETE \ 127 | 'https://{domain}.mocoapp.com/api/v1/schedules/{id}' \ 128 | -H 'Authorization: Token token=YOUR_API_KEY' 129 | ``` 130 | -------------------------------------------------------------------------------- /entities.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: default 3 | title: Entities 4 | has_children: true 5 | --- 6 | 7 | # Entities 8 | 9 | ## Global Filters 10 | 11 | All list/index endpoints offer a common set of filters. 12 | 13 | ### Filter `ids` 14 | 15 | Usage: `GET /api/v1/entities?ids=123,456` 16 | 17 | Allows you to filter by comma-separated IDs and fetch multiple entities. 18 | 19 | ### Filter `updated_after` 20 | 21 | Usage: `GET /api/v1/entities?updated_after=2022-04-20T09:17:58Z` (ISO8601 timestamp) 22 | 23 | Enables you to give a timestamp for all entities that are created or updated after this timestamp, especially useful for synchronisation purposes. 24 | 25 | Combine it with a [webhook subscription](webhooks) on DELETE for the entity to have a complete synchronisation. 26 | 27 | ### Filter by Custom Fields – `custom_properties` 28 | 29 | Allows you to filter entities by one or more custom fields. The filter for the custom fields is passed via the query-parameter `custom_properties`. To query entities that contain the value "Automotive" in a custom field named "Sector", the query would need to be as follows: 30 | 31 | `GET /api/v1/entities?custom_properties[Sector]=Automotive` 32 | 33 | {: .note } 34 | Filtering by an unknown custom field will result in an empty result set! 35 | 36 | #### Custom Fields of type MultiSelect 37 | 38 | For custom fields of type `MultiSelect` can store multiple values. They can be queried by a single value or multiple values. Assuming there is a custom field named "Sector" of type `MultiSelect`, the following queries are possible: 39 | 40 | - querying for a single value: `GET /api/v1/entities?custom_properties[Sector]=Pharma` 41 | 42 | This will find entities with the value "Pharma" in the custom field named `Sector`. Additional values may be present in the custom field named "Sector" and the entity is still matched. 43 | 44 | - querying for multiple values: `GET /api/v1/entities?custom_properties[Sector][]=Pharma&custom_properties[Sector][]=Chemistry` 45 | 46 | This will find entities with both the values "Pharma" and "Chemistry" in the custom field named "Sector". Additional values may be present in the custom field named "Sector" and the entity is still matched. 47 | 48 | The multiple values are given in the array bracket format (notice the empty bracket after the custom field name), i.e. `custom_properties[Sector][]=Pharma&custom_properties[Sector][]=Chemistry` will correspond to the following JSON: 49 | 50 | ```JSON 51 | { 52 | "custom_properties": { 53 | "Sector": ["Pharma", "Chemistry"] 54 | } 55 | } 56 | ``` 57 | 58 | While this `custom_properties[Sector]=Pharma` will correspond to the following JSON: 59 | 60 | ```JSON 61 | { 62 | "custom_properties": { 63 | "Sector": "Pharma" 64 | } 65 | } 66 | ``` 67 | 68 | Both are valid for querying custom field of type `MultiSelect`. 69 | 70 | #### Custom Fields of type Boolean 71 | 72 | Custom fields of type `Boolean` can be queried with `true` or `false`. Assuming there is a custom field named "Newsletter" of type `Boolean`, the following queries are possible: 73 | 74 | - `GET /api/v1/entities?custom_properties[Newsletter]=true` 75 | 76 | Will find all entities for which the custom field named "Newsletter" is set to true. 77 | 78 | - `GET /api/v1/entities?custom_properties[Newsletter]=false` 79 | 80 | Will find all entities for which the custom field named "Newsletter" is set to false. 81 | 82 | {: .note } 83 | This will not find entities for which the custom field named "Newsletter" was not set to any value. 84 | 85 | #### Custom Fields of other types 86 | 87 | Custom fields of type `Date` need to be queried with the date-format `YYYY-MM-DD`, e.g. query all entities with a "Subscription Date" of March 25th, 2024: 88 | 89 | - `GET /api/v1/entities?custom_properties[Subscription Date]=2024-03-25` 90 | 91 | For custom fields of type `Select`, `Textarea`, `String`, `Link`, the queried value needs to match exactly, i.e. partial matches do not result in a match. 92 | -------------------------------------------------------------------------------- /sections/invoice_payments.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: default 3 | parent: Invoices 4 | grand_parent: Entities 5 | --- 6 | 7 | # Invoice Payments 8 | 9 | German: "Rechnungen / Zahlungen" 10 | 11 | - TOC 12 | {:toc} 13 | 14 | ## Attributes 15 | 16 | The invoice payment representation contains among standard fields also shortened invoice information. 17 | 18 | ```json 19 | { 20 | "id": 123, 21 | "date": "2017-10-01", 22 | "invoice": { 23 | "id": 12345, 24 | "identifier": "R1710-001", 25 | "title": "Invoice – Website" 26 | }, 27 | "paid_total": "17999.00", 28 | "paid_total_in_account_currency": "17999.00", 29 | "currency": "EUR", 30 | "description": "", 31 | "created_at": "2018-10-17T09:33:46Z", 32 | "updated_at": "2018-10-17T09:33:46Z" 33 | } 34 | ``` 35 | 36 | ## GET /invoices/payments 37 | 38 | Retrieve all invoice payments: 39 | 40 | ```bash 41 | curl -X GET \ 42 | 'https://{domain}.mocoapp.com/api/v1/invoices/payments' \ 43 | -H 'Authorization: Token token=YOUR_API_KEY' 44 | ``` 45 | 46 | Additionally, these parameters can be used to filter the results set: 47 | 48 | - [Global filters apply](../entities#global-filters) 49 | - **invoice_id** – 123 50 | - **date_from** – "2018-01-01" 51 | - **date_to** – "2018-01-31" 52 | 53 | ## GET /invoices/payments/{id} 54 | 55 | Retrieve a single invoice payment: 56 | 57 | ```bash 58 | curl -X GET \ 59 | 'https://{domain}.mocoapp.com/api/v1/invoices/payments/{id}' \ 60 | -H 'Authorization: Token token=YOUR_API_KEY' 61 | ``` 62 | 63 | ## POST /invoices/payments 64 | 65 | Create an invoice payment: 66 | 67 | ```bash 68 | curl -X POST \ 69 | 'https://{domain}.mocoapp.com/api/v1/invoices/payments' \ 70 | -H 'Authorization: Token token=YOUR_API_KEY' \ 71 | -H 'Content-Type: application/json' \ 72 | -d '{ 73 | "date": "2018-10-20", 74 | "invoice_id": 123, 75 | "paid_total": 1000, 76 | "currency": "EUR" 77 | }' 78 | ``` 79 | 80 | Mandatory fields are marked with a star (\*): 81 | 82 | - **date\*** – "2017-10-20" 83 | - **invoice_id** – 12345 84 | - **paid_total\*** – 1000 85 | - **currency** – "EUR" 86 | - **partially_paid** – true/false 87 | - **description** – "Provision" (must be provided if `invoice_id` is omitted) 88 | 89 | ## POST /invoices/payments/bulk 90 | 91 | Create multiple invoice payments in bulk: 92 | 93 | ```bash 94 | curl -X POST \ 95 | 'https://{domain}.mocoapp.com/api/v1/invoices/payments/bulk' \ 96 | -H 'Authorization: Token token=YOUR_API_KEY' \ 97 | -H 'Content-Type: application/json' \ 98 | -d '{ 99 | "bulk_data": [ 100 | { 101 | "date": "2018-10-20", 102 | "invoice_id": 456, 103 | "paid_total": 2000, 104 | "currency": "EUR" 105 | }, 106 | { 107 | "date": "2018-10-22", 108 | "invoice_id": 123, 109 | "paid_total": 1000, 110 | "currency": "EUR" 111 | } 112 | ] 113 | }' 114 | ``` 115 | 116 | Mandatory fields are marked with a star (\*): 117 | 118 | - **date\*** – "2018-10-20" 119 | - **invoice_id\*** – 12345 120 | - **paid_total\*** – 1000 121 | - **currency** – "EUR" 122 | 123 | ## PUT invoices/payments/{id} 124 | 125 | Update an invoice payment: 126 | 127 | ```bash 128 | curl -X PUT \ 129 | 'https://{domain}.mocoapp.com/api/v1/invoices/payments/{id}' \ 130 | -H 'Authorization: Token token=YOUR_API_KEY' \ 131 | -H 'Content-Type: application/json' \ 132 | -d '{ 133 | "paid_total": 2000 134 | }' 135 | ``` 136 | 137 | Fields are analogous to the POST request, except for the `invoice_id`. 138 | 139 | ## DELETE /invoices/payments/{id} 140 | 141 | Delete an invoice payment: 142 | 143 | ```bash 144 | curl -X DELETE \ 145 | 'https://{domain}.mocoapp.com/api/v1/invoices/payments/{id}' \ 146 | -H 'Authorization: Token token=YOUR_API_KEY' 147 | ``` 148 | -------------------------------------------------------------------------------- /sections/contacts.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: default 3 | parent: Entities 4 | --- 5 | 6 | # Contacts 7 | 8 | German: "Kontakte / Ansprechpartner" 9 | 10 | - TOC 11 | {:toc} 12 | 13 | ## Attributes 14 | 15 | Includes among the standard fields for contacts also: 16 | 17 | - Tags 18 | - Company (if this contact belongs to a company) 19 | 20 | ```json 21 | { 22 | "id": 123, 23 | "gender": "M", 24 | "firstname": "Peter", 25 | "lastname": "Muster", 26 | "title": "Dr. med.", 27 | "job_position": "Account Manager", 28 | "mobile_phone": "+41 123 45 67", 29 | "work_fax": "", 30 | "work_phone": "+41 445 45 67", 31 | "work_email": "peter.muster@beispiel.ch", 32 | "work_address": "Beispiel AG\nPeter Muster\nBeispielstrasse 123", 33 | "home_email": "", 34 | "home_address": "", 35 | "birthday": "1959-05-22", 36 | "info": "", 37 | "avatar_url": "https//meinefirma.mocoapp.com/.../profil.jpg", 38 | "tags": ["Key Account", "Christmas Card"], 39 | "company": { 40 | "id": 123456, 41 | "type": "customer", 42 | "name": "Beispiel AG" 43 | }, 44 | "created_at": "2018-10-17T09:33:46Z", 45 | "updated_at": "2018-10-17T09:33:46Z" 46 | } 47 | ``` 48 | 49 | ## GET /contacts/people 50 | 51 | Retrieve all contacts: 52 | 53 | ```bash 54 | curl -X GET \ 55 | 'https://{domain}.mocoapp.com/api/v1/contacts/people' \ 56 | -H 'Authorization: Token token=YOUR_API_KEY' 57 | ``` 58 | 59 | It's also possible to filter: 60 | 61 | - [Global filters apply](../entities#global-filters) 62 | - **tags** "Influencer, Early Adopter" (comma separated list) 63 | - **term** "mario, volkswagen" (full text search name, firstname, work_email, company) 64 | - **phone** 79 826 (reverse lookup for work_phone or mobile_phone) 65 | 66 | Returns an array with all contact information (see attributes), except `info`. 67 | 68 | ## GET /contacts/people/{id} 69 | 70 | Retrieve a single contact: 71 | 72 | ```bash 73 | curl -X GET \ 74 | 'https://{domain}.mocoapp.com/api/v1/contacts/people/{id}' \ 75 | -H 'Authorization: Token token=YOUR_API_KEY' 76 | ``` 77 | 78 | Returns the representation for a single contact, including tags and the company. 79 | 80 | ## POST /contacts/people 81 | 82 | Create a contact: 83 | 84 | ```bash 85 | curl -X POST \ 86 | 'https://{domain}.mocoapp.com/api/v1/contacts/people' \ 87 | -H 'Authorization: Token token=YOUR_API_KEY' \ 88 | -H 'Content-Type: application/json' \ 89 | -d '{ 90 | "firstname": "Peter", 91 | "lastname": "Muster", 92 | "birthday": "1959-05-22" 93 | }' 94 | ``` 95 | 96 | Mandatory fields are marked with a star (\*): 97 | 98 | - **firstname** – "Peter" 99 | - **lastname\*** – "Muster" 100 | - **gender\*** – "F", "M" or "U" 101 | - **company_id** – 123 102 | - **user_id** - 456 (responsible for this contact), current user is default 103 | - **title** – "Dr. med." 104 | - **job_position** – "Account Manager" 105 | - **mobile_phone** – "+49 177 123 45 67" 106 | - **work_fax** – "+49 30 123 45 67" 107 | - **work_phone** – "+49 30 123 45 67" 108 | - **work_email** – "bestellung@lieferant.de" 109 | - **work_address** – "Lieferant AG\nBeispielstrasse 123\n12345 Berlin" 110 | - **home_email** – "privat@home.ch" 111 | - **home_address** – "Peter Muster\nZu Hause" 112 | - **birthday** – "1959-05-22" 113 | - **info** – "Information for this company" 114 | - **tags** – ["Christmas Card", "Project Lead"] 115 | 116 | ## PUT /contacts/people/{id} 117 | 118 | Update a contact: 119 | 120 | ```bash 121 | curl -X PUT \ 122 | 'https://{domain}.mocoapp.com/api/v1/contacts/people/{id}' \ 123 | -H 'Authorization: Token token=YOUR_API_KEY' \ 124 | -H 'Content-Type: application/json' \ 125 | -d '{ 126 | "job_position": "Head of Sales" 127 | }' 128 | ``` 129 | 130 | Fields are analogous to the POST request. 131 | 132 | ## DELETE /contacts/people/{id} 133 | 134 | ```bash 135 | curl -X DELETE \ 136 | 'https://{domain}.mocoapp.com/api/v1/contacts/people/{id}' \ 137 | -H 'Authorization: Token token=YOUR_API_KEY' 138 | ``` 139 | -------------------------------------------------------------------------------- /sections/planning_entries.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: default 3 | parent: Entities 4 | --- 5 | 6 | # Planning Entries 7 | 8 | German: "Planung" 9 | 10 | - TOC 11 | {:toc} 12 | 13 | ## Attributes 14 | 15 | The planning entry representation contains among the standard fields also: 16 | 17 | - assigned user (staff) 18 | - *either* project *or* deal, the other is set to `null` 19 | - deal attributes (project attributes are given in the example below): 20 | ```json 21 | { 22 | "id": 6542, 23 | "name": "Redesign website", 24 | "customer_name": "Acme GmbH", 25 | "color": "#aacb84" 26 | } 27 | ``` 28 | 29 | 30 | ```json 31 | { 32 | "id": 4839, 33 | "title": "Project Management", 34 | "starts_on": "2020-05-04", 35 | "ends_on": "2020-05-04", 36 | "hours_per_day": 6.0, 37 | "comment": "", 38 | "symbol": null, 39 | "color": "#2965cc", 40 | "read_only": false, 41 | "user": { 42 | "id": 5484, 43 | "firstname": "Thomas", 44 | "lastname": "Munster" 45 | }, 46 | "project": { 47 | "id": 4553, 48 | "identifier": "130", 49 | "name": "Support", 50 | "customer_name": "Acme GmbH", 51 | "color": "#faeb44" 52 | }, 53 | "task": { 54 | "id": 6789, 55 | "name": "Projektleitung" 56 | }, 57 | "deal": null, 58 | "series_id": null, 59 | "tentative": false, 60 | "series_repeat": null, 61 | "created_at": "2018-10-17T09:33:46Z", 62 | "updated_at": "2018-10-17T09:33:46Z" 63 | } 64 | ``` 65 | 66 | ## GET /planning_entries 67 | 68 | Retrieve all planning entries (paged): 69 | 70 | ```bash 71 | curl -X GET \ 72 | 'https://{domain}.mocoapp.com/api/v1/planning_entries?period=2020-04-01:2020-07-31' \ 73 | -H 'Authorization: Token token=YOUR_API_KEY' 74 | ``` 75 | 76 | This returns an array with complete information about the planning entries (see Attributes). 77 | 78 | The following parameters can be supplied: 79 | 80 | - [Global filters apply](../entities#global-filters) 81 | - **period** – "2020-05-01:2020-07-31" 82 | - **user_id** – 123 83 | - **project_id** – 345 84 | - **deal_id** – 456 85 | 86 | ## GET /planning_entries/{id} 87 | 88 | Retrieve a single planning entry: 89 | 90 | ```bash 91 | curl -X GET \ 92 | 'https://{domain}.mocoapp.com/api/v1/planning_entries/{id}' \ 93 | -H 'Authorization: Token token=YOUR_API_KEY' 94 | ``` 95 | 96 | ## POST /planning_entries 97 | 98 | Create a planning entry: 99 | 100 | The entry is always created with the user that's executing the request (authorization token) if no `user_id` is supplied. 101 | 102 | ```bash 103 | curl -X POST \ 104 | 'https://{domain}.mocoapp.com/api/v1/planning_entries' \ 105 | -H 'Authorization: Token token=YOUR_API_KEY' \ 106 | -H 'Content-Type: application/json' \ 107 | -d '{ 108 | "project_id": 4322, 109 | "task_id": 6789, 110 | "starts_on": "2020-05-20", 111 | "ends_on": "2020-05-30", 112 | "hours_per_day": 3, 113 | "comment": "A comment...", 114 | "symbol": 2 115 | }' 116 | ``` 117 | 118 | Mandatory fields are marked with a star (\*): 119 | 120 | - either **project_id\*** or **deal_id\*** – 4322 (project or deal ID) 121 | - **starts_on\*** – "2020-05-20" 122 | - **ends_on\*** – "2020-05-30" 123 | - **hours_per_day\*** – 3 124 | - **user_id** – 234567 (user ID for active staff) 125 | - **comment** – "A comment..." 126 | - **symbol** – 1, 2, 3, 4, 5, 6, 7, 8, 9, 10 (home, building, car, graduation cap, cocktail, bells, baby carriage, users, moon , info circle) 127 | - **tentative** - true / false (whether this is a blocker or not) 128 | 129 | ## PUT /planning_entries/{id} 130 | 131 | Update a planning entry: 132 | 133 | ```bash 134 | curl -X PUT \ 135 | 'https://{domain}.mocoapp.com/api/v1/planning_entries/{id}' \ 136 | -H 'Authorization: Token token=YOUR_API_KEY' \ 137 | -H 'Content-Type: application/json' \ 138 | -d '{ 139 | "hours_per_day": 5 140 | }' 141 | ``` 142 | 143 | Fields are analogous to the POST request. 144 | 145 | ## DELETE /planning_entries/{id} 146 | 147 | ```bash 148 | curl -X DELETE \ 149 | 'https://{domain}.mocoapp.com/api/v1/planning_entries/{id}' \ 150 | -H 'Authorization: Token token=YOUR_API_KEY' 151 | ``` 152 | -------------------------------------------------------------------------------- /sections/account/custom_properties.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: default 3 | title: Custom Properties 4 | parent: Account 5 | grand_parent: Entities 6 | --- 7 | 8 | # Custom Properties 9 | 10 | German: "Eigene Felder" 11 | 12 | - TOC 13 | {:toc} 14 | 15 | ## Attributes 16 | 17 | - **entity** – any kind of entity that a custom property can be added to 18 | - **kind** – `String` / `Textarea` / `Link` / `Boolean` / `Select` / `MultiSelect` / `Date` 19 | - **defaults** – for selections: the options that can be selected, empty strings are also valid. 20 | - **placeholder** – the placeholder text displayed on MOCO for input fields 21 | - **notification_enabled** – for kind `Date` a notification is sent to a user (dependent on the entity). 22 | 23 | ```json 24 | { 25 | "id": 8601, 26 | "name": "Purchase Order Number", 27 | "name_alt": "Numero Identificativo Acquisto", 28 | "placeholder": "", 29 | "placeholder_alt": "", 30 | "entity": "Project", 31 | "kind": "String", 32 | "print_on_invoice": true, 33 | "print_on_offer": false, 34 | "print_on_timesheet": true, 35 | "notification_enabled": false, 36 | "defaults": [], 37 | "updated_at": "2022-08-15T15:31:28Z", 38 | "created_at": "2022-08-15T15:31:22Z" 39 | } 40 | ``` 41 | 42 | ## GET /account/custom_properties 43 | 44 | Retrieve custom properties: 45 | 46 | ```bash 47 | curl -X GET \ 48 | 'https://{domain}.mocoapp.com/api/v1/account/custom_properties' \ 49 | -H 'Authorization: Token token=YOUR_API_KEY' 50 | ``` 51 | 52 | The following parameters can be supplied: 53 | 54 | - [Global filters apply](../../entities#global-filters) 55 | - **entity** – e.g. `Project` (any kind of entity that a custom property can be added to) 56 | 57 | returns an array of custom properties. 58 | 59 | ## GET /account/custom_properties/{id} 60 | 61 | Retrieve custom properties: 62 | 63 | ```bash 64 | curl -X GET \ 65 | 'https://{domain}.mocoapp.com/api/v1/account/custom_properties/{id}' \ 66 | -H 'Authorization: Token token=YOUR_API_KEY' 67 | ``` 68 | 69 | returns a single custom property. 70 | 71 | ## POST /account/custom_properties 72 | 73 | Create a new custom property: 74 | 75 | ```bash 76 | curl -X POST \ 77 | 'https://{domain}.mocoapp.com/api/v1/account/custom_properties' \ 78 | -H 'Authorization: Token token=YOUR_API_KEY' \ 79 | -H 'Content-Type: application/json' \ 80 | -d '{ 81 | "name": "Slogan", 82 | "kind": "String", 83 | "entity": "Deal" 84 | }' 85 | ``` 86 | 87 | Mandatory fields are marked with a star (\*): 88 | 89 | - **name\*** – "Slogan" name of the custom property 90 | - **kind\*** – String | Textarea | Link | Boolean | Select | MultiSelect | Date 91 | - **entity\*** – Deal | Project | Customer | ... 92 | - **placeholder** – placeholder text displayed on MOCO for the input fields 93 | - **placeholder_alt** – paceholder in the alternative language 94 | - **print_on_invoice** – true/false (if true, the custom property is printed on invoices) 95 | - **print_on_offer** – true/false (if true, the custom property is printed on offers) 96 | - **print_on_timesheet** – true/false (if true, the custom property is printed on timesheets) 97 | - **notification_enabled** – true/false (for kind `Date` a notification is sent to a user, dependent on the entity) 98 | - **api_only** – true/false (if true, the custom property is not displayed in the UI, but can be used via the API) 99 | - **defaults** – for selections: the options that can be selected, empty strings are also valid. 100 | 101 | ## PATCH /account/custom_properties/{id} 102 | 103 | Update a new custom property: 104 | 105 | ```bash 106 | 107 | curl -X PATCH \ 108 | 'https://{domain}.mocoapp.com/api/v1/account/custom_properties/{id}' \ 109 | -H 'Authorization: Token token=YOUR_API_KEY' \ 110 | -H 'Content-Type: application/json' \ 111 | -d '{ 112 | "name": "Slogan", 113 | "placeholder": "Enter your slogan here", 114 | }' 115 | ``` 116 | 117 | Fields are analogous to the POST request, but `kind` and `entity` cannot be changed. 118 | 119 | ## DELETE /account/custom_properties/{id} 120 | 121 | Deletes the custom property: 122 | 123 | ```bash 124 | curl -X DELETE \ 125 | 'https://{domain}.mocoapp.com/api/v1/account/custom_properties/{id}' \ 126 | -H 'Authorization: Token token=YOUR_API_KEY' 127 | -------------------------------------------------------------------------------- /sections/invoice_reminders.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: default 3 | parent: Invoices 4 | grand_parent: Entities 5 | --- 6 | 7 | # Invoice Reminders 8 | 9 | German: "Mahnung / Zahlungserinnerung" 10 | 11 | - TOC 12 | {:toc} 13 | 14 | ## Attributes 15 | 16 | The invoice reminder representation contains among standard fields also shortened invoice information. 17 | 18 | * `status` can be `created` or `sent`. 19 | 20 | ```json 21 | { 22 | "id": 1, 23 | "title": "Zahlungserinnerung", 24 | "text": "Bei der Bearbeitung unserer Buchhaltung ist uns aufgefallen, dass wir für folgende Rechnung noch keinen Zahlungseingang verbuchen konnten. Sicherlich handelt es sich hierbei um ein Versehen. Wir bitten Sie höflich, uns den Betrag in den nächsten Tagen zu überweisen. Sollte sich Ihre Zahlung mit diesem Schreiben gekreuzt haben, betrachten Sie diese Erinnerung als gegenstandslos.", 25 | "fee": 0.0, 26 | "date": "2019-10-16", 27 | "due_date": "2019-10-30", 28 | "status": "created", 29 | "invoice": { 30 | "id": 1489, 31 | "identifier": "1409-019", 32 | "title": "Rechnung - Android Prototype" 33 | }, 34 | "created_at": "2019-10-30T07:20:40Z", 35 | "updated_at": "2020-03-19T09:13:44Z" 36 | } 37 | ``` 38 | 39 | ## GET /invoice_reminders 40 | 41 | Retrieve all invoice reminders: 42 | 43 | ```bash 44 | curl -X GET \ 45 | 'https://{domain}.mocoapp.com/api/v1/invoice_reminders' \ 46 | -H 'Authorization: Token token=YOUR_API_KEY' 47 | ``` 48 | 49 | Additionally, these parameters can be used to filter the results set: 50 | 51 | - [Global filters apply](../entities#global-filters) 52 | - **invoice_id** – 123 53 | - **date_from** – "2018-01-01" 54 | - **date_to** – "2018-01-31" 55 | 56 | ## GET /invoice_reminders/{id} 57 | 58 | Retrieve a single invoice reminder: 59 | 60 | ```bash 61 | curl -X GET \ 62 | 'https://{domain}.mocoapp.com/api/v1/invoice_reminders/{id}' \ 63 | -H 'Authorization: Token token=YOUR_API_KEY' 64 | ``` 65 | 66 | ## POST /invoice_reminders 67 | 68 | Create an invoice reminder: 69 | 70 | ```bash 71 | curl -X POST \ 72 | 'https://{domain}.mocoapp.com/api/v1/invoice_reminders' \ 73 | -H 'Authorization: Token token=YOUR_API_KEY' \ 74 | -H 'Content-Type: application/json' \ 75 | -d '{ 76 | "invoice_id": 546046, 77 | "title": "Mahnung", 78 | "text": "Hallo", 79 | "date": "2020-08-04", 80 | "due_date": "2020-09-12" 81 | }' 82 | ``` 83 | 84 | Mandatory fields are marked with a star (\*): 85 | 86 | - **invoice_id\*** – 546046 87 | - **title** – "Mahnung", 88 | - **text** – "Sehr geehrte Damen und Herren..." 89 | - **fee** – 50 90 | - **date** – "2020-08-04" 91 | - **due_date** – "2020-09-12" 92 | 93 | Fields `title` and `text` are optional. If these fields are obmitted the configured default values are taken. 94 | 95 | ## DELETE /invoice_reminders/{id} 96 | 97 | Delete an invoice reminder: 98 | 99 | ```bash 100 | curl -X DELETE \ 101 | 'https://{domain}.mocoapp.com/api/v1/invoices_reminders/{id}' \ 102 | -H 'Authorization: Token token=YOUR_API_KEY' 103 | ``` 104 | 105 | ## POST /invoice_reminders/{id}/send_email 106 | 107 | Send the reminder by email: 108 | 109 | ```bash 110 | curl -X POST \ 111 | 'https://{domain}.mocoapp.com/api/v1/invoice_reminders/{id}/send_email' \ 112 | -H 'Authorization: Token token=YOUR_API_KEY' \ 113 | -H 'Content-Type: application/json' \ 114 | -d '{ 115 | "emails_to": "somebody@example.com", 116 | "subject": "reminder", 117 | "text": "pending invoice" 118 | }' 119 | ``` 120 | 121 | Mandatory fields are marked with a star (\*): 122 | 123 | - **subject\*** – "Invoice", 124 | - **text\*** – "Kind regards" 125 | - **emails_to** – "somebody@example.com;info@example.com" (list of addresses separated by _;_). To use default recipients, see information below. 126 | - **emails_cc** – "somebodyelse@example.com" (list of addresses separated by _;_) 127 | - **emails_bcc** – "somebody@partner.example.com" (list of addresses separated by _;_) 128 | 129 | 🛈 If you want to send emails to the default recipients configured in the project or on the customer, leave `emails_to`, `emails_cc` and `emails_bcc` empty. `emails_to` always needs to be provided, either via the default recipients or as a given value. In the response, the recipients selected are returned. 130 | -------------------------------------------------------------------------------- /index.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: default 3 | title: Moco API Documentation 4 | nav_exclude: true 5 | --- 6 | 7 | # MOCO API Documentation 8 | 9 | This is the official API documentation for [mocoapp.com](https://www.mocoapp.com). 10 | 11 | * TOC 12 | {:toc} 13 | 14 | ## General 15 | 16 | - Request payloads to MOCO must be sent as valid JSON with a mandatory `Content-Type: application/json`-header. Responses are also sent as JSON. 17 | - All requests have to be [authenticated](authentication) with a key 18 | - Example responses showcase the happy case, i.e. usually the `200 OK` response 19 | - Collections are usually [paginated](#pagination) 20 | - Zapier triggers are **not** triggered for API requests 21 | - Timestamps `created_at` and `updated_at` are sent for all entities in UTC, as ISO8601 format. 22 | - For synchronization almost all resources can be filtered by `updated_after` passing a time in UTC, as ISO8601 format. 23 | - MOCO does not support any client-libraries at the moment. However, there are currently the following unofficial clients available, which you can use at your risk: [Python Client](https://github.com/sommalia/moco-wrapper) 24 | 25 | ## Entities 26 | 27 | All the entities exposed via the API can be found in their [respective sections](entities.md) 28 | 29 | ## Client Implementations / API Wrappers 30 | 31 | Here's a list of API client implementations, not maintained by us. Feel free to open up a PR to point to your implementation so others can re-use it. 32 | 33 | | Language | Repository | 34 | | :------: | :-------------------------------------------------------------------------------------------------: | 35 | | Python | [https://github.com/sommalia/moco-wrapper](https://github.com/sommalia/moco-wrapper) | 36 | | PHP | [https://github.com/mbs-hub/moco-php](https://github.com/mbs-hub/moco-php) | 37 | | Ruby | [https://github.com/starsong-consulting/moco-ruby](https://github.com/starsong-consulting/moco-ruby) | 38 | 39 | ## Impersonation 40 | 41 | By default all requests are scoped to the authenticated user. Some resources cannot be provided with a `user_id` or similar, like `Activities` and `User Presences`. This reflects the behaviour in the UI, since every user can only create their own activities or presences. But you can login as another user provided that the authenticated user has permission to _Staff_. To achieve the same behaviour in the API, one can set the following x-header: 42 | 43 | `X-IMPERSONATE-USER-ID=123` (user id to act in behalf of) 44 | 45 | ## Rate Limiting 46 | 47 | You can expect to be able to send 120 requests per 2 minutes (~ 1 request per second). For the unlimited plan, its 1200 requests per 2 minutes (~ 10 per second). If you exceed this limit, the server responds with `429 Too Many Requests`. 48 | 49 | ## Pagination 50 | 51 | Responses are paginated with a common default of 100 entries per page. In the HTTP response header, the current page, the entries per page and the number of total entries is reported. There is also a link header to links to the consecutive page. 52 | 53 | - **X-Page** – 3 54 | - **X-Per-Page** – 100 55 | - **X-Total** – 415 56 | - **Link** – `; rel="next"` 57 | 58 | If there is not Link header with `rel="next"`, the current page is the last page. 59 | 60 | ## Errors and HTTP status codes 61 | 62 | The MOCO-API is mostly conformant with the [general HTTP status codes](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes). 63 | 64 | Here are the most comment errors you will see: 65 | 66 | - **401 Unauthorized** - Check the error message in the response body 67 | - **403 Forbidden** - Check your [Authentication](#authentication) or your MOCO user permission 68 | - **404 Not Found** - Check that resource exists (maybe it was deleted in the meantime) 69 | - **422 Unprocessable Entity** - Check the provided error message in the response body 70 | - **429 Too Many Requests** - Check [Rate Limiting](#rate-limiting) 71 | 72 | ## Sorting 73 | 74 | Sorting is controlled by the `sort_by` query parameter. Its value is the field name that should be sorted, followed by an optional sorting order (`asc` or `desc`, default is `asc`). 75 | 76 | Example: 77 | 78 | - `https://{domain}.mocoapp.com/api/v1/offers?sort_by=title desc` 79 | 80 | 81 | 82 | -------------------------------------------------------------------------------- /sections/deals.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: default 3 | parent: Entities 4 | has_children: true 5 | --- 6 | 7 | # Deals / Leads 8 | 9 | German: "Leads" 10 | 11 | - TOC 12 | {:toc} 13 | 14 | ## Attributes 15 | 16 | The lead representation contains among standard fields also: 17 | 18 | - Custom properties, if set 19 | - User (representative) 20 | - Company 21 | - Person 22 | - Category 23 | - Status ("potential", "pending", "won", "lost", "dropped") 24 | 25 | Company and person are optional. The category is only important in status "pending". 26 | 27 | ```json 28 | { 29 | "id": 123, 30 | "name": "Website V2", 31 | "status": "pending", 32 | "reminder_date": "2022-09-19", 33 | "closed_on": null, 34 | "money": 61000.0, 35 | "currency": "CHF", 36 | "info": "Interesting Lead!", 37 | "custom_properties": { 38 | "Type": "Website" 39 | }, 40 | "user": { 41 | "id": 933593033, 42 | "firstname": "Nicola", 43 | "lastname": "Piccinini" 44 | }, 45 | "company": { 46 | "id": 760260535, 47 | "name": "Beispiel AG", 48 | "type": "customer" 49 | }, 50 | "person": { 51 | "id": 123311, 52 | "name": "Max Muster" 53 | }, 54 | "category": { 55 | "id": 12, 56 | "name": "Angebot", 57 | "probability": 30 58 | }, 59 | "service_period_from": "2022-09-01", 60 | "service_period_to": "2023-01-31", 61 | "inbox_email_address": "lead-website-v2-jh72nuqrkfcndwkj@inbox.mocoapp.com", 62 | "created_at": "2021-10-17T09:33:46Z", 63 | "updated_at": "2012-10-17T09:33:46Z" 64 | } 65 | ``` 66 | 67 | ## GET /deals 68 | 69 | Retrieve all leads: 70 | 71 | ```bash 72 | curl -X GET \ 73 | 'https://{domain}.mocoapp.com/api/v1/deals' \ 74 | -H 'Authorization: Token token=YOUR_API_KEY' 75 | ``` 76 | 77 | Additionally, these parameters can be supplied: 78 | 79 | - [Global filters apply](../entities#global-filters) 80 | - **status** – "potential", "pending", "won", "lost" or "dropped" 81 | - **tags** - "Important, Strategic" (comma separated list) 82 | - **closed_from** / **closed_to** - One or both parameters can be given to define an open or closed range for the `closed_on` attribute 83 | - **company_id** - 123 84 | 85 | This returns an array with complete lead information (see attributes). 86 | 87 | ## GET /deals/{id} 88 | 89 | Retrieve a single lead: 90 | 91 | ```bash 92 | curl -X GET \ 93 | 'https://{domain}.mocoapp.com/api/v1/deals/{id}' \ 94 | -H 'Authorization: Token token=YOUR_API_KEY' 95 | ``` 96 | 97 | The response is a single lead representation. 98 | 99 | ## POST /deals 100 | 101 | Create a lead: 102 | 103 | ```bash 104 | curl -X POST \ 105 | 'https://{domain}.mocoapp.com/api/v1/deals' \ 106 | -H 'Authorization: Token token=YOUR_API_KEY' \ 107 | -H 'Content-Type: application/json' \ 108 | -d '{ 109 | "name": "Beispiel AG Website Relaunch", 110 | "currency": "EUR", 111 | "money": 25000, 112 | "reminder_date": "2018-12-01", 113 | "user_id": 123, 114 | "deal_category_id": 456, 115 | }' 116 | ``` 117 | 118 | Mandatory fields are marked with a star (\*): 119 | 120 | - **name\*** – "Beispiel AG / Website Relaunch" 121 | - **currency\*** – "EUR" 122 | - **money\*** – 25000 123 | - **reminder_date\*** – "2017-08-15" 124 | - **user_id\*** – 123 125 | - **deal_category_id\*** – 456 126 | - **company_id** – 789 127 | - **person_id** – 357 128 | - **info** – "Information for this lead..." 129 | - **status** – "potential", "pending", "won", "lost" or "dropped" (default: "pending") 130 | - **closed_on** – "2021-12-27" 131 | - **service_period_from** – "2022-06-01" ⚠️ must be the first of the month 132 | - **service_period_to** – "2022-12-31" ⚠️ must be the last of the month 133 | - **tags** – ["Important", "Health"] 134 | 135 | ## PUT /deals/{id} 136 | 137 | Update a lead: 138 | 139 | ```bash 140 | curl -X PUT \ 141 | 'https://{domain}.mocoapp.com/api/v1/deals/{id}' \ 142 | -H 'Authorization: Token token=YOUR_API_KEY' \ 143 | -H 'Content-Type: application/json' \ 144 | -d '{ 145 | "status": "lost" 146 | }' 147 | ``` 148 | 149 | Fields are analogous to the POST request. 150 | 151 | ## DELETE /deals/{id} 152 | 153 | Delete a deal. 154 | 155 | ```bash 156 | curl -X DELETE \ 157 | 'https://{domain}.mocoapp.com/api/v1/deals/{id}' \ 158 | -H 'Authorization: Token token=YOUR_API_KEY' 159 | ``` 160 | -------------------------------------------------------------------------------- /sections/presences.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: default 3 | parent: Users 4 | grand_parent: Entities 5 | --- 6 | 7 | # User Presences 8 | 9 | German: "Arbeitszeiten" 10 | 11 | - TOC 12 | {:toc} 13 | 14 | ## Attributes 15 | 16 | Presences contain among the standard fields also: 17 | 18 | - User (creator) 19 | 20 | ```json 21 | { 22 | "id": 982237015, 23 | "date": "2018-07-03", 24 | "from": "07:30", 25 | "to": "13:15", 26 | "is_home_office": true, 27 | "user": { 28 | "id": 933590696, 29 | "firstname": "John", 30 | "lastname": "Doe" 31 | }, 32 | "created_at": "2018-10-17T09:33:46Z", 33 | "updated_at": "2018-10-17T09:33:46Z" 34 | } 35 | ``` 36 | 37 | ## GET /users/presences 38 | 39 | Retrieve all presences: 40 | 41 | ```bash 42 | curl -X GET \ 43 | 'https://{domain}.mocoapp.com/api/v1/users/presences?from=2018-06-01&to=2018-06-30' \ 44 | -H 'Authorization: Token token=YOUR_API_KEY' 45 | ``` 46 | 47 | This returns an array of all presences. 48 | 49 | The following parameters can be supplied: 50 | 51 | - [Global filters apply](../entities#global-filters) 52 | - **from, to** – "2018-06-01", "2018-06-30" (from and to have to be provided together) 53 | - **user_id** – 123 54 | - **is_home_office** – true/false 55 | 56 | ## GET /users/presences/{id} 57 | 58 | Retrieve a single presence: 59 | 60 | ```bash 61 | curl -X GET \ 62 | 'https://{domain}.mocoapp.com/api/v1/users/presences/{id}' \ 63 | -H 'Authorization: Token token=YOUR_API_KEY' 64 | ``` 65 | 66 | ## POST /users/presences 67 | 68 | Create a presence: 69 | 70 | Every presence is created for the user that the API key belongs to. 71 | 72 | ```bash 73 | curl -X POST \ 74 | 'https://{domain}.mocoapp.com/api/v1/users/presences' \ 75 | -H 'Authorization: Token token=YOUR_API_KEY' \ 76 | -H 'Content-Type: application/json' \ 77 | -d '{ 78 | "date": "2018-06-11", 79 | "from": "08:00", 80 | "to": "10:00" 81 | }' 82 | ``` 83 | 84 | Mandatory fields are marked with a star (\*): 85 | 86 | - **date\*** – "2018-06-11" 87 | - **from\*** – "08:00" 88 | - **to** – "12:30" (End time, can be left blank) 89 | - **is_home_office** – true/false (default: `false`, will set the whole day) 90 | 91 | ## POST /users/presences/touch 92 | 93 | This request creates a new presence and returns it for the user with the corresponding API-Key starting from the current time or terminates an existing open presence at the current time. Can be used to implement a time clock system (e.g. RFID). 94 | 95 | ```bash 96 | curl -X POST \ 97 | 'https://{domain}.mocoapp.com/api/v1/users/presences/touch' \ 98 | -H 'Authorization: Token token=YOUR_API_KEY' 99 | ``` 100 | 101 | A first request at 9:30 AM creates a presence with `from="09:30"`, a second request at 11:30 AM sets `to="11:30"` of the previous presence. 102 | 103 | {: .note } 104 | > There are two special situations to take into consideration: 105 | > 106 | > 1. If a presence is started and stopped by `touch` within the same minute, then it is discarded. 107 | > 2. If a `touch` conflicts with an existing presence, then the request is refused and the server response code 108 | is `423 Locked`. 109 | 110 | ```bash 111 | curl -X POST \ 112 | 'https://{domain}.mocoapp.com/api/v1/users/presences/touch' \ 113 | -H 'Authorization: Token token=YOUR_API_KEY' \ 114 | -H 'Content-Type: application/json' \ 115 | -d '{ 116 | "is_home_office": true, 117 | }' 118 | ``` 119 | 120 | Optional fields: 121 | 122 | - **is_home_office** – true/false (default: `false`, will set the whole day) 123 | - **override** – "2022-03-27 14:45" 124 | 125 | To prevent time differences during delays between systems, the parameter `override` can be passed with the time of the event in the format `YYYY-MM-DD HH:MM`. It has to be in 24h format and is timezone agnostic which means that MOCO stores the hour and minute in local time. 126 | 127 | ## PUT /users/presences/{id} 128 | 129 | Update a presence. 130 | 131 | ```bash 132 | curl -X PUT \ 133 | 'https://{domain}.mocoapp.com/api/v1/users/presences/{id}' \ 134 | -H 'Authorization: Token token=YOUR_API_KEY' \ 135 | -H 'Content-Type: application/json' \ 136 | -d '{ 137 | "to": "14:00" 138 | }' 139 | ``` 140 | 141 | All fields are analogous to the POST request. 142 | 143 | ## DELETE /users/presences/{id} 144 | 145 | Delete a presence. 146 | 147 | ```bash 148 | curl -X DELETE \ 149 | 'https://{domain}.mocoapp.com/api/v1/users/presences/{id}' \ 150 | -H 'Authorization: Token token=YOUR_API_KEY' 151 | ``` 152 | -------------------------------------------------------------------------------- /sections/comments.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: default 3 | parent: Entities 4 | --- 5 | 6 | # Comments 7 | 8 | German: "Notizen" 9 | 10 | - TOC 11 | {:toc} 12 | 13 | ## Attributes 14 | 15 | The representation contains, among the standard fields, also: 16 | 17 | - user (creator) 18 | 19 | ```json 20 | { 21 | "id": 123, 22 | "commentable_id": 12345, 23 | "commentable_type": "Project", 24 | "text": "
Project was ordered on 1.10.2017
.", 25 | "manual": true, 26 | "user": { 27 | "id": 567, 28 | "firstname": "Tobias", 29 | "lastname": "Miesel" 30 | }, 31 | "created_at": "2018-10-17T09:33:46Z", 32 | "updated_at": "2018-10-17T09:33:46Z" 33 | } 34 | ``` 35 | 36 | The text must be "plain text" or valid HTML. MOCO removes all HTML-tags, except for `['div', 'strong', 'em', 'u', 'pre', 'ul', 'ol', 'li', 'br']`. 37 | 38 | ## GET /comments 39 | 40 | Retrieve all comments 41 | 42 | ```bash 43 | curl -X GET \ 44 | 'https://{domain}.mocoapp.com/api/v1/comments' \ 45 | -H 'Authorization: Token token=YOUR_API_KEY' 46 | ``` 47 | 48 | This returns complete comment information (see Attributes). 49 | 50 | Additionally, the following parameters can be supplied: 51 | 52 | - [Global filters apply](../entities#global-filters) 53 | - **commentable_type** – "Company", "Contact", "Deal", "DeiveryNote", "Expense", "Invoice", "InvoiceBookkeepingExport", "InvoiceDeletion", "InvoiceReminder", "Offer", "OfferConfirmation", "Project", "ProjectGroup", "Purchase", "PurchaseBookkeepingExport", "PurchaseDraft", "Receipt", "ReceiptRefundRequest", "RecurringExpense", "Unit", "User", "UserHolidayRequest" (object this comment relates to) 54 | - **commentable_id** – 123 (object ID) 55 | - **user_id** – 456 (creator user ID) 56 | - **manual** – true/false (user-created or generated) 57 | 58 | ## GET /comments/{id} 59 | 60 | Retrieve a single comment: 61 | 62 | ```bash 63 | curl -X GET \ 64 | 'https://{domain}.mocoapp.com/api/v1/comments/{id}' \ 65 | -H 'Authorization: Token token=YOUR_API_KEY' 66 | ``` 67 | 68 | This returns a single comment representation. 69 | 70 | ## POST /comments 71 | 72 | Create a comment: 73 | 74 | ```bash 75 | curl -X POST \ 76 | 'https://{domain}.mocoapp.com/api/v1/comments' \ 77 | -H 'Authorization: Token token=YOUR_API_KEY' \ 78 | -H 'Content-Type: application/json' \ 79 | -d '{ 80 | "commentable_id": 123, 81 | "commentable_type": "Project", 82 | "text": "
Project was ordered on 1.10.2017
." 83 | }' 84 | ``` 85 | 86 | Mandatory fields are marked with a star (\*): 87 | 88 | - **commentable_id\*** – 123 (object ID) 89 | - **commentable_type\*** – ""Contact", "Deal", "DeliveryNote", "Project", "User", "Unit", "Company", "Offer", "OfferConfirmation", "Invoice", "InvoiceReminder", "InvoiceDeletion", "InvoiceBookkeepingExport", "Expense", "RecurringExpense", "Receipt", "ReceiptRefundRequest", "Purchase", "PurchaseBookkeepingExport", "PurchaseDraft" (object type) 90 | - **text\*** – "Comment text..." 91 | - **attachment_filename** – "document.pdf" 92 | - **attachment_content** – _the file as a base64-encoded string_ 93 | - **created_at** – _when migrating data, pass this in the format `2018-05-09T05:40:06`_ 94 | 95 | ## POST /comments/bulk 96 | 97 | Create multiple comments in bulk: 98 | 99 | ```bash 100 | curl -X POST \ 101 | 'https://{domain}.mocoapp.com/api/v1/comments/bulk' \ 102 | -H 'Authorization: Token token=YOUR_API_KEY' \ 103 | -H 'Content-Type: application/json' \ 104 | -d '{ 105 | "commentable_ids": [123, 234, 345], 106 | "commentable_type": "Contact", 107 | "text": "Sent Newsletter RJ-2019/03" 108 | }' 109 | ``` 110 | 111 | Mandatory fields are marked with a star (\*): 112 | 113 | - **commentable_ids\*** – [123, 234, ...] (object IDs) 114 | 115 | Other fields are analogous to the POST request. 116 | 117 | ## PUT /comments/{id} 118 | 119 | Update a comment: 120 | 121 | ```bash 122 | curl -X PUT \ 123 | 'https://{domain}.mocoapp.com/api/v1/comments/{id}' \ 124 | -H 'Authorization: Token token=YOUR_API_KEY' \ 125 | -H 'Content-Type: application/json' \ 126 | -d '{ 127 | "text": "
Project is paused for now.
.", 128 | }' 129 | ``` 130 | 131 | Fields are analogous to the POST request. 132 | 133 | ## DELETE /comments/{id} 134 | 135 | Deleting manually created comments: 136 | 137 | ```bash 138 | curl -X DELETE \ 139 | 'https://{domain}.mocoapp.com/api/v1/comments/{id}' \ 140 | -H 'Authorization: Token token=YOUR_API_KEY' 141 | ``` 142 | -------------------------------------------------------------------------------- /sections/reports.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: default 3 | parent: Entities 4 | --- 5 | 6 | # Reports 7 | 8 | German: "Berichte" 9 | 10 | - TOC 11 | {:toc} 12 | 13 | ## GET /report/absences 14 | 15 | Retrieve a list of absences per user: 16 | 17 | ```bash 18 | curl -X GET \ 19 | 'https://{domain}.mocoapp.com/api/v1/report/absences' \ 20 | -H 'Authorization: Token token=YOUR_API_KEY' 21 | ``` 22 | 23 | It's also possible to filter: 24 | 25 | - **active** - true/false (include only absences for active users, defaults to false) 26 | - **year** - 2021 (defaults to current year) 27 | 28 | This returns an array with the following structure: 29 | 30 | ```json 31 | [ 32 | { 33 | "user": { 34 | "id": 123, 35 | "firstname": "Jane", 36 | "lastname": "Doe" 37 | }, 38 | "total_vacation_days": 25.0, 39 | "used_vacation_days": 10.5, 40 | "planned_vacation_days": 5.0, 41 | "sickdays": 4.0 42 | } 43 | ] 44 | ``` 45 | 46 | ## GET /report/cashflow 47 | 48 | Retrieve the cashflow report: 49 | 50 | ```bash 51 | curl -X GET \ 52 | 'https://{domain}.mocoapp.com/api/v1/report/cashflow' \ 53 | -H 'Authorization: Token token=YOUR_API_KEY' 54 | ``` 55 | 56 | It's possible to filter: 57 | 58 | - **from** - 2025-01-01 59 | - **to** - 2025-12-31 60 | - **term** - text 61 | 62 | 63 | This returns an array with the following structure: 64 | 65 | ```json 66 | [ 67 | { 68 | "record_id": 28206351, 69 | "company_id": 760383472, 70 | "description": "R2212-022 Invoice", 71 | "user_id": 933622946, 72 | "amount_in_account_currency": 1022.07, 73 | "kind": "invoice_created", 74 | "company": { 75 | "id": 760683172, 76 | "name": "Kronenhalle Bar" 77 | }, 78 | "user": { 79 | "id": 933622946, 80 | "firstname": "John", 81 | "lastname": "Doe" 82 | }, 83 | "date": "2024-09-17" 84 | } 85 | ] 86 | ``` 87 | 88 | ## GET /report/finance 89 | 90 | Retrieve the finance report: 91 | 92 | ```bash 93 | curl -X GET \ 94 | 'https://{domain}.mocoapp.com/api/v1/report/finance' \ 95 | -H 'Authorization: Token token=YOUR_API_KEY' 96 | ``` 97 | 98 | It's possible to filter: 99 | 100 | - **from** - 2025-01-01 101 | - **to** - 2025-12-31 102 | - **term** - text 103 | 104 | 105 | This returns an array with the following structure: 106 | 107 | ```json 108 | [ 109 | { 110 | "record_id": 3731655, 111 | "company_id": 760718470, 112 | "description":"ZL 1", 113 | "user_id": 933621267, 114 | "net_amount_in_account_currency": 100.0, 115 | "kind": "incoming_expenses", 116 | "company": { 117 | "id": 762768470, 118 | "name":"Maus AG" 119 | }, 120 | "user": { 121 | "id":933621267, 122 | "firstname": "Jenni", 123 | "lastname": "Doe" 124 | }, 125 | "date":"2025-03-27" 126 | } 127 | ] 128 | ``` 129 | 130 | ## GET /report/utilization 131 | 132 | Retrieve the utilization report: 133 | 134 | ```bash 135 | curl -X GET \ 136 | 'https://{domain}.mocoapp.com/api/v1/report/utilization?from={from_date}&to={to_date}' \ 137 | -H 'Authorization: Token token=YOUR_API_KEY' 138 | ``` 139 | 140 | The parameters `from` and `to` are required: 141 | 142 | - **from** - 2025-01-01 143 | - **to** - 2025-12-31 144 | 145 | ```json 146 | [ 147 | { 148 | "date": "2025-08-20", 149 | "user_id": 92345, 150 | "target_hours": 6.4, 151 | "billable_hours": 4.3, 152 | "unbillable_hours": 0.83, 153 | "billable_seconds": 15487, 154 | "unbillable_seconds": 3000 155 | }, 156 | { 157 | "date": "2025-08-21", 158 | "user_id": 92345, 159 | "target_hours": 6.4, 160 | "billable_hours": 2.0, 161 | "unbillable_hours": 3.83, 162 | "billable_seconds": 7200, 163 | "unbillable_seconds": 13800 164 | }, 165 | { 166 | "date": "2025-08-22", 167 | "user_id": 92345, 168 | "target_hours": 6.4, 169 | "billable_hours": 3.33, 170 | "unbillable_hours": 3.5, 171 | "billable_seconds": 12000, 172 | "unbillable_seconds": 12600 173 | }, 174 | { 175 | "date": "2025-08-20", 176 | "user_id": 93346, 177 | "target_hours": 8.0, 178 | "billable_hours": 0.0, 179 | "unbillable_hours": 0.0, 180 | "billable_seconds": 0.0, 181 | "unbillable_seconds": 0.0 182 | }, 183 | { 184 | "date": "2025-08-21", 185 | "user_id": 93346, 186 | "target_hours": 4.0, 187 | "billable_hours": 0.0, 188 | "unbillable_hours": 0.0, 189 | "billable_seconds": 0.0, 190 | "unbillable_seconds": 0.0 191 | }, 192 | { 193 | "date": "2025-08-22", 194 | "user_id": 93346, 195 | "target_hours": 8.0, 196 | "billable_hours": 0.0, 197 | "unbillable_hours": 0.25, 198 | "billable_seconds": 0, 199 | "unbillable_seconds": 900 200 | } 201 | ] 202 | ``` 203 | -------------------------------------------------------------------------------- /sections/receipts.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: default 3 | parent: Entities 4 | --- 5 | 6 | # Receipts 7 | 8 | German: "Spesen" 9 | 10 | - TOC 11 | {:toc} 12 | 13 | ## Attributes 14 | 15 | Includes among the standard fields for receipts also: 16 | 17 | - User 18 | - Items (with vat code, project, refund request and purchase category info) 19 | 20 | ```json 21 | { 22 | "id": 123, 23 | "title": "Team-Lunch", 24 | "date": "2021-12-13", 25 | "billable": false, 26 | "pending": false, 27 | "gross_total": 56.5, 28 | "currency": "CHF", 29 | "items": [ 30 | { 31 | "gross_total": 56.5, 32 | "vat": { 33 | "id": 186, 34 | "tax": 7.7, 35 | "reverse_charge": false, 36 | "intra_eu": false 37 | }, 38 | "purchase_category": { 39 | "id": 2684, 40 | "name": "Bewirtungsaufwände" 41 | } 42 | } 43 | ], 44 | "project": { 45 | "id": 567, 46 | "name": "Intern/Admin", 47 | "billable": false, 48 | "company": { 49 | "id": 789, 50 | "name": "Acme Inc." 51 | } 52 | }, 53 | "refund_request": { 54 | "id": 266, 55 | "status": "paid" 56 | }, 57 | "info": "Teamlunch mit Peter, Sandra und Till", 58 | "user": { 59 | "id": 933, 60 | "firstname": "Sabine", 61 | "lastname": "Schäuble" 62 | }, 63 | "attachment_url": "/system/documents/account/123/document/123/d8fef77df35c5753.pdf" 64 | } 65 | ``` 66 | 67 | ## GET /receipts 68 | 69 | Retrieve all receipts: 70 | 71 | ```bash 72 | curl -X GET \ 73 | 'https://{domain}.mocoapp.com/api/v1/receipts' \ 74 | -H 'Authorization: Token token=YOUR_API_KEY' 75 | ``` 76 | 77 | It's also possible to filter: 78 | 79 | - [Global filters apply](../entities#global-filters) 80 | - **from** – "2021-06-01" 81 | - **to** – "2021-06-30" 82 | - **project_id** – 567 (Project ID) 83 | - **user_id** – 933 (User ID) 84 | - **purchase_category_id** – 2684 (Purchase Category ID) 85 | - **refund_request_id** – 123,456 (Refund Request IDs) 86 | - **submitted** – true/false (refund request created) 87 | 88 | Returns an array with all receipt information (see attributes). 89 | 90 | ## GET /receipts/{id} 91 | 92 | Retrieve a single receipt: 93 | 94 | ```bash 95 | curl -X GET \ 96 | 'https://{domain}.mocoapp.com/api/v1/receipts/{id}' \ 97 | -H 'Authorization: Token token=YOUR_API_KEY' 98 | ``` 99 | 100 | Returns the representation for a single receipt. 101 | 102 | ## POST /receipts 103 | 104 | Create a receipt: 105 | 106 | ```bash 107 | curl -X POST \ 108 | 'https://{domain}.mocoapp.com/api/v1/receipts' \ 109 | -H 'Authorization: Token token=YOUR_API_KEY' \ 110 | -H 'Content-Type: application/json' \ 111 | -d ' 112 | { 113 | "date": "2020-02-02", 114 | "title": "Lunch with coworkers", 115 | "currency": "CHF", 116 | "items": [ 117 | { 118 | "vat_code_id": 186, 119 | "gross_total": 99.90 120 | } 121 | ], 122 | "project_id": 123, 123 | "attachment": { 124 | "filename": "document.pdf", 125 | "base64": "JVBERi0xLjQKJeLjz9MKNCAwIG9iago8PC9GaWx..." 126 | } 127 | }' 128 | ``` 129 | 130 | Mandatory fields are marked with a star (\*): 131 | 132 | - **date\*** – "2020-02-02" 133 | - **title\*** – "Lunch with coworkers" 134 | - **currency\*** - "CHF" 135 | - **items\*** – list of positions. At least one position must be present and every position has the following fields: 136 | - **vat_code_id\*** – 186 (Vat Code ID) 137 | - **gross_total\*** – 99.90 138 | - **purchase_category_id** – 123 (Purchase Category ID, currently has to be **the same** for all items) 139 | - **project_id** – 123 (Project ID) 140 | - **info** – free text 141 | - **billable** – true/false 142 | - **attachment** – file attached to the purchase, with the following fields: 143 | - **filename** – "document.pdf" 144 | - **base64** – base64 encoded content of the file 145 | 146 | ## PATCH /receipts/{id} 147 | 148 | Update a receipt: 149 | 150 | ```bash 151 | curl -X POST \ 152 | 'https://{domain}.mocoapp.com/api/v1/receipts/{id}' \ 153 | -H 'Authorization: Token token=YOUR_API_KEY' \ 154 | -H 'Content-Type: application/json' \ 155 | -d ' 156 | { 157 | "date": "2020-02-02", 158 | "title": "Lunch with customer", 159 | "currency": "CHF", 160 | "items": [ 161 | { 162 | "vat_code_id": 186, 163 | "gross_total": 109.90 164 | } 165 | ], 166 | "attachment": { 167 | "filename": "document.pdf", 168 | "base64": "JVBERi0xLjQKJeLjz9MKNCAwIG9iago8PC9GaWx..." 169 | } 170 | }' 171 | ``` 172 | 173 | Fields are similar to the create action. 174 | 175 | {: .warning } 176 | If provided, the field `items` will overwrite any existing items and has therefore to be provided entirely. 177 | 178 | ## DELETE /receipts/{id} 179 | 180 | {: .note } 181 | It's only possible to delete a receipt until no _refund_request_ has been created (receipt has not been requested for refund). 182 | 183 | ```bash 184 | curl -X DELETE \ 185 | 'https://{domain}.mocoapp.com/api/v1/receipts/{id}' \ 186 | -H 'Authorization: Token token=YOUR_API_KEY' 187 | ``` 188 | -------------------------------------------------------------------------------- /sections/project_recurring_expenses.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: default 3 | parent: Projects 4 | grand_parent: Entities 5 | --- 6 | 7 | # Project Recurring Expenses 8 | 9 | German: "Projekte / Wiederkehrende Zusatzleistungen" 10 | 11 | - TOC 12 | {:toc} 13 | 14 | ## Attributes 15 | 16 | The representation contains, among the standard fields, also: 17 | 18 | - Custom properties 19 | - Project 20 | 21 | ```json 22 | { 23 | "id": 47266, 24 | "start_date": "2017-07-01", 25 | "finish_date": "2017-12-31", 26 | "recur_next_date": "2017-09-01", 27 | "period": "monthly", 28 | "title": "Hosting XS", 29 | "description": "
Hosting, Monitoring und Backup
", 30 | "quantity": 1, 31 | "unit": "Server", 32 | "unit_price": 29, 33 | "unit_cost": 19, 34 | "price": 29, 35 | "cost": 19, 36 | "currency": "CHF", 37 | "budget_relevant": true, 38 | "billable": true, 39 | "service_period_direction": "forward", 40 | "custom_properties": { 41 | "Type": "Website" 42 | }, 43 | "project": { 44 | "id": 1234, 45 | "name": "Project A" 46 | }, 47 | "revenue_category": { 48 | "id": 124, 49 | "name": "Hosting", 50 | "revenue_account": 30056, 51 | "cost_category": "HO1" 52 | }, 53 | "created_at": "2018-10-17T09:33:46Z", 54 | "updated_at": "2018-10-17T09:33:46Z" 55 | } 56 | ``` 57 | 58 | ## GET /recurring_expenses 59 | 60 | Retrieve all recurring additional services entries, or all the recurring additional service entries on a project: 61 | 62 | ```bash 63 | curl -X GET \ 64 | 'https://{domain}.mocoapp.com/api/v1/recurring_expenses' \ 65 | -H 'Authorization: Token token=YOUR_API_KEY' 66 | ``` 67 | 68 | This returns an array of recurring additional services entries (see Attributes). 69 | 70 | It's also possible to filter: 71 | 72 | - [Global filters apply](../entities#global-filters) 73 | 74 | ## GET /projects/{id}/recurring_expenses 75 | 76 | ```bash 77 | curl -X GET \ 78 | 'https://{domain}.mocoapp.com/api/v1/projects/{id}/recurring_expenses' \ 79 | -H 'Authorization: Token token=YOUR_API_KEY' 80 | ``` 81 | 82 | This returns an array of recurring additional services entries for the project (see Attributes). 83 | 84 | ## GET /projects/{id}/recurring_expenses/{id} 85 | 86 | Retrieve a single recurring additional services entry on a project: 87 | 88 | ```bash 89 | curl -X GET \ 90 | 'https://{domain}.mocoapp.com/api/v1/projects/{id}/recurring_expenses/{id}' \ 91 | -H 'Authorization: Token token=YOUR_API_KEY' 92 | ``` 93 | 94 | ## POST /projects/{id}/recurring_expenses 95 | 96 | Create a recurring additional services entry on a project: 97 | 98 | ```bash 99 | curl -X POST \ 100 | 'https://{domain}.mocoapp.com/api/v1/projects/{id}/recurring_expenses' \ 101 | -H 'Authorization: Token token=YOUR_API_KEY' \ 102 | -H 'Content-Type: application/json' \ 103 | -d '{ 104 | "start_date": "2018-10-01", 105 | "period": "monthly", 106 | "service_period_direction": "forward", 107 | "title": "Hosting XS", 108 | "quantity": 1, 109 | "unit": "Server", 110 | "unit_price": 29, 111 | "unit_cost": 19 112 | }' 113 | ``` 114 | 115 | Mandatory fields are marked with a star (\*): 116 | 117 | - **start_date\*** – "2018-07-01" 118 | - **period\*** – "weekly", "biweekly", "monthly", "quarterly", "biannual" or "annual" 119 | - **title\*** – "Hosting XS" 120 | - **quantity\*** – 1 121 | - **unit\*** – "Server" 122 | - **unit_price\*** – 29 123 | - **unit_cost\*** – 19 124 | - **finish_date** – "2018-12-31" (if empty: unlimited) 125 | - **description** – "Hosting, Monitoring, Backup" 126 | - **billable** – true/false (default: true) 127 | - **budget_relevant** – true/false (default: false) 128 | - **service_period_direction** – "none", "forward", "backward" (default: "none") 129 | - **custom_properties** – {"Type": "Website"} 130 | 131 | ## PUT /projects/{id}/recurring_expenses/{id} 132 | 133 | Update a recurring additional services entry on a project: 134 | 135 | ```bash 136 | curl -X PUT \ 137 | 'https://{domain}.mocoapp.com/api/v1/projects/{id}/recurring_expenses/{id}' \ 138 | -H 'Authorization: Token token=YOUR_API_KEY' \ 139 | -H 'Content-Type: application/json' \ 140 | -d '{ 141 | "unit_price": 49, 142 | }' 143 | ``` 144 | The fields are analogous to the POST request, except for `start_date` and `period`. These fields cannot be modified after creation. 145 | 146 | ## POST /projects/{id}/recurring_expenses/{id}/recur 147 | 148 | Creates an additional service entry on a project ahead of schedule. 149 | 150 | For an active recurring additional service, MOCO automatically creates the corresponding additional expense on the next recurrence date. 151 | Using the `recur` endpoint, you can trigger this creation process manually — before the automatic generation occurs. 152 | This also advances the `recur_next_date` by the defined `period`. 153 | 154 | ```bash 155 | curl -X POST \ 156 | 'https://{domain}.mocoapp.com/api/v1/projects/{id}/recurring_expenses/{id}/recur' \ 157 | -H 'Authorization: Token token=YOUR_API_KEY' \ 158 | ``` 159 | 160 | ## DELETE /projects/{id}/recurring_expenses/{id} 161 | 162 | ```bash 163 | curl -X DELETE \ 164 | 'https://{domain}.mocoapp.com/api/v1/projects/{id}/recurring_expenses/{id}' \ 165 | -H 'Authorization: Token token=YOUR_API_KEY' 166 | ``` 167 | -------------------------------------------------------------------------------- /sections/companies.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: default 3 | parent: Entities 4 | --- 5 | 6 | # Companies 7 | 8 | German: "Firmen" 9 | 10 | - TOC 11 | {:toc} 12 | 13 | ## Attributes 14 | 15 | The company representation contains among default fields the following features: 16 | 17 | - Type ("customer", "supplier", "organization") 18 | - Tags 19 | - Custom properties 20 | - Projects (shortened) 21 | - User (shortened) 22 | - billing_vat ("tax", "reverse_charge", "intra_eu" (intra community trade, only applicable for accounts in the EU)) 23 | 24 | ```json 25 | { 26 | "id": 760253573, 27 | "type": "customer", 28 | "name": "Beispiel AG", 29 | "website": "www.beispiel-ag.com", 30 | "email": "info@beispiel-ag.com", 31 | "billing_email_cc": "cc@beispiel-ag.com", 32 | "phone": "+49 30 123 45 67", 33 | "fax": "+49 30 123 45 66", 34 | "address": "Beispiel AG\nBeispielstrasse 123\n12345 Beispielstadt", 35 | "tags": ["Netzwerk", "Druckerei"], 36 | "user": { 37 | "id": 933589840, 38 | "firstname": "Tobias", 39 | "lastname": "Miesel" 40 | }, 41 | "info": "", 42 | "custom_properties": { 43 | "UID": "1234-UID-4567" 44 | }, 45 | "identifier": "36", 46 | "intern": false, 47 | "billing_tax": 0, 48 | "customer_vat": { "tax": 0.0, "reverse_charge": true, "intra_eu": true, "active": true, "print_gross_total": true, "notice_tax_exemption": "", "notice_tax_exemption_alt": "" }, // for customers only 49 | "supplier_vat": { "tax": 0.0, "reverse_charge": true, "intra_eu": true, "active": true }, // for suppliers only 50 | "currency": "CHF", 51 | "custom_rates": false, 52 | "include_time_report": false, 53 | "billing_notes": "Vor Rechnungsstellung PO beantragen.", 54 | "default_discount": 0.0, 55 | "default_cash_discount": 2.0, 56 | "default_cash_discount_days": 10, 57 | "country_code": "CH", 58 | "vat_identifier": "CH999999999", 59 | "alternative_correspondence_language": false, 60 | "default_invoice_due_days": 30, 61 | "footer": "
Footer text
", 62 | "projects": [ 63 | { 64 | "id": 944504145, 65 | "identifier": "46", 66 | "name": "Layoutanpassung", 67 | "active": false, 68 | "billable": true 69 | } 70 | ], 71 | "created_at": "2018-10-17T09:33:46Z", 72 | "updated_at": "2018-10-17T09:33:46Z", 73 | "debit_number": 10000 74 | } 75 | ``` 76 | 77 | ## GET /companies 78 | 79 | Retrieve all companies: 80 | 81 | ```bash 82 | curl -X GET \ 83 | 'https://{domain}.mocoapp.com/api/v1/companies' \ 84 | -H 'Authorization: Token token=YOUR_API_KEY' 85 | ``` 86 | 87 | It's also possible to filter: 88 | 89 | {: .note } 90 | To filter by custom properties, you have to supply the `type` parameter. 91 | 92 | - [Global filters apply](../entities#global-filters) 93 | - **type** ("customer", "supplier", "organization") 94 | - **tags** "Automotive, Pharma" (comma separated list) 95 | - **identifier** "K0405" 96 | - **term** "acme corp" (search term) 97 | 98 | This returns an array with the complete company information. 99 | 100 | ## GET /companies/{id} 101 | 102 | Retrieve a single company: 103 | 104 | ```bash 105 | curl -X GET \ 106 | 'https://{domain}.mocoapp.com/api/v1/companies/123' \ 107 | -H 'Authorization: Token token=YOUR_API_KEY' 108 | ``` 109 | 110 | This returns a single company's complete represenation. 111 | 112 | ## POST /companies 113 | 114 | Create a company: 115 | 116 | ```bash 117 | curl -X POST \ 118 | 'https://{domain}.mocoapp.com/api/v1/companies' \ 119 | -H 'Authorization: Token token=YOUR_API_KEY' \ 120 | -H 'Content-Type: application/json' \ 121 | -d '{ 122 | "name": "Beispiel AG", 123 | "currency": "EUR" 124 | }' 125 | ``` 126 | 127 | Fields for all types of companies. Mandatory fields are marked with a star (\*): 128 | 129 | - **name\*** – "Beispiel AG" 130 | - **type\*** – ("customer", "supplier", "organization") 131 | - **country_code** – (ISO Alpha-2 Country Code like "DE" / "CH" / "AT" in upper case - default is account country) 132 | - **vat_identifier** – European Union VAT identification numbers (USt-IdNr) 133 | - **alternative_correspondence_language** – true/false (create sales documents in the account alternative language) 134 | - **website** – "http//www.lieferant.com" 135 | - **fax** – "+49 30 123 45 67" 136 | - **phone** – "+49 30 123 45 67" 137 | - **email** – "bestellung@lieferant.de" 138 | - **billing_email_cc** - "cc@lieferant.de" 139 | - **billing_notes** - "Rechnung mit Stundenauszug schicken" 140 | - **address** – "Lieferant AG\nBeispielstrasse 123\n12345 Berlin" 141 | - **info** – "Information for this company..." 142 | - **custom_properties** – {"UID": "123-UID-456"} 143 | - **tags** – ["Network", "Print"] 144 | - **user_id** – 123456 💡(responsible person) 145 | - **footer** – "
some html
" (appears at the end of invoices) 146 | 147 | Additional fields just for companies of type customer: 148 | 149 | - **currency\*** – "EUR" 150 | - **identifier\*** – "K-123" (only mandatory if not automatically assigned) 151 | - **customer_tax** – 19.0 152 | - **default_invoice_due_days** – 20 (use **invoice_due_days** to set a value for a company) 153 | - **debit_number** – 10000 if bookkeeping is enabled 154 | 155 | Additional fields just for companies of type supplier: 156 | 157 | - **bank_owner** – name of the account holder (if deviating from the supplier name) 158 | - **iban** – CH3908704016075473007 159 | - **bank_bic** – POFICHBEXXX 160 | - **supplier_tax** – 19.0 161 | - **default_invoice_due_days** – 20 (use **invoice_due_days** to set a value for a company) 162 | - **credit_number** – 70000 if bookkeeping is enabled 163 | 164 | ## PUT /companies/{id} 165 | 166 | Update a company. 167 | 168 | ```bash 169 | curl -X PUT \ 170 | 'https://{domain}.mocoapp.com/api/v1/companies/{123}' \ 171 | -H 'Authorization: Token token=YOUR_API_KEY' \ 172 | -H 'Content-Type: application/json' \ 173 | -d '{ 174 | "name": "Beispiel GmbH" 175 | }' 176 | ``` 177 | 178 | Fields are analogous to the POST request. 179 | 180 | ## DELETE /companies/{id} 181 | 182 | ```bash 183 | curl -X DELETE \ 184 | 'https://{domain}.mocoapp.com/api/v1/companies/{123}' \ 185 | -H 'Authorization: Token token=YOUR_API_KEY' 186 | ``` 187 | -------------------------------------------------------------------------------- /sections/account/catalog_services.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: default 3 | title: Catalog Services 4 | parent: Account 5 | grand_parent: Entities 6 | --- 7 | 8 | # Catalog Services 9 | 10 | German: "Leistungskatalog" 11 | 12 | - TOC 13 | {:toc} 14 | 15 | ## Attributes 16 | 17 | Item attributes: 18 | 19 | - **type** `title` / `description` / `item` / `page-break` / `subtotal` / `separator` - position type 20 | - **description** (`description` type only) 21 | - **quantity** can be 0 for all-inclusive item (detailed `item` type only) 22 | - **unit** only used for detailed `item` type, could be e.g. "hours" or "pieces", (detailed `item` type only) 23 | - **unit_price** price for a single unit (detailed `item` type only) 24 | - **net_total** total price for this position (`item` type only) 25 | - **unit_cost** internal cost for 1 unit (`item` type only) 26 | - **optional** optional position (`item` type only) 27 | - **part** `subtotal` type only, part "true" means subtotal to the upper `title`, "false" means for the whole document 28 | - **additional** mark as additional service 29 | 30 | ```json 31 | { 32 | "id": 20370, 33 | "title": "Catalog entry", 34 | "items": [ 35 | { 36 | "id": 113400, 37 | "type": "item", 38 | "title": "Setup", 39 | "description": null, 40 | "quantity": 0.0, 41 | "unit": null, 42 | "unit_price": 0.0, 43 | "net_total": 1200.0, 44 | "unit_cost": 0.0, 45 | "optional": false, 46 | "part": false, 47 | "additional": false, 48 | "revenue_category": { 49 | "id": 124, 50 | "name": "Hosting", 51 | "revenue_account": 30056, 52 | "cost_category": "HO1" 53 | }, 54 | "created_at": "2022-06-16T12:24:30Z", 55 | "updated_at": "2022-06-16T12:24:30Z" 56 | }, 57 | { 58 | "id": 76675, 59 | "type": "item", 60 | "title": "Consulting", 61 | "description": null, 62 | "quantity": 20.0, 63 | "unit": "h", 64 | "unit_price": 150.0, 65 | "net_total": 3000.0, 66 | "unit_cost": 0.0, 67 | "optional": false, 68 | "part": false, 69 | "additional": false, 70 | "revenue_category": { 71 | "id": 127, 72 | "name": "Consulting", 73 | "revenue_account": 30059, 74 | "cost_category": "CO1" 75 | }, 76 | "created_at": "2022-06-16T12:24:30Z", 77 | "updated_at": "2022-06-16T12:24:30Z" 78 | } 79 | ], 80 | "created_at": "2022-06-16T12:24:30Z", 81 | "updated_at": "2022-06-16T12:24:30Z" 82 | } 83 | ``` 84 | 85 | ## GET /account/catalog_services 86 | 87 | Retrieve catalog services: 88 | 89 | ```bash 90 | curl -X GET \ 91 | 'https://{domain}.mocoapp.com/api/v1/account/catalog_services' \ 92 | -H 'Authorization: Token token=YOUR_API_KEY' 93 | ``` 94 | 95 | returns an array of catalog services including their items. 96 | 97 | Additionally, the following parameters can be supplied: 98 | 99 | - [Global filters apply](../../entities#global-filters) 100 | 101 | ## GET /account/catalog_services/{id} 102 | 103 | Retrieve catalog services: 104 | 105 | ```bash 106 | curl -X GET \ 107 | 'https://{domain}.mocoapp.com/api/v1/account/catalog_services/{id}' \ 108 | -H 'Authorization: Token token=YOUR_API_KEY' 109 | ``` 110 | 111 | returns a single catalog service. 112 | 113 | ## POST /account/catalog_services 114 | 115 | Create a catalog service including their items 116 | 117 | ```bash 118 | curl -X POST \ 119 | 'https://{domain}.mocoapp.com/api/v1/account/catalog_services' \ 120 | -H 'Authorization: Token token=YOUR_API_KEY' 121 | -H 'Content-Type: application/json' \ 122 | -d '{ 123 | "title": "Catalog entry", 124 | "items": [ 125 | { 126 | "type": "item", 127 | "title": "Setup", 128 | "net_total": 1200.0 129 | }, 130 | { 131 | "type": "item", 132 | "title": "Consulting", 133 | "quantity": 20.0, 134 | "unit": "h", 135 | "unit_price": 150.0, 136 | "net_total": 3000.0 137 | } 138 | ] 139 | }' 140 | ``` 141 | 142 | ## PUT /account/catalog_services/{id} 143 | 144 | Update a catalog service: 145 | 146 | ```bash 147 | curl -X PUT \ 148 | 'https://{domain}.mocoapp.com/api/v1/account/catalog_services/{id}' \ 149 | -H 'Authorization: Token token=YOUR_API_KEY' 150 | -H 'Content-Type: application/json' \ 151 | -d '{ 152 | "title": "Catalog entry" 153 | }' 154 | ``` 155 | 156 | The items cannot be updated this way, use the separate endpoints for this. 157 | 158 | ## DELETE /account/catalog_services/{id} 159 | 160 | Delete a catalog service: 161 | 162 | ```bash 163 | curl -X DELETE \ 164 | 'https://{domain}.mocoapp.com/api/v1/account/catalog_services/{id}' \ 165 | -H 'Authorization: Token token=YOUR_API_KEY' 166 | ``` 167 | 168 | ## GET /account/catalog_services/{service_id}/items/{id} 169 | 170 | Get an item within a service: 171 | 172 | ```bash 173 | curl -X GET \ 174 | 'https://{domain}.mocoapp.com/api/v1/account/catalog_services/{service_id}/items/{id}' \ 175 | -H 'Authorization: Token token=YOUR_API_KEY' 176 | ``` 177 | 178 | ## POST /account/catalog_services/{service_id}/items 179 | 180 | Create a new item within a service: 181 | 182 | ```bash 183 | curl -X POST \ 184 | 'https://{domain}.mocoapp.com/api/v1/account/catalog_services/{service_id}/items' \ 185 | -H 'Authorization: Token token=YOUR_API_KEY' 186 | -H 'Content-Type: application/json' \ 187 | -d '{ 188 | "type": "item", 189 | "title": "Consulting", 190 | "quantity": 20.0, 191 | "unit": "h", 192 | "unit_price": 150.0, 193 | "net_total": 3000.0 194 | }' 195 | ``` 196 | 197 | ## PUT /account/catalog_services/{service_id}/items/{id} 198 | 199 | Update an item: 200 | 201 | ```bash 202 | curl -X PUT \ 203 | 'https://{domain}.mocoapp.com/api/v1/account/catalog_services/{service_id}/items/{id}' \ 204 | -H 'Authorization: Token token=YOUR_API_KEY' 205 | -H 'Content-Type: application/json' \ 206 | -d '{ 207 | "type": "item", 208 | "title": "Consulting", 209 | "quantity": 20.0, 210 | "unit": "h", 211 | "unit_price": 150.0, 212 | "net_total": 3000.0 213 | }' 214 | ``` 215 | 216 | ## DELETE /account/catalog_services/{service_id}/items/{id} 217 | 218 | Delete an item: 219 | 220 | ```bash 221 | curl -X DELETE \ 222 | 'https://{domain}.mocoapp.com/api/v1/account/catalog_services/{service_id}/items/{id}' \ 223 | -H 'Authorization: Token token=YOUR_API_KEY' 224 | ``` 225 | -------------------------------------------------------------------------------- /sections/activities.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: default 3 | parent: Entities 4 | --- 5 | 6 | # Activities 7 | 8 | German: "Zeiteinträge" 9 | 10 | - TOC 11 | {:toc} 12 | 13 | ## Attributes 14 | 15 | Activities contain among the standard fields also: 16 | 17 | - Project 18 | - Customer 19 | - Task (on the project) 20 | - User (creator) 21 | 22 | The attribute `seconds` are the billable seconds of the activity; the attribute `worked_seconds` are the seconds considered for the users' actual hours. 23 | 24 | Attributes `remote_service`, `remote_id` und `remote_url` are set by the MOCO Browser extension and represent a ticket in an external system (Trello, Jira, etc.) that this activity's time was spent on. 25 | `timer_started_at` is `null` for all activities and shows a timestamp if the timer is running on an activity. A timer can only be running on one activity at a time per user. 26 | 27 | ```json 28 | { 29 | "id": 982237015, 30 | "date": "2018-07-03", 31 | "hours": 1.25, 32 | "seconds": 4500, 33 | "worked_seconds": 4500, 34 | "description": "Analysis context and dependencies", 35 | "billed": false, 36 | "invoice_id": null, 37 | "billable": false, 38 | "tag": "", 39 | "remote_service": "trello", 40 | "remote_id": "9qzOS8AA", 41 | "remote_url": "https://trello.com/c/9qzOS8AA/123-analyse", 42 | "project": { 43 | "id": 944587499, 44 | "name": "Website Relaunch", 45 | "billable": false 46 | }, 47 | "task": { 48 | "id": 658636, 49 | "name": "Concept", 50 | "billable": false 51 | }, 52 | "customer": { 53 | "id": 760253684, 54 | "name": "Example Inc." 55 | }, 56 | "user": { 57 | "id": 933590696, 58 | "firstname": "John", 59 | "lastname": "Doe" 60 | }, 61 | "hourly_rate": 150, 62 | "timer_started_at": null, 63 | "created_at": "2018-10-17T09:33:46Z", 64 | "updated_at": "2018-10-17T09:33:46Z" 65 | } 66 | ``` 67 | 68 | ## GET /activities 69 | 70 | Retrieve all activities: 71 | 72 | ```bash 73 | curl -X GET \ 74 | 'https://{domain}.mocoapp.com/api/v1/activities?from=2018-06-01&to=2018-06-30&project_id=4242' \ 75 | -H 'Authorization: Token token=YOUR_API_KEY' 76 | ``` 77 | 78 | This returns an array of all activities. 79 | 80 | The following parameters can be supplied: 81 | 82 | - [Global filters apply](../entities#global-filters) 83 | - **from** – "2018-06-01" 84 | - **to** – "2018-06-30" 85 | - **user_id** – 123 86 | - **project_id** – 345 87 | - **task_id** – 789 88 | - **company_id** – 234567 89 | - **billable** - true / false (set to true for billable activities and false for non-billable activities) 90 | - **billed** - true / false (set to true for (already) billed activities and false for not (yet) billed activities) 91 | - **term** – "search terms" (search in tag, description and remote_id) 92 | 93 | ## GET /activities/{id} 94 | 95 | Retrieve a single activity: 96 | 97 | ```bash 98 | curl -X GET \ 99 | 'https://{domain}.mocoapp.com/api/v1/activities/{id}' \ 100 | -H 'Authorization: Token token=YOUR_API_KEY' 101 | ``` 102 | 103 | ## POST /activities 104 | 105 | Create an activity: 106 | 107 | Every activity is created for the user that the API key belongs to. Use [impersonation](../index.md#impersonation) to create activities for other users. 108 | 109 | ```bash 110 | curl -X POST \ 111 | 'https://{domain}.mocoapp.com/api/v1/activities' \ 112 | -H 'Authorization: Token token=YOUR_API_KEY' \ 113 | -H 'Content-Type: application/json' \ 114 | -d '{ 115 | "date": "2017-06-11", 116 | "description": "Analysis context and dependencies", 117 | "project_id": 123456, 118 | "task_id": 234567, 119 | "seconds": 3600 120 | }' 121 | ``` 122 | 123 | Mandatory fields are marked with a star (\*): 124 | 125 | - **date\*** – "2017-06-11" 126 | - **project_id\*** – 123456 127 | - **task_id\*** – 234567 128 | - **seconds** – 3600 💡 3600 seconds = 1 hour 129 | - **description** – "Analysis context and dependencies" 130 | - **billable** – true/false (default: `true` or dependent on project configuration) 131 | - **tag** – "RMT-123" (any tag as a string) 132 | - **remote_service** – jira (Allowed values are: "trello", "jira", "asana", "basecamp", "wunderlist", "basecamp2", "basecamp3", "toggl", "mite", "github", "youtrack") 133 | - **remote_id** – PRJ-2342 134 | - **remote_url** – https://jira.meinefirma.de/browse/PRJ-2342 135 | 136 | ## POST /activities/bulk 137 | 138 | Bulk insert activities: 139 | 140 | ```bash 141 | curl -X POST \ 142 | 'https://{domain}.mocoapp.com/api/v1/activities/bulk' \ 143 | -H 'Authorization: Token token=YOUR_API_KEY' \ 144 | -H 'Content-Type: application/json' \ 145 | -d '{ 146 | "activities": [ 147 | { 148 | "date": "2023-08-21", 149 | "description": "Activity 1", 150 | "project_id": 123456, 151 | "task_id": 234567, 152 | "seconds": 3600 153 | }, 154 | { 155 | "date": "2023-08-21", 156 | "description": "Activity 2", 157 | "project_id": 123456, 158 | "task_id": 234567, 159 | "seconds": 7200 160 | } 161 | ] 162 | }' 163 | ``` 164 | 165 | ## PUT /activities/{id} 166 | 167 | Update an activity. 168 | 169 | ```bash 170 | curl -X PUT \ 171 | 'https://{domain}.mocoapp.com/api/v1/activities/{id}' \ 172 | -H 'Authorization: Token token=YOUR_API_KEY' \ 173 | -H 'Content-Type: application/json' \ 174 | -d '{ 175 | "seconds": 7200 176 | }' 177 | ``` 178 | 179 | All fields are analogous to the POST request. 180 | 181 | ## PATCH /activities/{id}/start_timer 182 | 183 | Start or continue a timer on an activity. 184 | 185 | ```bash 186 | curl -X PATCH \ 187 | 'https://{domain}.mocoapp.com/api/v1/activities/{id}/start_timer' \ 188 | -H 'Authorization: Token token=YOUR_API_KEY' \ 189 | -H 'Content-Type: application/json' \ 190 | ``` 191 | 192 | {: .note } 193 | The timer is only available for activities on the current day. If timer cannot be started a 422 will be returned. 194 | 195 | ## PATCH /activities/{id}/stop_timer 196 | 197 | Stop a timer running on an activity. 198 | 199 | ```bash 200 | curl -X PATCH \ 201 | 'https://{domain}.mocoapp.com/api/v1/activities/{id}/stop_timer' \ 202 | -H 'Authorization: Token token=YOUR_API_KEY' \ 203 | -H 'Content-Type: application/json' \ 204 | ``` 205 | 206 | ## DELETE /activities/{id} 207 | 208 | Delete an activity. 209 | 210 | ```bash 211 | curl -X DELETE \ 212 | 'https://{domain}.mocoapp.com/api/v1/activities/{id}' \ 213 | -H 'Authorization: Token token=YOUR_API_KEY' 214 | ``` 215 | 216 | {: .note } 217 | Deleting an activity is only possible if this activity has not yet been billed or locked. 218 | 219 | ## POST /activities/disregard 220 | 221 | Mark activities as "already billed". 222 | 223 | ```bash 224 | curl -X POST \ 225 | 'https://{domain}.mocoapp.com/api/v1/activities/disregard' \ 226 | -H 'Authorization: Token token=YOUR_API_KEY' \ 227 | -H 'Content-Type: application/json' \ 228 | -d '{ 229 | "activity_ids": [47268, 47269], 230 | "reason": "Courtesy service as agreed", 231 | "company_id": 123456 232 | }' 233 | ``` 234 | 235 | Mandatory fields are marked with a star (\*): 236 | 237 | - **reason\*** – "Courtesy service as agreed" 238 | - **activity_ids\*** – [123, 234, 345] 239 | - **company_id\*** – 123456 (customer ID these activities belong to) 240 | - **project_id** – 234567 (project ID these activities belong to) 241 | -------------------------------------------------------------------------------- /sections/users.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: default 3 | parent: Entities 4 | has_children: true 5 | --- 6 | 7 | # Users 8 | 9 | German: "Personal" 10 | 11 | - TOC 12 | {:toc} 13 | 14 | ## Attributes 15 | 16 | ```json 17 | { 18 | "id": 123, 19 | "firstname": "Max", 20 | "lastname": "Muster", 21 | "active": true, 22 | "extern": false, 23 | "email": "max.muster@beispiel.de", 24 | "mobile_phone": "+49 177 123 45 67", 25 | "work_phone": "+49 40 123 45 67", 26 | "home_address": "", 27 | "info": "", 28 | "birthday": "1970-01-01", 29 | "iban": "CH3181239000001245689", 30 | "avatar_url": "https//meinefirma.mocoapp.com/.../profil.jpg", 31 | "tags": [ 32 | "Deutschland" 33 | ], 34 | "custom_properties": { 35 | "Starting Month": "January 2015" 36 | }, 37 | "unit": { 38 | "id": 456, 39 | "name": "Geschäftsleitung" 40 | }, 41 | "role": { 42 | "id": 42, 43 | "name": "Entwickler" 44 | }, 45 | "created_at": "2018-10-17T09:33:46Z", 46 | "updated_at": "2018-10-17T09:33:46Z" 47 | } 48 | ``` 49 | 50 | ## GET /users 51 | 52 | Retrieve all staff: 53 | 54 | ```bash 55 | curl -X GET \ 56 | 'https://{domain}.mocoapp.com/api/v1/users' \ 57 | -H 'Authorization: Token token=YOUR_API_KEY' 58 | ``` 59 | 60 | This returns an array with complete staff information (see Attributes). 61 | 62 | The following parameters can be supplied: 63 | 64 | - [Global filters apply](../entities#global-filters) 65 | - **include_archived** – true/false (deactivated users) 66 | - **tags** "Designer, Developer" (comma separated list) 67 | 68 | ## GET /users/{id} 69 | 70 | Retrieve a single staff member: 71 | 72 | ```bash 73 | curl -X GET \ 74 | 'https://{domain}.mocoapp.com/api/v1/users/{id}' \ 75 | -H 'Authorization: Token token=YOUR_API_KEY' 76 | ``` 77 | 78 | This returns a single staff member representation. 79 | 80 | ## POST /users 81 | 82 | Create a staff member: 83 | 84 | ```bash 85 | curl -X POST \ 86 | 'https://{domain}.mocoapp.com/api/v1/users' \ 87 | -H 'Authorization: Token token=YOUR_API_KEY' \ 88 | -H 'Content-Type: application/json' \ 89 | -d '{ 90 | "firstname": "Carmen", 91 | "lastname": "Sandiego", 92 | "email": "carmen.sandiego@acme.corp", 93 | "password": "dAfsdf88fw8fKjtD28f293!", 94 | "unit_id": 123 95 | }' 96 | ``` 97 | 98 | Mandatory fields are marked with a star (\*): 99 | 100 | - **firstname\*** – "Peter" 101 | - **lastname\*** – "Müller" 102 | - **email\*** – "peter.mueller@meinefirma.de" 103 | - **password** – "dAfsdf88fw8fKjtD28f293!" 104 | - **unit_id\*** – 123 (team ID) 105 | - **role_id** – 42 (permission role ID) 106 | - **active** – true/false (activated/deactivated) 107 | - **external** – true/false (external employee / contractor) 108 | - **language** – "de", "de-AT", "de-CH", "en", "it" or "fr" 109 | - **mobile_phone** – "+41 79 123 45 67" 110 | - **work_phone** – "+41 44 123 45 67" 111 | - **home_address** – "Peter Müller\nBeispielstrasse 123\nBeispielstadt" 112 | - **bday** – "1975-01-17" 113 | - **iban** - "CH3181239000001245689" 114 | - **work_phone** – "+41 44 123 45 67" 115 | - **tags** – ["Switzerland"] 116 | - **custom_properties** – {"Starting Month": "01.01.2016"} 117 | - **info** – "Info for this person..." 118 | - **welcome_email** – true/false (if the user should get the welcome email) 119 | - **avatar** – avatar (user picture) with the following fields: 120 | - filename – "document.pdf" 121 | - base64 – base64 encoded content of the file 122 | 123 | ## PUT /users/{id} 124 | 125 | Update a staff member: 126 | 127 | ```bash 128 | curl -X PUT \ 129 | 'https://{domain}.mocoapp.com/api/v1/users/{id}' \ 130 | -H 'Authorization: Token token=YOUR_API_KEY' \ 131 | -H 'Content-Type: application/json' \ 132 | -d '{ 133 | "lastname": "Casanova", 134 | "email": "carmen.casanova@acme.corp", 135 | }' 136 | ``` 137 | 138 | Fields are analogous to the POST request. A related [employment](employments.md) must be termined separately. 139 | 140 | ## DELETE /users/{id} 141 | 142 | {: .note } 143 | Deleting a staff member is only possible if no hours are billed already. 144 | 145 | ```bash 146 | curl -X DELETE \ 147 | 'https://{domain}.mocoapp.com/api/v1/users/{id}' \ 148 | -H 'Authorization: Token token=YOUR_API_KEY' 149 | ``` 150 | 151 | ## GET /users/{id}/performance_report 152 | 153 | Retrieve a report on tracked hours vs target hours: 154 | 155 | ```bash 156 | curl -X GET \ 157 | 'https://{domain}.mocoapp.com/api/v1/users/{id}/performance_report' \ 158 | -H 'Authorization: Token token=YOUR_API_KEY' 159 | ``` 160 | 161 | This returns a performance report for this user: 162 | 163 | ```json 164 | { 165 | "annually": { 166 | "year": 2021, 167 | "employment_hours": 1670.4, 168 | "target_hours": 1606.4, 169 | "hours_tracked_total": 210.95, 170 | "variation": -1395.45, 171 | "variation_until_today": -0.25, 172 | "hours_billable_total": 190.95 173 | }, 174 | "monthly": [ 175 | { 176 | "year": 2021, 177 | "month": 1, 178 | "target_hours": 128.0, 179 | "hours_tracked_total": 133.71, 180 | "variation": 5.71, 181 | "hours_billable_total": 113.95 182 | }, 183 | { 184 | "year": 2021, 185 | "month": 2, 186 | "target_hours": 128.0, 187 | "hours_tracked_total": 77.24, 188 | "variation": -50.76, 189 | "hours_billable_total": 67.95 190 | }, 191 | { 192 | "year": 2021, 193 | "month": 3, 194 | "target_hours": 115.2, 195 | "hours_tracked_total": 0.0, 196 | "variation": -115.2, 197 | "hours_billable_total": 0.0 198 | }, 199 | { 200 | "year": 2021, 201 | "month": 4, 202 | "target_hours": 128.0, 203 | "hours_tracked_total": 0.0, 204 | "variation": -128.0, 205 | "hours_billable_total": 0.0 206 | }, 207 | { 208 | "year": 2021, 209 | "month": 5, 210 | "target_hours": 121.6, 211 | "hours_tracked_total": 0.0, 212 | "variation": -121.6, 213 | "hours_billable_total": 0.0 214 | }, 215 | { 216 | "year": 2021, 217 | "month": 6, 218 | "target_hours": 140.8, 219 | "hours_tracked_total": 0.0, 220 | "variation": -140.8, 221 | "hours_billable_total": 0.0 222 | }, 223 | { 224 | "year": 2021, 225 | "month": 7, 226 | "target_hours": 140.8, 227 | "hours_tracked_total": 0.0, 228 | "variation": -140.8, 229 | "hours_billable_total": 0.0, 230 | }, 231 | { 232 | "year": 2021, 233 | "month": 8, 234 | "target_hours": 140.8, 235 | "hours_tracked_total": 0.0, 236 | "variation": -140.8, 237 | "hours_billable_total": 0.0 238 | }, 239 | { 240 | "year": 2021, 241 | "month": 9, 242 | "target_hours": 140.8, 243 | "hours_tracked_total": 0.0, 244 | "variation": -140.8, 245 | "hours_billable_total": 0.0 246 | }, 247 | { 248 | "year": 2021, 249 | "month": 10, 250 | "target_hours": 134.4, 251 | "hours_tracked_total": 0.0, 252 | "variation": -134.4, 253 | "hours_billable_total": 0.0 254 | }, 255 | { 256 | "year": 2021, 257 | "month": 11, 258 | "target_hours": 140.8, 259 | "hours_tracked_total": 0.0, 260 | "variation": -140.8, 261 | "hours_billable_total": 0.0 262 | }, 263 | { 264 | "year": 2021, 265 | "month": 12, 266 | "target_hours": 147.2, 267 | "hours_tracked_total": 0.0, 268 | "variation": -147.2, 269 | "hours_billable_total": 0.0 270 | } 271 | ] 272 | } 273 | ``` 274 | 275 | The following parameters can be supplied: 276 | 277 | - **year** – e.g. 2021 (empty = current year) 278 | -------------------------------------------------------------------------------- /sections/project_expenses.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: default 3 | parent: Projects 4 | grand_parent: Entities 5 | --- 6 | 7 | # Project Expenses 8 | 9 | German: "Projekte / Zusatzleistungen" 10 | 11 | - TOC 12 | {:toc} 13 | 14 | ## Attributes 15 | 16 | The representation contains, among the standard fields, also the following fields: 17 | 18 | - Custom properties 19 | - Company 20 | - Project 21 | - Group 22 | 23 | ```json 24 | { 25 | "id": 47266, 26 | "date": "2024-06-07", 27 | "title": "Hosting XS", 28 | "description": "
Hosting, Monitoring und Backup
", 29 | "quantity": 3, 30 | "unit": "Monat", 31 | "unit_price": 29, 32 | "unit_cost": 19, 33 | "price": 87, 34 | "cost": 57, 35 | "currency": "CHF", 36 | "budget_relevant": true, 37 | "billable": true, 38 | "billed": false, 39 | "purchase_assignment_locked": true, 40 | "cost_total_planned": 0, 41 | "planned_purchase_date": null, 42 | "invoice_id": null, 43 | "recurring_expense_id": null, 44 | "service_period": "06/2024", 45 | "service_period_from": "2024-06-01", 46 | "service_period_to": "2024-06-30", 47 | "file_url": "https//meinefirma.mocoapp.com/.../beleg1.jpg", 48 | "revenue_category": { 49 | "id": 124, 50 | "name": "Hosting", 51 | "revenue_account": 30056, 52 | "cost_category": "HO1" 53 | }, 54 | "custom_properties": { 55 | "Type": "Website" 56 | }, 57 | "company": { 58 | "id": 1234, 59 | "name": "Acme Corp." 60 | }, 61 | "project": { 62 | "id": 1234, 63 | "name": "Project A" 64 | }, 65 | "group": { 66 | "id": 456, 67 | "title": "Exepnse Group A", 68 | "budget": 5200 69 | }, 70 | "purchase_items": [ 71 | { 72 | "id": 1234, 73 | "title": "Item Title", 74 | "net_total", 12.0, 75 | "currency": "EUR", 76 | "purchase_id": 345, 77 | "document": { 78 | "id": 567, 79 | "file_url": "https://..." 80 | } 81 | } 82 | ], 83 | "created_at": "2024-06-06T09:33:46Z", 84 | "updated_at": "2024-06-06T09:33:46Z" 85 | } 86 | ``` 87 | 88 | ## GET /projects/{id}/expenses 89 | 90 | Retrieve all additional services for a project: 91 | 92 | ```bash 93 | curl -X GET \ 94 | 'https://{domain}.mocoapp.com/api/v1/projects/{id}/expenses' \ 95 | -H 'Authorization: Token token=YOUR_API_KEY' 96 | ``` 97 | 98 | This returns an array with all additional services (see Attributes). 99 | 100 | Additionally, these parameters can be supplied: 101 | 102 | - [Global filters apply](../entities#global-filters) 103 | - **billable** – true/false 104 | - **billed** – true/false 105 | - **budget_relevant** – true/false 106 | - **user_id** - 123456 (user that created expense) 107 | 108 | ## GET /projects/{id}/expenses/{id} 109 | 110 | Retrieve a single additional service for a project: 111 | 112 | ```bash 113 | curl -X GET \ 114 | 'https://{domain}.mocoapp.com/api/v1/projects/{id}/expenses/{id}' \ 115 | -H 'Authorization: Token token=YOUR_API_KEY' 116 | ``` 117 | 118 | ## POST /projects/{id}/expenses 119 | 120 | Create an additional service entry on a project: 121 | 122 | ```bash 123 | curl -X POST \ 124 | 'https://{domain}.mocoapp.com/api/v1/projects/{id}/expenses' \ 125 | -H 'Authorization: Token token=YOUR_API_KEY' \ 126 | -H 'Content-Type: application/json' \ 127 | -d '{ 128 | "date": "2018-10-01", 129 | "title": "Hosting XS", 130 | "quantity": 3, 131 | "unit": "months", 132 | "unit_price": 29, 133 | "unit_cost": 19, 134 | "file": { 135 | "filename": "document.pdf", 136 | "base64": "JVBERi0xLjQKJeLjz9MKNCAwIG9iago8PC9GaWx..." 137 | } 138 | }' 139 | ``` 140 | 141 | Mandatory fields are marked with a star (\*): 142 | 143 | - **date\*** – "2017-04-12" 144 | - **title\*** – "Hosting XS" 145 | - **quantity\*** – 3 146 | - **unit\*** – "months" 147 | - **unit_price\*** – 29 148 | - **unit_cost\*** – 19 149 | - **description** – "Hosting, Monitoring, Backup" 150 | - **billable** – true/false (default: true) 151 | - **budget_relevant** – true/false (default: false) 152 | - **service_period_from** – "2021-01-01" 153 | - **service_period_to** – "2021-01-31" 154 | - **user_id** - 456 (user responsible, current user by default) 155 | - **custom_properties** – {"Type": "Website"} 156 | - **file** – file attached to the expense, with the following fields: 157 | - filename – "document.pdf" 158 | - base64 – base64 encoded content of the file 159 | 160 | ## POST /projects/{id}/expenses/bulk 161 | 162 | Create multiple additional services entries: 163 | 164 | ```bash 165 | curl -X POST \ 166 | 'https://{domain}.mocoapp.com/api/v1/projects/{id}/expenses/bulk' \ 167 | -H 'Authorization: Token token=YOUR_API_KEY' \ 168 | -H 'Content-Type: application/json' \ 169 | -d '{ 170 | "bulk_data": [ 171 | { 172 | "date": "2018-10-20", 173 | "title": "Hosting: Server", 174 | "quantity": 1, 175 | "unit": "Server", 176 | "unit_price": 29, 177 | "unit_cost": 19 178 | }, 179 | { 180 | "date": "2018-10-22", 181 | "title": "Hosting: Server", 182 | "quantity": 1, 183 | "unit": "Server", 184 | "unit_price": 29, 185 | "unit_cost": 19 186 | } 187 | ] 188 | }' 189 | ``` 190 | 191 | Mandatory fields are marked with a star (\*): 192 | 193 | - **date\*** – "2017-04-12" 194 | - **title\*** – "Hosting XS" 195 | - **quantity\*** – 3 196 | - **unit\*** – "months" 197 | - **unit_price\*** – 29 198 | - **unit_cost\*** – 19 199 | - **description** – "Hosting, Monitoring, Backup" 200 | - **billable** – true/false (default: true) 201 | - **budget_relevant** – true/false (default: false) 202 | 203 | ## PUT /projects/{id}/expenses/{id} 204 | 205 | Update an additional services entry on a project: 206 | 207 | ```bash 208 | curl -X PUT \ 209 | 'https://{domain}.mocoapp.com/api/v1/projects/{id}/expenses/{id}' \ 210 | -H 'Authorization: Token token=YOUR_API_KEY' \ 211 | -H 'Content-Type: application/json' \ 212 | -d '{ 213 | "unit_price": 49 214 | }' 215 | ``` 216 | 217 | Fields are analogous to the POST request. Updates are only possible if this entry is not yet billed. 218 | 219 | ## DELETE /projects/{id}/expenses/{id} 220 | 221 | Delete an additional services entry on a project. 222 | 223 | Deletions are only possible if this entry is not yet billed. 224 | 225 | ```bash 226 | curl -X DELETE \ 227 | 'https://{domain}.mocoapp.com/api/v1/projects/{id}/expenses/{id}' \ 228 | -H 'Authorization: Token token=YOUR_API_KEY' 229 | ``` 230 | 231 | ## POST /projects/{id}/expenses/disregard 232 | 233 | Mark additional services entries as "already billed". 234 | 235 | ```bash 236 | curl -X POST \ 237 | 'https://{domain}.mocoapp.com/api/v1/projects/{id}/expenses/disregard' \ 238 | -H 'Authorization: Token token=YOUR_API_KEY' \ 239 | -H 'Content-Type: application/json' \ 240 | -d '{ 241 | "expense_ids": [1234, 5678], 242 | "reason": "Courtesy services, as discussed" 243 | }' 244 | ``` 245 | 246 | Mandatory fields are marked with a star (\*): 247 | 248 | - **reason\*** – "Courtesy services, as discussed" 249 | - **expense_ids\*** – [1234, 5678] 250 | 251 | ## GET /projects/expenses 252 | 253 | Retrieve all additional services 254 | 255 | ```bash 256 | curl -X GET \ 257 | 'https://{domain}.mocoapp.com/api/v1/projects/expenses' \ 258 | -H 'Authorization: Token token=YOUR_API_KEY' 259 | ``` 260 | 261 | This returns an array with all additional services (see Attributes). 262 | 263 | Additionally, these parameters can be supplied: 264 | 265 | - **ids** – e.g. `123,456` (IDS, comma-separated) 266 | - **updated_after** - e.g. `2022-09-01T14:00:00Z` ISO8601 timestamp, only records that have been updated/created after 267 | - **from** – "2019-01-01" 268 | - **to** – "2019-01-31" 269 | - **billable** – true/false 270 | - **billed** – true/false 271 | - **budget_relevant** – true/false 272 | - **tags** – "tag one,tag two" (comma-separated project tags) 273 | - **user_id** - 123456 (user that created expense) 274 | 275 | {: .note } 276 | Parameters `from` and `to` only work when provided together. 277 | -------------------------------------------------------------------------------- /Gemfile.lock: -------------------------------------------------------------------------------- 1 | GEM 2 | remote: https://rubygems.org/ 3 | specs: 4 | activesupport (8.0.1) 5 | base64 6 | benchmark (>= 0.3) 7 | bigdecimal 8 | concurrent-ruby (~> 1.0, >= 1.3.1) 9 | connection_pool (>= 2.2.5) 10 | drb 11 | i18n (>= 1.6, < 2) 12 | logger (>= 1.4.2) 13 | minitest (>= 5.1) 14 | securerandom (>= 0.3) 15 | tzinfo (~> 2.0, >= 2.0.5) 16 | uri (>= 0.13.1) 17 | addressable (2.8.7) 18 | public_suffix (>= 2.0.2, < 7.0) 19 | base64 (0.2.0) 20 | benchmark (0.4.0) 21 | bigdecimal (3.1.9) 22 | coffee-script (2.4.1) 23 | coffee-script-source 24 | execjs 25 | coffee-script-source (1.12.2) 26 | colorator (1.1.0) 27 | commonmarker (0.23.11) 28 | concurrent-ruby (1.3.5) 29 | connection_pool (2.5.0) 30 | csv (3.3.2) 31 | dnsruby (1.72.3) 32 | base64 (~> 0.2.0) 33 | simpleidn (~> 0.2.1) 34 | drb (2.2.1) 35 | em-websocket (0.5.3) 36 | eventmachine (>= 0.12.9) 37 | http_parser.rb (~> 0) 38 | ethon (0.16.0) 39 | ffi (>= 1.15.0) 40 | eventmachine (1.2.7) 41 | execjs (2.10.0) 42 | faraday (2.12.2) 43 | faraday-net_http (>= 2.0, < 3.5) 44 | json 45 | logger 46 | faraday-net_http (3.4.0) 47 | net-http (>= 0.5.0) 48 | ffi (1.17.1-x86_64-linux-gnu) 49 | forwardable-extended (2.6.0) 50 | gemoji (4.1.0) 51 | github-pages (232) 52 | github-pages-health-check (= 1.18.2) 53 | jekyll (= 3.10.0) 54 | jekyll-avatar (= 0.8.0) 55 | jekyll-coffeescript (= 1.2.2) 56 | jekyll-commonmark-ghpages (= 0.5.1) 57 | jekyll-default-layout (= 0.1.5) 58 | jekyll-feed (= 0.17.0) 59 | jekyll-gist (= 1.5.0) 60 | jekyll-github-metadata (= 2.16.1) 61 | jekyll-include-cache (= 0.2.1) 62 | jekyll-mentions (= 1.6.0) 63 | jekyll-optional-front-matter (= 0.3.2) 64 | jekyll-paginate (= 1.1.0) 65 | jekyll-readme-index (= 0.3.0) 66 | jekyll-redirect-from (= 0.16.0) 67 | jekyll-relative-links (= 0.6.1) 68 | jekyll-remote-theme (= 0.4.3) 69 | jekyll-sass-converter (= 1.5.2) 70 | jekyll-seo-tag (= 2.8.0) 71 | jekyll-sitemap (= 1.4.0) 72 | jekyll-swiss (= 1.0.0) 73 | jekyll-theme-architect (= 0.2.0) 74 | jekyll-theme-cayman (= 0.2.0) 75 | jekyll-theme-dinky (= 0.2.0) 76 | jekyll-theme-hacker (= 0.2.0) 77 | jekyll-theme-leap-day (= 0.2.0) 78 | jekyll-theme-merlot (= 0.2.0) 79 | jekyll-theme-midnight (= 0.2.0) 80 | jekyll-theme-minimal (= 0.2.0) 81 | jekyll-theme-modernist (= 0.2.0) 82 | jekyll-theme-primer (= 0.6.0) 83 | jekyll-theme-slate (= 0.2.0) 84 | jekyll-theme-tactile (= 0.2.0) 85 | jekyll-theme-time-machine (= 0.2.0) 86 | jekyll-titles-from-headings (= 0.5.3) 87 | jemoji (= 0.13.0) 88 | kramdown (= 2.4.0) 89 | kramdown-parser-gfm (= 1.1.0) 90 | liquid (= 4.0.4) 91 | mercenary (~> 0.3) 92 | minima (= 2.5.1) 93 | nokogiri (>= 1.16.2, < 2.0) 94 | rouge (= 3.30.0) 95 | terminal-table (~> 1.4) 96 | webrick (~> 1.8) 97 | github-pages-health-check (1.18.2) 98 | addressable (~> 2.3) 99 | dnsruby (~> 1.60) 100 | octokit (>= 4, < 8) 101 | public_suffix (>= 3.0, < 6.0) 102 | typhoeus (~> 1.3) 103 | html-pipeline (2.14.3) 104 | activesupport (>= 2) 105 | nokogiri (>= 1.4) 106 | http_parser.rb (0.8.0) 107 | i18n (1.14.7) 108 | concurrent-ruby (~> 1.0) 109 | jekyll (3.10.0) 110 | addressable (~> 2.4) 111 | colorator (~> 1.0) 112 | csv (~> 3.0) 113 | em-websocket (~> 0.5) 114 | i18n (>= 0.7, < 2) 115 | jekyll-sass-converter (~> 1.0) 116 | jekyll-watch (~> 2.0) 117 | kramdown (>= 1.17, < 3) 118 | liquid (~> 4.0) 119 | mercenary (~> 0.3.3) 120 | pathutil (~> 0.9) 121 | rouge (>= 1.7, < 4) 122 | safe_yaml (~> 1.0) 123 | webrick (>= 1.0) 124 | jekyll-avatar (0.8.0) 125 | jekyll (>= 3.0, < 5.0) 126 | jekyll-coffeescript (1.2.2) 127 | coffee-script (~> 2.2) 128 | coffee-script-source (~> 1.12) 129 | jekyll-commonmark (1.4.0) 130 | commonmarker (~> 0.22) 131 | jekyll-commonmark-ghpages (0.5.1) 132 | commonmarker (>= 0.23.7, < 1.1.0) 133 | jekyll (>= 3.9, < 4.0) 134 | jekyll-commonmark (~> 1.4.0) 135 | rouge (>= 2.0, < 5.0) 136 | jekyll-default-layout (0.1.5) 137 | jekyll (>= 3.0, < 5.0) 138 | jekyll-feed (0.17.0) 139 | jekyll (>= 3.7, < 5.0) 140 | jekyll-gist (1.5.0) 141 | octokit (~> 4.2) 142 | jekyll-github-metadata (2.16.1) 143 | jekyll (>= 3.4, < 5.0) 144 | octokit (>= 4, < 7, != 4.4.0) 145 | jekyll-include-cache (0.2.1) 146 | jekyll (>= 3.7, < 5.0) 147 | jekyll-mentions (1.6.0) 148 | html-pipeline (~> 2.3) 149 | jekyll (>= 3.7, < 5.0) 150 | jekyll-optional-front-matter (0.3.2) 151 | jekyll (>= 3.0, < 5.0) 152 | jekyll-paginate (1.1.0) 153 | jekyll-readme-index (0.3.0) 154 | jekyll (>= 3.0, < 5.0) 155 | jekyll-redirect-from (0.16.0) 156 | jekyll (>= 3.3, < 5.0) 157 | jekyll-relative-links (0.6.1) 158 | jekyll (>= 3.3, < 5.0) 159 | jekyll-remote-theme (0.4.3) 160 | addressable (~> 2.0) 161 | jekyll (>= 3.5, < 5.0) 162 | jekyll-sass-converter (>= 1.0, <= 3.0.0, != 2.0.0) 163 | rubyzip (>= 1.3.0, < 3.0) 164 | jekyll-sass-converter (1.5.2) 165 | sass (~> 3.4) 166 | jekyll-seo-tag (2.8.0) 167 | jekyll (>= 3.8, < 5.0) 168 | jekyll-sitemap (1.4.0) 169 | jekyll (>= 3.7, < 5.0) 170 | jekyll-swiss (1.0.0) 171 | jekyll-theme-architect (0.2.0) 172 | jekyll (> 3.5, < 5.0) 173 | jekyll-seo-tag (~> 2.0) 174 | jekyll-theme-cayman (0.2.0) 175 | jekyll (> 3.5, < 5.0) 176 | jekyll-seo-tag (~> 2.0) 177 | jekyll-theme-dinky (0.2.0) 178 | jekyll (> 3.5, < 5.0) 179 | jekyll-seo-tag (~> 2.0) 180 | jekyll-theme-hacker (0.2.0) 181 | jekyll (> 3.5, < 5.0) 182 | jekyll-seo-tag (~> 2.0) 183 | jekyll-theme-leap-day (0.2.0) 184 | jekyll (> 3.5, < 5.0) 185 | jekyll-seo-tag (~> 2.0) 186 | jekyll-theme-merlot (0.2.0) 187 | jekyll (> 3.5, < 5.0) 188 | jekyll-seo-tag (~> 2.0) 189 | jekyll-theme-midnight (0.2.0) 190 | jekyll (> 3.5, < 5.0) 191 | jekyll-seo-tag (~> 2.0) 192 | jekyll-theme-minimal (0.2.0) 193 | jekyll (> 3.5, < 5.0) 194 | jekyll-seo-tag (~> 2.0) 195 | jekyll-theme-modernist (0.2.0) 196 | jekyll (> 3.5, < 5.0) 197 | jekyll-seo-tag (~> 2.0) 198 | jekyll-theme-primer (0.6.0) 199 | jekyll (> 3.5, < 5.0) 200 | jekyll-github-metadata (~> 2.9) 201 | jekyll-seo-tag (~> 2.0) 202 | jekyll-theme-slate (0.2.0) 203 | jekyll (> 3.5, < 5.0) 204 | jekyll-seo-tag (~> 2.0) 205 | jekyll-theme-tactile (0.2.0) 206 | jekyll (> 3.5, < 5.0) 207 | jekyll-seo-tag (~> 2.0) 208 | jekyll-theme-time-machine (0.2.0) 209 | jekyll (> 3.5, < 5.0) 210 | jekyll-seo-tag (~> 2.0) 211 | jekyll-titles-from-headings (0.5.3) 212 | jekyll (>= 3.3, < 5.0) 213 | jekyll-watch (2.2.1) 214 | listen (~> 3.0) 215 | jemoji (0.13.0) 216 | gemoji (>= 3, < 5) 217 | html-pipeline (~> 2.2) 218 | jekyll (>= 3.0, < 5.0) 219 | json (2.9.1) 220 | just-the-docs (0.10.1) 221 | jekyll (>= 3.8.5) 222 | jekyll-include-cache 223 | jekyll-seo-tag (>= 2.0) 224 | rake (>= 12.3.1) 225 | kramdown (2.4.0) 226 | rexml 227 | kramdown-parser-gfm (1.1.0) 228 | kramdown (~> 2.0) 229 | liquid (4.0.4) 230 | listen (3.9.0) 231 | rb-fsevent (~> 0.10, >= 0.10.3) 232 | rb-inotify (~> 0.9, >= 0.9.10) 233 | logger (1.6.5) 234 | mercenary (0.3.6) 235 | minima (2.5.1) 236 | jekyll (>= 3.5, < 5.0) 237 | jekyll-feed (~> 0.9) 238 | jekyll-seo-tag (~> 2.1) 239 | minitest (5.25.4) 240 | net-http (0.6.0) 241 | uri 242 | nokogiri (1.18.8-x86_64-linux-gnu) 243 | racc (~> 1.4) 244 | octokit (4.25.1) 245 | faraday (>= 1, < 3) 246 | sawyer (~> 0.9) 247 | pathutil (0.16.2) 248 | forwardable-extended (~> 2.6) 249 | public_suffix (5.1.1) 250 | racc (1.8.1) 251 | rake (13.2.1) 252 | rb-fsevent (0.11.2) 253 | rb-inotify (0.11.1) 254 | ffi (~> 1.0) 255 | rexml (3.4.0) 256 | rouge (3.30.0) 257 | rubyzip (2.4.1) 258 | safe_yaml (1.0.5) 259 | sass (3.7.4) 260 | sass-listen (~> 4.0.0) 261 | sass-listen (4.0.0) 262 | rb-fsevent (~> 0.9, >= 0.9.4) 263 | rb-inotify (~> 0.9, >= 0.9.7) 264 | sawyer (0.9.2) 265 | addressable (>= 2.3.5) 266 | faraday (>= 0.17.3, < 3) 267 | securerandom (0.4.1) 268 | simpleidn (0.2.3) 269 | terminal-table (1.8.0) 270 | unicode-display_width (~> 1.1, >= 1.1.1) 271 | typhoeus (1.4.1) 272 | ethon (>= 0.9.0) 273 | tzinfo (2.0.6) 274 | concurrent-ruby (~> 1.0) 275 | unicode-display_width (1.8.0) 276 | uri (1.0.3) 277 | webrick (1.9.1) 278 | 279 | PLATFORMS 280 | x86_64-linux 281 | 282 | DEPENDENCIES 283 | github-pages 284 | jekyll 285 | jekyll-default-layout 286 | just-the-docs 287 | webrick 288 | 289 | BUNDLED WITH 290 | 2.3.11 291 | -------------------------------------------------------------------------------- /sections/purchases.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: default 3 | parent: Entities 4 | has_children: true 5 | --- 6 | 7 | # Purchases 8 | 9 | German: "Ausgaben" 10 | 11 | - TOC 12 | {:toc} 13 | 14 | ## Attributes 15 | 16 | Includes among the standard fields for purchases also: 17 | 18 | - tags 19 | - company (if the purchase is associated to a supplier) 20 | - payments (list of payments made for the purchase) 21 | - user 22 | - status (`pending` = Inbox, `archived` = Archive) 23 | - approval_status (`none` = no approval requested, `approved` = all requests approved, `denied` = at least 1 denial none pending, `pending` = approvals still pending) 24 | - items 25 | - items.vat ("tax", "reverse_charge", "intra_eu" (intra community trade, only applicable for accounts in the EU)) 26 | - items.expense (the associated project expense or `null`) 27 | - items.receipt (the associated receipt or `null`) 28 | 29 | ```json 30 | { 31 | "id": 987, 32 | "identifier": "E2016-0001", 33 | "receipt_identifier": "KK121", 34 | "title": "SBB Ticket", 35 | "info": null, 36 | "iban": "CH3908704016075473007", 37 | "reference": null, 38 | "date": "2020-02-28", 39 | "due_date": null, 40 | "service_period_from": "2020-02-28", 41 | "service_period_to": "2020-02-28", 42 | "status": "pending", 43 | "payment_method": "bank_transfer", 44 | "net_total": 44.88, 45 | "gross_total": 46.0, 46 | "currency": "CHF", 47 | "file_url": null, 48 | "custom_properties": { "Various": "some stuff" }, 49 | "tags": ["Transportation"], 50 | "approval_status": "approved", 51 | "company": { 52 | "id": 5552, 53 | "name": "Schweizerische Bundesbahnen SBB", 54 | "iban": "CH3908704016075473007" 55 | }, 56 | "payments": [], 57 | "user": { 58 | "id": 433109936, 59 | "firstname": "Mario", 60 | "name": "Rossi" 61 | }, 62 | "refund_request": { 63 | "id": 66129936, 64 | "comment": "My receipts", 65 | "user_id": 123456 66 | }, 67 | "credit_card_transaction": { 68 | "source": "pliant", 69 | "transaction_identifier": "57a04fc8-a56e-4be6-acb2-241b513f0570" 70 | }, 71 | "items": [ 72 | { 73 | "id": 311936153, 74 | "title": "SBB Ticket", 75 | "net_total": 44.88, 76 | "tax_total": 1.12, 77 | "tax": 2.5, 78 | "vat": { "tax": 2.5, "reverse_charge": false, "intra_eu": false, "active": true }, 79 | "tax_included": true, 80 | "gross_total": 46.0, 81 | "category": { 82 | "id": 671034328, 83 | "name": "Spesen und Reisekosten", 84 | "credit_account": "6640" 85 | }, 86 | "supplier_credit_number": 70001, 87 | "expense": { 88 | "id": 7655423, 89 | "project": { 90 | "id": 23345545, 91 | "company_id": 54345 92 | } 93 | }, 94 | "receipt": { 95 | "id": 9857765, 96 | "title": "SBB Ticket", 97 | "date": "2018-10-01", 98 | "attachment_url": "https://..." 99 | } 100 | } 101 | ], 102 | "created_at": "2018-10-17T09:33:46Z", 103 | "updated_at": "2018-10-17T09:33:46Z" 104 | } 105 | ``` 106 | 107 | ## GET /purchases 108 | 109 | Retrieve all purchases: 110 | 111 | ```bash 112 | curl -X GET \ 113 | 'https://{domain}.mocoapp.com/api/v1/purchases' \ 114 | -H 'Authorization: Token token=YOUR_API_KEY' 115 | ``` 116 | 117 | It's also possible to filter: 118 | 119 | - [Global filters apply](../entities#global-filters) 120 | - **category_id** – identifier of the purchases' category, 121 | - **term** – full text search on purchase positions, 122 | - **company_id** – identifier of the supplier, pass _0_ to get the purchases not associated to a supplier, 123 | - **status** – "pending" or "archived" (Inbox / Archive) 124 | - **not_booked** – true/false 125 | - **tags** – "Transportation, Restaurants" (comma separated list) 126 | - **date** – date range in the form _2020-02-01:2020-02-22_ 127 | - **unpaid** – filter only purchases without a payment 128 | - **payment_method** – possible values are: "bank_transfer", "direct_debit", "credit_card", "paypal" or "cash", "bank_transfer_swiss_qr_esr" 129 | - **receipt_identifier** – filter by the receipts invoice number, e.g. R2023-1234. It must be unique scoped by supplier. 130 | - **identifier** – filter by purchase identifier, e.g. E2312-0001 131 | 132 | Returns an array with all purchases information (see attributes). 133 | 134 | ## GET /purchases/{id} 135 | 136 | Retrieve a single purchase: 137 | 138 | ```bash 139 | curl -X GET \ 140 | 'https://{domain}.mocoapp.com/api/v1/purchases/{id}' \ 141 | -H 'Authorization: Token token=YOUR_API_KEY' 142 | ``` 143 | 144 | Returns the representation for a single purchase. 145 | 146 | ## POST /purchases 147 | 148 | Create a purchase: 149 | 150 | ```bash 151 | curl -X POST \ 152 | 'https://{domain}.mocoapp.com/api/v1/purchases' \ 153 | -H 'Authorization: Token token=YOUR_API_KEY' \ 154 | -H 'Content-Type: application/json' \ 155 | -d ' 156 | { 157 | "date": "2020-02-02", 158 | "currency": "EUR", 159 | "payment_method": "bank_transfer", 160 | "receipt_identifier": "XXLA", 161 | "custom_properties": { "Various": "Stuff" }, 162 | "items": [ 163 | { 164 | "title": "Ticket", 165 | "total": 30, 166 | "tax": 10, 167 | "tax_included": true 168 | } 169 | ], 170 | "file": { 171 | "filename": "document.pdf", 172 | "base64": "JVBERi0xLjQKJeLjz9MKNCAwIG9iago8PC9GaWx..." 173 | } 174 | }' 175 | ``` 176 | 177 | Mandatory fields are marked with a star (\*): 178 | 179 | - **date\*** – "2020-02-02" 180 | - **currency\*** – "CHF" (a valid currency of the account) 181 | - **payment_method\*** – "bank_transfer", "direct_debit", "credit_card", "paypal", "cash", "bank_transfer_swiss_qr_esr" 182 | - **title** – set the title for this purchase. If left out, the title is generated from the positions. 183 | - **items\*** – list of position. At least one position must be present and every position has the following fields: 184 | - **title\*** – Ticket 185 | - **total\*** – 30 186 | - **tax\*** – 7.7 (tax percentage) 187 | - **tax_included** – true (specify if the total includes the tax or not) 188 | - **category_id** – 123 (reference to a purchase category) 189 | - **due_date** – "2020-02-18" 190 | - **service_period_from** – "2020-01-01" 191 | - **service_period_to** – "2020-01-31" 192 | - **status** - "pending" or "archived" 193 | - **due_date** – "2020-02-18" 194 | - **company_id** – 211 (reference to the supplier) 195 | - **user_id** – 123 (reference to the responsible user) 196 | - **receipt_identifier** – 123 197 | - **info** – free text 198 | - **iban** – CH123 199 | - **reference** – ref 200 | - **custom_property_values** – {"Field": "Value} 201 | - **file** – file attached to the purchase, with the following fields: 202 | - filename – "document.pdf" 203 | - base64 – base64 encoded content of the file 204 | - **tags** – ["Label1", "Label2"] 205 | 206 | ## PUT /purchases/{id} 207 | 208 | Update a purchase: 209 | 210 | ```bash 211 | curl -X PUT \ 212 | 'https://{domain}.mocoapp.com/api/v1/purchases/{id}' \ 213 | -H 'Authorization: Token token=YOUR_API_KEY' \ 214 | -H 'Content-Type: application/json' \ 215 | -d '{ 216 | "date": "2020-02-02", 217 | "currency": "EUR", 218 | "payment_method": "bank_transfer", 219 | "receipt_identifier": "XXLA", 220 | }' 221 | ``` 222 | 223 | Fields are analogous to the POST request, update of purchase's items is at the moment **NOT** supported. 224 | 225 | ## POST /purchases/{id}/assign_to_project 226 | 227 | Assign a purchase item to a project by creating or linking to an expense in the project. 228 | The assignment has to be done per line item explicitly. 229 | 230 | ```bash 231 | curl -X POST \ 232 | 'https://{domain}.mocoapp.com/api/v1/purchases/{id}/assign_to_project' \ 233 | -H 'Authorization: Token token=YOUR_API_KEY' \ 234 | -H 'Content-Type: application/json' \ 235 | -d ' 236 | { 237 | "item_id": 311936153, 238 | "project_id": 23345545, 239 | "expense_id": 7655423, 240 | "notify_project_leader": true, 241 | "billable": true, 242 | "budget_relevant": true, 243 | "surcharge": true 244 | }' 245 | ``` 246 | 247 | Mandatory fields are marked with a star (*): 248 | 249 | - **item_id*** – 311936153 (reference to the purchase item) 250 | - **project_id*** – 23345545 (reference to the project) 251 | - expense_id – 7655423 (reference to the project expense, if empty, a new one is created) 252 | - notify_project_leader – true (send a notification to the project if an expense is created) 253 | - surcharge – true/false (if provided in account settings, the surcharge will be applied) 254 | 255 | The following fields will override account settings only if provided: 256 | 257 | - billable – true (if the expense is billable) 258 | - budget_relevant – true (if the expense is budget relevant) 259 | 260 | ## PATCH /purchases/{id}/update_status 261 | 262 | Updates the purchase status: 263 | 264 | ```bash 265 | curl -X PATCH \ 266 | 'https://{domain}.mocoapp.com/api/v1/purchases/{id}/update_status' \ 267 | -H 'Authorization: Token token=YOUR_API_KEY' \ 268 | -H 'Content-Type: application/json' \ 269 | -d ' 270 | { 271 | "status": "archived" 272 | }' 273 | ``` 274 | 275 | - **status\*** – "pending", "archived" 276 | 277 | ## PATCH /purchases/{id}/store_document 278 | 279 | Submits the purchase's document using `multipart/form-data` format if it has to be changed afterwards or was not submitted 280 | with the initial creation. 281 | 282 | ```bash 283 | curl -X PATCH \ 284 | 'https://{domain}.mocoapp.com/api/v1/purchases/{id}/store_document' \ 285 | -H 'Authorization: Token token=YOUR_API_KEY' \ 286 | -F file=@/path/to/file.pdf 287 | ``` 288 | 289 | - **file\*** – path to the document to store 290 | 291 | ## DELETE /purchases/{id} 292 | 293 | {: .note } 294 | Deletes a purchase. It's possible only if the status is _pending_ and no payments have been registered. 295 | 296 | ```bash 297 | curl -X DELETE \ 298 | 'https://{domain}.mocoapp.com/api/v1/purchases/{id}' \ 299 | -H 'Authorization: Token token=YOUR_API_KEY' 300 | ``` 301 | -------------------------------------------------------------------------------- /sections/projects.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: default 3 | parent: Entities 4 | has_children: true 5 | --- 6 | 7 | # Projects 8 | 9 | German: "Projekte" 10 | 11 | - TOC 12 | {:toc} 13 | 14 | ## Attributes 15 | 16 | The project representation contains, among the standard fields, also: 17 | 18 | - custom properties 19 | - project leader (user) 20 | - customer 21 | - deal (optional) 22 | - tasks (services) 23 | - contracts (assigned staff) 24 | - project group 25 | 26 | The attributes `hourly_rate` and `billing_variant` are linked. By choosing the billing variant "project", the hourly rate is just that. If choosing "task" (depending on the service) or "user" (depending on the staff), hourly rate becomes the mean value of hourly rates. Thus, `hourly_rate` on a `task` or `contract` only become relevant if the `billing_variant` is set accordingly. 27 | 28 | ```json 29 | { 30 | "id": 1234567, 31 | "identifier": "P001", 32 | "name": "Website Support", 33 | "active": true, 34 | "billable": true, 35 | "fixed_price": true, 36 | "retainer": false, 37 | "start_date": null, 38 | "finish_date": "2018-12-31", 39 | "color": "#CCCC00", 40 | "currency": "EUR", 41 | "billing_variant": "project", 42 | "billing_address": "Beispiel AG\nHerr Maier\nBeispielstrasse...", 43 | "billing_email_to": "project@beispiel.co", 44 | "billing_email_cc": "project-cc@beispiel.co", 45 | "billing_notes": "Billig notes text", 46 | "setting_include_time_report": true, 47 | "budget": 18200, 48 | "budget_monthly": null, 49 | "budget_expenses": 8200, 50 | "hourly_rate": 150, 51 | "info": "Abrechnung jährlich", 52 | "tags": ["Print", "Digital"], 53 | "customer_report_url": "https://mycompany.mocoapp.com/projects/1234567/customer_report/cfd1901d23e000712488", 54 | "custom_properties": { 55 | "Project Management": "https://basecamp.com/123456" 56 | }, 57 | "leader": { 58 | "id": 933590696, 59 | "firstname": "Michael", 60 | "lastname": "Mustermann" 61 | }, 62 | "co_leader": null, 63 | "customer": { 64 | "id": 1233434, 65 | "name": "Beispiel AG" 66 | }, 67 | "deal": { 68 | "id": 5635453, 69 | "name": "Website Relaunch" 70 | }, 71 | "tasks": [ 72 | { 73 | "id": 125112, 74 | "name": "Project Management", 75 | "billable": true, 76 | "active": true, 77 | "budget": null, 78 | "hourly_rate": 0, 79 | "description": "A task description" 80 | }, 81 | { 82 | "id": 125111, 83 | "name": "Development", 84 | "billable": true, 85 | "active": true, 86 | "budget": null, 87 | "hourly_rate": 0, 88 | "description": "A task description" 89 | } 90 | ], 91 | "contracts": [ 92 | { 93 | "id": 458639048, 94 | "user_id": 933590696, 95 | "firstname": "Michael", 96 | "lastname": "Mustermann", 97 | "billable": true, 98 | "active": true, 99 | "budget": null, 100 | "hourly_rate": 0 101 | }, 102 | { 103 | "id": 458672097, 104 | "user_id": 933589591, 105 | "firstname": "Nicola", 106 | "lastname": "Piccinini", 107 | "billable": true, 108 | "active": true, 109 | "budget": null, 110 | "hourly_rate": 0 111 | } 112 | ], 113 | "project_group": { 114 | "id": 456687, 115 | "name": "Webpages" 116 | }, 117 | "billing_contact": { 118 | "id": 1234, 119 | "firstname": "Maxine", 120 | "lastname": "Muster" 121 | }, 122 | "contact": { 123 | "id": 2345, 124 | "firstname": "Max", 125 | "lastname": "Muster" 126 | }, 127 | "secondary_contact": { 128 | "id": 3456, 129 | "firstname": "Meike", 130 | "lastname": "Muster" 131 | }, 132 | "created_at": "2018-10-17T09:33:46Z", 133 | "updated_at": "2018-10-17T09:33:46Z" 134 | } 135 | ``` 136 | 137 | ## GET /projects 138 | 139 | Retrieve all projects: 140 | 141 | ```bash 142 | curl -X GET \ 143 | 'https://{domain}.mocoapp.com/api/v1/projects' \ 144 | -H 'Authorization: Token token=YOUR_API_KEY' 145 | ``` 146 | 147 | This returns an array with complete project information (see Attributes). 148 | 149 | The following parameters can be supplied: 150 | 151 | - [Global filters apply](../entities#global-filters) 152 | - **include_archived** – true/false 153 | - **include_company** – true/false (returns a complete company instead of just ID and name) 154 | - **leader_id** – 123456 (project (co-)leader user ID; also multiple values, comma-separated) 155 | - **company_id** – 123456 (also multiple values, comma-separated) 156 | - **created_from** – "2018-01-01" 157 | - **created_to** – "2018-12-31" 158 | - **updated_from** – "2018-01-01" 159 | - **updated_to** – "2018-12-31" 160 | - **tags** – "Important, Strategic" (comma separated list) 161 | - **identifier** – "P1903-003" (also multiple values, comma-separated) 162 | - **retainer** – true/false 163 | - **project_group_id** – 4566687 (also multiple values, comma-separated) 164 | - **deal_id** – 123456 (also multiple values, comma-separated) 165 | 166 | ## GET /projects/assigned 167 | 168 | Retrieve all projects assigned to the user: 169 | 170 | ```bash 171 | curl -X GET \ 172 | 'https://{domain}.mocoapp.com/api/v1/projects/assigned' \ 173 | -H 'Authorization: Token token=YOUR_API_KEY' 174 | ``` 175 | 176 | This returns an array with limited project information. 177 | 178 | ```json 179 | [ 180 | { 181 | "id": 1234, 182 | "identifier": "P1900", 183 | "name": "Application", 184 | "active": false, 185 | "billable": true, 186 | "customer": { 187 | "id": 4567, 188 | "name": "A Company" 189 | }, 190 | "tasks": [ 191 | { 192 | "id": 573383, 193 | "name": "Integrations", 194 | "active": true, 195 | "billable": true 196 | } 197 | ], 198 | "contract": { 199 | "user_id": 65455, 200 | "active": true 201 | } 202 | } 203 | ] 204 | ``` 205 | 206 | The following parameters can be supplied: 207 | 208 | - **active** – true/false 209 | 210 | ## GET /projects/{id} 211 | 212 | Retrieve a single project: 213 | 214 | ```bash 215 | curl -X GET \ 216 | 'https://{domain}.mocoapp.com/api/v1/projects/{id}' \ 217 | -H 'Authorization: Token token=YOUR_API_KEY' 218 | ``` 219 | 220 | This returns a single project representation. 221 | 222 | ## POST /projects 223 | 224 | Create a project: 225 | 226 | ```bash 227 | curl -X POST \ 228 | 'https://{domain}.mocoapp.com/api/v1/projects' \ 229 | -H 'Authorization: Token token=YOUR_API_KEY' \ 230 | -H 'Content-Type: application/json' \ 231 | -d '{ 232 | "name": "Website Relaunch", 233 | "currency": "EUR", 234 | "leader_id": "1234", 235 | "customer_id": "5678", 236 | "tags": ["Print", "Digital"], 237 | }' 238 | ``` 239 | 240 | Mandatory fields are marked with a star (\*): 241 | 242 | - **name\*** – "Relaunch Website" 243 | - **currency\*** – "EUR" 244 | - **start_date\*** – "2018-01-01" 245 | - **finish_date\*** – "2018-12-31" 246 | - **fixed_price\*** – true/false 247 | - **retainer\*** – true/false ⚠ see below requirements for other fields 248 | - **leader_id\*** – 123456 (user ID) 249 | - **co_leader_id** – 12345 (user ID) 250 | - **customer_id\*** – 234567 251 | - **deal_id** – 123456 (deal ID) 252 | - **project_group_id** - 123456 (project group ID) 253 | - **contact_id** - 123456 (contact ID) 254 | - **secondary_contact_id** - 56789 (contact ID) 255 | - **billing_contact_id** - 56789 (contact ID) 256 | - **identifier\*** – "P-123" (only mandatory if number ranges are manual) 257 | - **billing_address** – "Beispiel AG\nBeispielstrasse 123\n12345 Berlin" 258 | - **billing_email_to** - "project@beispiel.co" 259 | - **billing_email_cc** - "project-cc@beispiel.co" 260 | - **billing_notes** - "Billing notes text" 261 | - **setting_include_time_report** - true / false 262 | - **billing_variant** – "project", "task" or "user" (default: "project") 263 | - **hourly_rate** – 150 264 | - **budget** – 20000 265 | - **budget_monthly** – 2000 266 | - **budget_expenses** - 5000 267 | - **tags** – ["Print", "Digital"] 268 | - **custom_properties** – {"PO-Nummer": "123-ABC"} 269 | - **info** – "Info for this project" 270 | - **skip_favorite** – don't add this project to the leaders' favorites 271 | 272 | {: .note } 273 | If the field `retainer` is true, the fields `start_date`, `finish_date`, `budget_monthly` are mandatory. Also the start date has to be on the first and the finish date on the last of a month! 274 | 275 | ## PUT /projects/{id} 276 | 277 | Update a project: 278 | 279 | ```bash 280 | curl -X PUT \ 281 | 'https://{domain}.mocoapp.com/api/v1/projects/{id}' \ 282 | -H 'Authorization: Token token=YOUR_API_KEY' \ 283 | -H 'Content-Type: application/json' \ 284 | -d '{ 285 | "budget": 25000 286 | }' 287 | ``` 288 | 289 | Fields are analogous to the POST request, except for `currency` which cannot be modified after creation. 290 | 291 | ## DELETE /projects/{id} 292 | 293 | {: .note } 294 | Deletes a project. It's possible only if there are no activities, invoices, offers or expenses. 295 | 296 | ```bash 297 | curl -X DELETE \ 298 | 'https://{domain}.mocoapp.com/api/v1/projects/{id}' \ 299 | -H 'Authorization: Token token=YOUR_API_KEY' 300 | ``` 301 | 302 | ## PUT /projects/{id}/archive 303 | 304 | Archival of a project: 305 | 306 | ```bash 307 | curl -X PUT \ 308 | 'https://{domain}.mocoapp.com/api/v1/projects/{id}/archive' \ 309 | -H 'Authorization: Token token=YOUR_API_KEY' \ 310 | -H 'Content-Type: application/json' 311 | ``` 312 | 313 | ## PUT /projects/{id}/unarchive 314 | 315 | Reactivate an archived project: 316 | 317 | ```bash 318 | curl -X PUT \ 319 | 'https://{domain}.mocoapp.com/api/v1/projects/{id}/unarchive' \ 320 | -H 'Authorization: Token token=YOUR_API_KEY' \ 321 | -H 'Content-Type: application/json' 322 | ``` 323 | 324 | ## GET /projects/{id}/report 325 | 326 | Retrieve a project report: 327 | 328 | ```bash 329 | curl -X GET \ 330 | 'https://{domain}.mocoapp.com/api/v1/projects/{id}/report' \ 331 | -H 'Authorization: Token token=YOUR_API_KEY' 332 | ``` 333 | 334 | This returns the most important project business indicators: 335 | 336 | ```json 337 | { 338 | "budget_total": 50000.0, 339 | "budget_progress_in_percentage": 50, 340 | "budget_remaining": 25.0, 341 | "invoiced_total": 27885.0, 342 | "currency": "EUR", 343 | "hours_total": 1500, 344 | "hours_billable": 1340, 345 | "hours_remaining": 1500, 346 | "costs_expenses": 4000.0, 347 | "costs_activities": 16450.0, 348 | "costs_by_task": [ 349 | { 350 | "id": 7536, 351 | "name": "Project Management", 352 | "hours_total": 12.5, 353 | "total_costs": 725.0 354 | }, 355 | { 356 | "id": 7239, 357 | "name": "Design", 358 | "hours_total": 71.98, 359 | "total_costs": 5598.0 360 | }, 361 | { 362 | "id": 573376, 363 | "name": "Development", 364 | "hours_total": 94.48, 365 | "total_costs": 9448.0 366 | } 367 | ] 368 | } 369 | ``` 370 | 371 | {: .note } 372 | All costs are in the account's main currency, it might differ from the budget and billable items! 373 | 374 | ## PUT /projects/{id}/share 375 | 376 | Activate project report sharing: 377 | 378 | ```bash 379 | curl -X PUT \ 380 | 'https://{domain}.mocoapp.com/api/v1/projects/{id}/share' \ 381 | -H 'Authorization: Token token=YOUR_API_KEY' \ 382 | -H 'Content-Type: application/json' 383 | ``` 384 | 385 | This returns the the following attributes: 386 | 387 | ```json 388 | { 389 | "id": 123, 390 | "active": true, 391 | "url": "https://..." 392 | } 393 | ``` 394 | 395 | ## PUT /projects/{id}/disable_share 396 | 397 | Deactive project report sharing: 398 | 399 | ```bash 400 | curl -X PUT \ 401 | 'https://{domain}.mocoapp.com/api/v1/projects/{id}/disable_share' \ 402 | -H 'Authorization: Token token=YOUR_API_KEY' \ 403 | -H 'Content-Type: application/json' 404 | ``` 405 | 406 | This returns the the following attributes: 407 | 408 | ```json 409 | { 410 | "id": 123, 411 | "active": false, 412 | "url": null 413 | } 414 | ``` 415 | 416 | ## PUT /projects/{id}/assign_project_group 417 | 418 | Assign this project to a project group: 419 | 420 | ```bash 421 | curl -X PUT \ 422 | 'https://{domain}.mocoapp.com/api/v1/projects/{id}/assign_project_group' \ 423 | -H 'Authorization: Token token=YOUR_API_KEY' \ 424 | -H 'Content-Type: application/json' \ 425 | -d '{ 426 | "project_group_id": 123 427 | }' 428 | ``` 429 | 430 | ## PUT /projects/{id}/unassign_project_group 431 | 432 | Unassign this project from its project group: 433 | 434 | ```bash 435 | curl -X PUT \ 436 | 'https://{domain}.mocoapp.com/api/v1/projects/{id}/unassign_project_group' \ 437 | -H 'Authorization: Token token=YOUR_API_KEY' \ 438 | -H 'Content-Type: application/json' 439 | ``` 440 | -------------------------------------------------------------------------------- /sections/offers.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: default 3 | parent: Entities 4 | has_children: true 5 | --- 6 | 7 | # Offers 8 | 9 | German: "Angebote" 10 | 11 | - TOC 12 | {:toc} 13 | 14 | ## Attributes 15 | 16 | The offer representation contains among the standard fields: 17 | 18 | - custom properties 19 | - positions (items) 20 | - position types ("title", "description", "item", "subtotal", "page-break" or "separator") 21 | - subtotal_type: `part_total`, `sub_total`, `optional_part_total`, `optional_sub_total` (only relevant if type is `subtotal`) 22 | - vat ("tax", "reverse_charge", "intra_eu" (intra community trade, only applicable for accounts in the EU)) 23 | - service_type ("service" for regular items, "expense" for additional services) 24 | 25 | ```json 26 | { 27 | "id": 273, 28 | "identifier": "A1704-042", 29 | "invoice_id": 1873491, 30 | "date": "2017-04-12", 31 | "due_date": "2017-04-26", 32 | "title": "Offer - User Management", 33 | "recipient_address": "Beispiel GmbH\nPeter Muster\nBeispielstrasse 123\n12345 Berlin", 34 | "currency": "EUR", 35 | "net_total": 12750, 36 | "tax": 19, 37 | "vat": { "tax": 19.0, "reverse_charge": false, "intra_eu": false, "active": true, "print_gross_total": true, "notice_tax_exemption": "", "notice_tax_exemption_alt": "" }, 38 | "gross_total": 15172.5, 39 | "discount": 10, 40 | "status": "created", 41 | "salutation": "Hallo Peter

Folgende Aufwände schätzen wir für die Umsetzung der Komponenten:", 42 | "footer": "Für Rückfragen stehe ich dir jederzeit gerne zur Verfügung.

Viele Grüsse

Tobias", 43 | "tags": ["Print", "Digital"], 44 | "custom_properties": { 45 | "ext-ref": "3421" 46 | }, 47 | "company": { 48 | "id": 1234, 49 | "name": "Acme Corp." 50 | }, 51 | "project": { 52 | "id": 1234, 53 | "identifier": "P123", 54 | "name": "A Project" 55 | }, 56 | "deal": { 57 | "id": 1234, 58 | "name": "A Lead" 59 | }, 60 | "user": { 61 | "id": 1234, 62 | "firstname": "Jane", 63 | "lastname": "Doe" 64 | }, 65 | "offer_confirmation": { 66 | "id": 1234, 67 | "date": "2022-12-12", 68 | "title": "Offer confirmation", 69 | "created_at": "2022-12-12T09:33:46Z", 70 | "updated_at": "2022-12-12T09:33:46Z" 71 | }, 72 | "customer_approval": { 73 | "id": 1234, 74 | "active": true, 75 | "url": "https://mycompany.mocoapp.com/offers/1234/customer_approvals/ffbe642f6bdc65df7cb83a0d9459ece4" 76 | }, 77 | "items": [ 78 | { 79 | "id": 29, 80 | "type": "item", 81 | "title": "Project Setup", 82 | "description": null, 83 | "quantity": 1, 84 | "unit": "d", 85 | "unit_price": 1500, 86 | "net_total": 1500, 87 | "optional": false 88 | "service_type": "service", 89 | "revenue_category": { 90 | "id": 124, 91 | "name": "Hosting", 92 | "revenue_account": 30056, 93 | "cost_category": "HO1" 94 | } 95 | }, 96 | { 97 | "id": 30, 98 | "type": "item", 99 | "title": "Master Data", 100 | "description": null, 101 | "quantity": 3, 102 | "unit": "d", 103 | "unit_price": 1500, 104 | "net_total": 4500, 105 | "optional": false, 106 | "service_type": "service", 107 | "revenue_category": null 108 | }, 109 | { 110 | "id": 31, 111 | "type": "description", 112 | "title": null, 113 | "description": "Master data can be added.", 114 | "quantity": 0, 115 | "unit": null, 116 | "unit_price": 0, 117 | "net_total": 0, 118 | "optional": false, 119 | "service_type": "service", 120 | "revenue_category": null 121 | }, 122 | { 123 | "id": 34, 124 | "type": "item", 125 | "title": "OAuth Provider (Single Sign On)", 126 | "description": null, 127 | "quantity": 4, 128 | "unit": "d", 129 | "unit_price": 1500, 130 | "net_total": 6000, 131 | "optional": false, 132 | "service_type": "expense", 133 | "revenue_category": { 134 | "id": 123, 135 | "name": "Software-Entwicklung", 136 | "revenue_account": 30055, 137 | "cost_category": "SW1" 138 | } 139 | }, 140 | { 141 | "id": 35, 142 | "type": "description", 143 | "title": null, 144 | "description": "This component runs centrally and provides an OAuth Provider.
Other applications can access this authorization service.", 145 | "quantity": 0, 146 | "unit": null, 147 | "unit_price": 0, 148 | "net_total": 0, 149 | "optional": false, 150 | "service_type": "service", 151 | "revenue_category": null 152 | }, 153 | { 154 | "id": 38, 155 | "type": "item", 156 | "title": "Project Management / Communication / Hand-Over", 157 | "description": null, 158 | "quantity": 0.5, 159 | "unit": "d", 160 | "unit_price": 1500, 161 | "net_total": 750, 162 | "optional": false, 163 | "service_type": "service" 164 | "revenue_category": { 165 | "id": 126, 166 | "name": "Projektleitung", 167 | "revenue_account": 30058, 168 | "cost_category": "PM1" 169 | } 170 | } 171 | ], 172 | "created_at": "2018-10-17T09:33:46Z", 173 | "updated_at": "2018-10-17T09:33:46Z" 174 | } 175 | ``` 176 | 177 | ## GET /offers 178 | 179 | Retrieve all offers: 180 | 181 | ```bash 182 | curl -X GET \ 183 | 'https://{domain}.mocoapp.com/api/v1/offers' \ 184 | -H 'Authorization: Token token=YOUR_API_KEY' 185 | ``` 186 | 187 | This returns an array with complete offer information (see Attributes), except: `salutation`, `footer` and `items`. 188 | 189 | Offers can be sorted by: `date`, `created_at` and `title`: 190 | 191 | ```bash 192 | curl -X GET \ 193 | 'https://{domain}.mocoapp.com/api/v1/offers?sort=date' \ 194 | -H 'Authorization: Token token=YOUR_API_KEY' 195 | ``` 196 | 197 | Additionally, these parameters can be supplied: 198 | 199 | - [Global filters apply](../entities#global-filters) 200 | - **status** – ("created", "sent", "accepted", "partially_billed", "billed", "archived") 201 | - **from** – "2018-01-01" 202 | - **to** – "2018-01-31" 203 | - **identifier** – "A1903-003" 204 | - **deal_id** – "123,456" (deal ID for offers on this deal, single or comma-separated values) 205 | - **project_id** – "123,456" (project ID for offers on this project, single or comma-separated values) 206 | - **company_id** – "123,456" (company ID for offers on this project, single or comma-separated values) 207 | 208 | ## GET /offers/{id} 209 | 210 | Retrieve a single offer: 211 | 212 | ```bash 213 | curl -X GET \ 214 | 'https://{domain}.mocoapp.com/api/v1/offers/{id}' \ 215 | -H 'Authorization: Token token=YOUR_API_KEY' 216 | ``` 217 | 218 | This returns a single offer representation, including internal contact and positions. 219 | 220 | ## GET /offers/{id}.pdf 221 | 222 | Retrieve a single offer document: 223 | 224 | ```bash 225 | curl -X GET \ 226 | 'https://{domain}.mocoapp.com/api/v1/offers/{id}.pdf' \ 227 | -H 'Authorization: Token token=YOUR_API_KEY' 228 | ``` 229 | 230 | Additionally, the following parameters can be supplied: 231 | 232 | - **letter_paper_id** – (letter paper ID, default: White) 233 | 234 | This returns this offers's PDF document. 235 | 236 | ## POST /offers 237 | 238 | Create an offer: 239 | 240 | ```bash 241 | curl -X POST \ 242 | 'https://{domain}.mocoapp.com/api/v1/offers' \ 243 | -H 'Authorization: Token token=YOUR_API_KEY' \ 244 | -H 'Content-Type: application/json' \ 245 | -d '{ 246 | "deal_id": 123, 247 | "recipient_address": "Acme\r\nPark Avenue", 248 | "date": "2019-05-10", 249 | "due_date": "2019-06-08", 250 | "title": "Offer - Shop Locator", 251 | "salutation": "Hey", 252 | "tax": 8.0, 253 | "discount": 0.0, 254 | "footer": "Bye", 255 | "internal_contact_id": 1234, 256 | "items":[ 257 | {"type":"title","title":"Stunden"}, 258 | {"type":"description","description":"Aufstellung über geleistete Arbeiten"}, 259 | {"type":"item","title":"MailChimp Einrichtung","quantity":1,"unit":"Std","unit_price":100.0} 260 | ]}' 261 | ``` 262 | 263 | Mandatory fields are marked with a star (\*): 264 | 265 | - **company_id** – 123456 (ID of the associated company), is disregarded and set to the company of the project if project_id is provided 266 | - **deal_id** – 123456 (ID of the associated deal) 267 | - **project_id** – 123456 (ID of the associated project) 268 | - **recipient_address\*** – "My customer..." 269 | - **date\*** – "2018-09-17" 270 | - **due_date\*** – "2018-10-16" 271 | - **title\*** – "Offer" 272 | - **tax\*** – 8.0 273 | - **currency\** – "CHF" (a valid currency of the account), must match the currency of provided project and deal, only required if no company_id, deal_id and project_id is provided 274 | - **items\*** – positions (see [attributes](#attributes)) 275 | - **change_address** – address propagation ("offer", "customer"), default is "offer" 276 | - **salutation** (salutation text) 277 | - **footer** (footer text) 278 | - **discount** – 10 (discount in percent) 279 | - **contact_id** – 123456 (ID of the associated contact at customer) 280 | - **internal_contact_id** - 1234 (ID of an internal user) 281 | - **tags** – ["Retail"] 282 | - **custom_properties** – {"ext-ref": "3421"} 283 | - **print_detail_columns** - true (Hide/Display 'quantity, unit, price'). Optional property, which defaults to the global account layout setting 284 | 285 | ### Variables 286 | 287 | It's possible to use variables in the salutation and footer texts. Use curly braces like `{variable}` to use them: 288 | 289 | * `{salutation}` 290 | * `{date}` 291 | * `{due_date}` 292 | * `{due_days}` 293 | * `{invoice_due_days}` 294 | * `{recipient}` - full address 295 | * `{company_name}` 296 | * `{net_total}` 297 | * `{net_total_plus_options}` - including optional positions 298 | * `{tax}` 299 | * `{gross_total}` 300 | * `{title}` 301 | * `{identifier}` - offer number 302 | * `{me}` - current user full name 303 | * `{me_firstname}` 304 | * `{me_email}` 305 | * `{me_details}` - current user full name, email phone 306 | * `{user}` - creator full name 307 | * `{user_email}` 308 | * `{user_details}` - creator full name, email, phone 309 | * `{internal_contact}` - full name 310 | * `{internal_contact_email}` 311 | * `{internal_contact_details}` - full name, email, phone 312 | * `{signatur_image}` - email signature image 313 | * `{customer_approval_link}` - a URL to approve this offer - this activates the customer approval on this offer 314 | 315 | ## PUT /offers/{id}/assign 316 | 317 | Assign an offer to a company, project, and/or deal. 318 | 319 | ```bash 320 | curl -X PUT \ 321 | 'https://{domain}.mocoapp.com/api/v1/offers/{id}/assign' \ 322 | -H 'authorization: Token token=YOUR_API_KEY' \ 323 | -H 'Content-Type: application/json' \ 324 | -d '{ 325 | "company_id": 1234, 326 | "project_id": 2345, 327 | "deal_id": 3456 328 | }' 329 | ``` 330 | 331 | {: .note } 332 | If a `project_id` is set, the project's `company_id` is also set on this offer. If the company does not match the project's company, the project company overrides the given `company_id`. 333 | 334 | ## PUT /offers/{id}/update_status 335 | 336 | Update an offer status: 337 | 338 | ```bash 339 | curl -X PUT \ 340 | 'https://{domain}.mocoapp.com/api/v1/offers/{id}/update_status' \ 341 | -H 'authorization: Token token=YOUR_API_KEY' \ 342 | -H 'Content-Type: application/json' \ 343 | -d '{ 344 | "status": "billed" 345 | }' 346 | ``` 347 | 348 | The following states are valid: "created", "sent", "accepted", "partially_billed", "billed", "archived". 349 | 350 | ## POST /offers/{id}/send_email 351 | 352 | Send the offer by email: 353 | 354 | ```bash 355 | curl -X POST \ 356 | 'https://{domain}.mocoapp.com/api/v1/offers/{id}/send_email' \ 357 | -H 'Authorization: Token token=YOUR_API_KEY' \ 358 | -H 'Content-Type: application/json' \ 359 | -d '{ 360 | "emails_to": "somebody@example.com", 361 | "subject": "Offer", 362 | "text": "Kind regards" 363 | }' 364 | ``` 365 | 366 | Mandatory fields are marked with a star (\*): 367 | 368 | - **subject\*** – "Offer", 369 | - **text\*** – "Kind regards" 370 | - **emails_to** – "somebody@example.com;info@example.com" (list of addresses separated by _;_). To use default recipients, see information below. 371 | - **emails_cc** – "somebodyelse@example.com" (list of addresses separated by _;_) 372 | - **emails_bcc** – "somebody@partner.example.com" (list of addresses separated by _;_) 373 | 374 | 🛈 If you want to send emails to the default recipients configured on the customer or set as a contact, leave `emails_to`, `emails_cc` and `emails_bcc` empty. `emails_to` always needs to be provided, either via the default recipients or as a given value. In the response, the recipients selected are returned. 375 | 376 | ## GET /offers/{id}/attachments 377 | 378 | List all attachments for this offer: 379 | 380 | ```bash 381 | curl -X GET \ 382 | 'https://{domain}.mocoapp.com/api/v1/offers/{offer_id}/attachments' \ 383 | -H 'Authorization: Token token=YOUR_API_KEY' 384 | ``` 385 | 386 | Provide the payload base64 encoded. 387 | 388 | ## POST /offers/{id}/attachments 389 | 390 | Add attachment PDF to offer: 391 | 392 | ```bash 393 | curl -X POST \ 394 | 'https://{domain}.mocoapp.com/api/v1/offers/{id}/attachments' \ 395 | -H 'Authorization: Token token=YOUR_API_KEY' \ 396 | -H 'Content-Type: application/json' \ 397 | -d '{ 398 | "attachment": { 399 | "filename": "attachment.pdf", 400 | "base64": "JVBERi0xLjQKJeLjz9MKNCAwIG9iago8PC9GaWx..." 401 | } 402 | }' 403 | ``` 404 | 405 | Provide the payload base64 encoded. 406 | 407 | ## DELETE /offers/{offer_id}/attachments/{id} 408 | 409 | Remove attachment from offer: 410 | 411 | ```bash 412 | curl -X DELETE \ 413 | 'https://{domain}.mocoapp.com/api/v1/offers/{offer_id}/attachments/{id}' \ 414 | -H 'Authorization: Token token=YOUR_API_KEY' 415 | --------------------------------------------------------------------------------