API Documentation PlanningNow
A guide to integrating with our API.
Important Note on API Structure
This API is designed for managing orders, work schedules, and cost centres. Please be aware that the endpoints and data structures outlined in this documentation are definitive. External systems intending to integrate must adapt to the specified request and response formats, as the API structure will not be customized for individual integrations.
1. Create and Manage API Tokens
API tokens are managed on a per-user basis. Each user can have only one active API token. Follow these steps to create a token for a specific user:
Step 1: Navigate to User Management
First, go to
User Management
in your PlanningNow web app and select the user for whom you
want to generate or manage an API token.
Select the desired user account.
Step 2: Access API Key Settings
With the user selected, click on the
API Key
icon located in the right sidebar to open the token management
interface.
Click the icon to manage the user's API token.
Step 3: Generate a New Token
In the token management overview, click the "Add" button on the right to generate a new API token. If a token already exists, you may need to revoke it first.
The token management overview.
Step 4: Copy Your New Token
The newly generated token will be displayed. This is the only time the token will be shown. Copy it and store it in a secure location. If you lose the token, you will need to revoke it and generate a new one.
Your new API token.
2. Using Your API Token
To authenticate your requests, you must send the API token in the
HTTP header with every request. Use the header key
X-AUTH-TOKEN.
Example Header:
X-AUTH-TOKEN: your_personal_api_token_hereAPI Endpoints
Order Management
Retrieves a list of all order confirmations in the system. Returns the same full structure as GET /api/order/{id} for each order, including positions and tasks.
Example Response (200 OK):
[
{
"id": 3456,
"o_conf_date": "2025-08-15",
"employee_no": 101,
"zuHaenden": "Mr. Miller",
"addressfield_1": "Example Corp",
"customer_no": 1234,
"project_no": "PROJ-2025-Q3",
"netto": "8500.00",
"ges_netto": "8500.00",
"ges_rabatt": "0.00",
"pay_term_id": 1,
"pay_term_text": "Net 30 days",
"positions": [
{
"id": 1,
"pos_no": 1,
"article_number": "ART-001",
"article_desc": "Main Component Assembly",
"amount": "50.00",
"unit": "pcs",
"unit_price": "170.00",
"netto": "8500.00",
"tasks": [
{
"id": 101,
"kalk_id": 1,
"kalk_type": 1,
"cost_centre_name": "Assembly Line 1",
"activity_name": "Component Welding",
"min_ruest": "30.00",
"min_wage": "5.50"
}
]
}
]
}
]Retrieves the details of a specific order using its unique ID.
Example Response (200 OK):
{
"id": 4711,
"o_conf_date": "2025-09-11",
"employee_no": 101,
"zuHaenden": "Mr. Miller",
"customer_no": 1234,
"project_no": "PROJ-2025-Q4",
"netto": "1575.00",
"ges_netto": "1575.00",
"ges_rabatt": "0.00",
"pay_term_id": 1,
"pay_term_text": "Net 30 days",
"positions": [
{
"id": 1,
"pos_no": 1,
"article_number": "ART-001",
"article_desc": "Main Component Assembly",
"amount": "50.00",
"unit": "pcs",
"unit_price": "25.00",
"discount": "0.00",
"unit_price_disc": "25.00",
"netto": "1250.00",
"deliv_date": "2025-10-15",
"mwst_percent": "19.00",
"brutto": "1487.50",
"tasks": [
{
"id": 101,
"kalk_id": 1,
"kalk_type": 1,
"cost_centre_name": "Assembly Line 1",
"activity_name": "Component Welding",
"min_ruest": "30.00",
"min_wage": "5.50",
"min_masch": "7.20",
"production_start": "2025-09-20 08:00:00",
"production_end": "2025-09-20 16:30:00"
}
]
}
]
}Creates a new order with the data provided in the request body.
Example Request Body:
{
"o_conf_date": "2025-09-11",
"customer_no": 5678,
"project_no": "NEW-PROJ-01",
"subject": "Initial Prototype Order",
"delivery_date": "2025-11-01",
"positions": [
{
"pos_no": 1,
"article_number": "PROTO-X1",
"article_desc": "Prototype Mainframe",
"amount": "5.00",
"unit": "pcs",
"unit_price": "550.00",
"remarks": "Handle with care, urgent delivery."
}
]
}Updates an existing order. Any field of the order, its positions, or tasks can be updated.
Example Request Body:
{
"subject": "Q4 Production Run (Revised)",
"delivery_date": "2025-10-20",
"short_info": "Delivery date expedited per customer request."
}Permanently deletes an order from the system. This action cannot be undone.
Example Response (204 No Content):
On successful deletion, no body is returned.
Offer Management
Retrieves a list of all offers in the system. Returns the same full structure as GET /api/offer/{id} for each offer, including positions and tasks.
Example Response (200 OK):
[
{
"id": 2345,
"offer_date": "2025-09-05",
"employee_no": 101,
"zu_haenden": "Mr. Miller",
"customer_no": 1234,
"project_no": "PROJ-2025-Q3",
"lead_text": "Initial project proposal",
"netto": "2500.00",
"ges_netto": "2500.00",
"ges_rabatt": "0.00",
"pay_term_id": 1,
"pay_term_text": "Net 30 days",
"positions": [
{
"id": 1,
"pos_no": 1,
"article_number": "COMP-001",
"article_desc": "Main Component",
"amount": "25.00",
"unit": "pcs",
"unit_price": "100.00",
"netto": "2500.00",
"tasks": [
{
"id": 101,
"kalk_id": 1,
"kalk_type": 1,
"cost_centre_name": "Assembly Line 2",
"activity_name": "Component Assembly",
"min_ruest": "20.00",
"min_wage": "3.50"
}
]
}
]
}
]Retrieves the details of a specific offer using its unique ID.
Example Response (200 OK):
{
"id": 2345,
"offer_date": "2025-09-05",
"employee_no": 101,
"zu_haenden": "Mr. Miller",
"customer_no": 1234,
"project_no": "PROJ-2025-Q3",
"lead_text": "Initial project proposal",
"followup_text": "Follow-up discussion required",
"date_desired": "2025-10-01",
"delivery_date": "2025-10-15",
"netto": "2500.00",
"ges_netto": "2500.00",
"ges_rabatt": "0.00",
"info": "Special pricing for bulk order",
"pay_term_id": 1,
"pay_term_text": "Net 30 days",
"positions": [
{
"id": 1,
"pos_no": 1,
"article_number": "COMP-001",
"article_desc": "Main Component",
"amount": "25.00",
"unit": "pcs",
"unit_price": "100.00",
"discount": "0.00",
"unit_price_disc": "100.00",
"netto": "2500.00",
"deliv_date": "2025-10-15",
"mwst_percent": "19.00",
"brutto": "2975.00",
"tasks": [
{
"id": 101,
"kalk_id": 1,
"kalk_type": 1,
"cost_centre_name": "Assembly Line 2",
"activity_name": "Component Assembly",
"min_ruest": "20.00",
"min_wage": "3.50",
"min_masch": "5.00"
}
]
}
]
}Creates a new offer with the data provided in the request body.
Example Request Body:
{
"offer_date": "2025-09-25",
"customer_no": 9876,
"project_no": "NEW-OFFER-01",
"lead_text": "Initial consultation and proposal",
"delivery_date": "2025-11-30",
"pay_term_text": "Net 45 days",
"positions": [
{
"pos_no": 1,
"article_number": "SERV-X1",
"article_desc": "Consulting Services",
"amount": "20.00",
"unit": "hrs",
"unit_price": "125.00",
"remarks": "Senior consultant rate applies."
}
]
}Updates an existing offer. Any field of the offer, its positions, or tasks can be updated.
Example Request Body:
{
"lead_text": "Updated proposal with revised requirements",
"delivery_date": "2025-12-15",
"info": "Delivery date extended per customer request."
}Permanently deletes an offer from the system. This action cannot be undone.
Example Response (204 No Content):
On successful deletion, no body is returned.
Work Schedules
Retrieves a list of all work schedules. Returns the same structure as GET /api/work-schedule/{id} for each entry, including position IDs.
Example Response (200 OK):
[
{
"id": 101,
"name": "Standard Assembly Process",
"creation_date": "2025-01-10",
"sum_cost": "125.50",
"los_stueck": 1,
"wage_factor": 1,
"positions": [
{ "id": 201 }
]
},
{
"id": 102,
"name": "Finishing Process",
"creation_date": "2025-02-15",
"sum_cost": "85.00",
"los_stueck": 1,
"wage_factor": 1,
"positions": [
{ "id": 301 }
]
}
]Retrieves a specific work schedule. Note: positions currently only return their ID.
{
"id": 101,
"name": "Standard Assembly Process",
"creation_date": "2025-01-10",
"last_change_date": "2025-03-15",
"sum_min_ruest": "15.00",
"sum_min": "30.00",
"sum_cost_ruest": "10.00",
"sum_cost_wage": "25.00",
"sum_min_masch": "20.00",
"sum_cost_masch": "40.00",
"sum_cost_fremdfert": "0.00",
"sum_cost": "125.50",
"los_stueck": 1,
"sum_min_wage": "15.00",
"costperone": "125.50",
"hoursperday": "8.00",
"sum_min_setup": "10.00",
"sum_cost_setup": "5.00",
"wage_factor": 1,
"positions": [
{
"id": 201
}
]
}Creates a new work schedule.
{
"name": "Advanced Finishing Process",
"los_stueck": 1,
"wage_factor": 1,
"positions": [
{
"pos": 10,
"activity_name": "Sanding and Polishing",
"min_wage": "20.00"
}
]
}Updates an existing work schedule.
{
"name": "Standard Assembly Process (2025 Rev.)"
}Permanently deletes a work schedule.
Example Response (204 No Content):
On successful deletion, no body is returned.
Cost Centres
Retrieves a list of all cost centres. Returns the same structure as GET /api/cost-centre/{id} for each entry.
Example Response (200 OK):
[
{
"id": 1,
"name": "CNC Milling Dept.",
"type": 1,
"kalkMinKosten": "1.850",
"nutzungsdauer": "10.00",
"last_change": "2025-03-15 10:30:00",
"last_sync": "2025-03-15 10:30:00"
},
{
"id": 2,
"name": "Quality Assurance Lab",
"type": 2,
"kalkMinKosten": "2.150",
"nutzungsdauer": "8.00",
"last_change": "2025-03-10 14:00:00",
"last_sync": "2025-03-10 14:00:00"
}
]Retrieves a specific cost centre.
{
"id": 1,
"name": "CNC Milling Dept.",
"type": 1,
"kalkMinKosten": "1.850",
"nutzungsdauer": "10.00",
"last_change": "2025-03-15 10:30:00",
"last_sync": "2025-03-15 10:30:00"
}Creates a new cost centre.
{
"name": "Quality Assurance Lab",
"type": 2
}Updates an existing cost centre.
{
"kalk_min_kosten": "2.150"
}Permanently deletes a cost centre.
Example Response (204 No Content):
On successful deletion, no body is returned.
Document Management
Uploads a document file. The request must be sent as
multipart/form-data.
The file is stored in the document folder structure based on the
provided area and number.
Example Request (multipart/form-data):
Content-Type: multipart/form-data
file: (binary file data)
area: "order"
number: "4711"
external: false
folder_id: 5 (optional)Example Response (201 Created):
{
"success": true,
"document": {
"id": 42,
"area": "order",
"number": "4711",
"filename": "technical-drawing",
"filetype": "pdf",
"full_path": "/Dokutasche/order/4711/technical-drawing.pdf",
"creator": "api_user",
"creation_date": "2025-09-15",
"do_print": false,
"external": false,
"folder_id": 5,
"mimetype": "application/pdf"
},
"status_code": 201
}Retrieves a list of documents. Results can be filtered by area, number, and folder_id using query parameters.
Example: GET /api/documents?area=order&number=4711
Example Response (200 OK):
{
"success": true,
"documents": [
{
"id": 42,
"area": "order",
"number": "4711",
"filename": "technical-drawing",
"filetype": "pdf",
"full_path": "/Dokutasche/order/4711/technical-drawing.pdf",
"creator": "admin",
"creation_date": "2025-09-15",
"do_print": false,
"external": false,
"folder_id": 5,
"mimetype": "application/pdf"
},
{
"id": 43,
"area": "order",
"number": "4711",
"filename": "specification",
"filetype": "docx",
"full_path": "/Dokutasche/order/4711/specification.docx",
"creator": "admin",
"creation_date": "2025-09-16",
"do_print": true,
"external": false,
"folder_id": 5,
"mimetype": "application/vnd.openxmlformats-officedocument.wordprocessingml.document"
}
],
"count": 2,
"status_code": 200
}Retrieves the folder tree structure for documents. Can be filtered by area using a query parameter.
Example: GET /api/documents/structure?area=order
Example Response (200 OK):
{
"tree": [
{
"id": 1,
"name": "Alle",
"area": "order",
"parent_id": null,
"children": [
{
"id": 5,
"name": "Technical Drawings",
"area": "order",
"parent_id": 1,
"children": []
},
{
"id": 6,
"name": "Contracts",
"area": "order",
"parent_id": 1,
"children": []
}
]
}
],
"status_code": 200
}Permanently deletes a document from the system. Both the database record and the physical file are removed. This action cannot be undone.
Example Response (200 OK):
{
"success": true,
"message": "Document deleted successfully",
"status_code": 200
}Error Response (404):
{
"error": "Document not found",
"status_code": 404
}General
This endpoint is used to verify the correct authentication with the API token. On success, a confirmation message is returned.
Example Response (200 OK):
{
"response": "Test successfull."
}Returns a machine-readable JSON schema describing the general API documentation and available endpoints.
Example Response (200 OK):
Returns a JSON object with the general API documentation structure.
Returns a machine-readable JSON schema specifically for the order confirmation endpoints, describing available fields and their types.
Example Response (200 OK):
Returns a JSON object with the order confirmation documentation structure.