get_invoice
Retrieve detailed invoice data by specifying the invoice ID. Integrates with Norman Finance MCP Server to simplify accounting and tax workflows for entrepreneurs in Germany.
Instructions
Get detailed information about a specific invoice.
Args:
invoice_id: ID of the invoice to retrieve
Returns:
Detailed invoice informationInput Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| invoice_id | Yes |
Implementation Reference
- norman_mcp/tools/invoices.py:310-336 (handler)The main handler function for the 'get_invoice' tool. It retrieves detailed information about a specific invoice by making a GET request to the Norman API endpoint using the provided invoice_id.
@mcp.tool() async def get_invoice( ctx: Context, invoice_id: str ) -> Dict[str, Any]: """ Get detailed information about a specific invoice. Args: invoice_id: ID of the invoice to retrieve Returns: Detailed invoice information """ api = ctx.request_context.lifespan_context["api"] company_id = api.company_id if not company_id: return {"error": "No company available. Please authenticate first."} invoice_url = urljoin( config.api_base_url, f"api/v1/companies/{company_id}/invoices/{invoice_id}/" ) return api._make_request("GET", invoice_url) - norman_mcp/server.py:329-329 (registration)The call to register_invoice_tools(server) which registers all invoice-related tools, including 'get_invoice', with the MCP server.
register_invoice_tools(server) - norman_mcp/tools/invoices.py:12-553 (registration)The register_invoice_tools function that defines and registers the 'get_invoice' tool (and other invoice tools) using @mcp.tool() decorators.
def register_invoice_tools(mcp): """Register all invoice-related tools with the MCP server.""" @mcp.tool() async def create_invoice( ctx: Context, client_id: str, items: list[dict], invoice_number: Optional[str] = None, issued: Optional[str] = None, due_to: Optional[str] = None, currency: str = "EUR", payment_terms: Optional[str] = None, notes: Optional[str] = None, language: str = "en", invoice_type: str = "SERVICES", is_vat_included: bool = False, bank_name: Optional[str] = None, iban: Optional[str] = None, bic: Optional[str] = None, create_qr: bool = False, color_schema: str = "#FFFFFF", font: str = "Plus Jakarta Sans", is_to_send: bool = False, mailing_data: Optional[Dict[str, str]] = None, settings_on_overdue: Optional[Dict[str, Any]] = None, service_start_date: Optional[str] = None, service_end_date: Optional[str] = None, delivery_date: Optional[str] = None, ) -> Dict[str, Any]: """ Create a new invoice. Ask for additional information if needed, for example: - If the client is not found, ask for the client details and create a new client if necessary. - If pyament reminder should be sent, ask for the reminder settings. - If the invoice type is GOODS, ask for the delivery date. - If the invoice type is SERVICES, ask for the service start and end dates. - If the invoice should be sent to the client, ask for the email data. Args: client_id: ID of the client for the invoice items: List of invoice items, each containing name, quantity, rate, vatRate and total. Example: [{"name": "Software Development", "quantity": 3, "rate": 30000, "vatRate": 19, "total": 1071}] // VAT rates might be 0, 7, 19. By default it's 19. Rate and total are in cents. invoice_number: Optional invoice number (will be auto-generated if not provided) issued: Issue date in YYYY-MM-DD format due_to: Due date in YYYY-MM-DD format currency: Invoice currency (EUR, USD), by default it's EUR payment_terms: Payment terms text notes: Additional notes language: Invoice language (en, de) invoice_type: Type of invoice (SERVICES, GOODS) is_vat_included: Whether prices include VAT bank_name: Name of the bank (gets from company details if exists) iban: IBAN for payments (gets from company details if exists) bic: BIC/SWIFT code (gets from company details if exists) create_qr: Whether to create payment QR code (only if BIC and IBAN provided) color_schema: Invoice style color (hex code) font: Invoice font (e.g. "Plus Jakarta Sans", "Inter") is_to_send: Whether to send invoice automatically to client mailing_data: Email data if is_to_send is True. Example: { "emailSubject": "Invoice No.{invoice_number} for {client_name}", "emailBody": "Dear {client_name},...", "customClientEmail": "client@example.com" // email to send the invoice to, if not provided, it will be sent to the client email address } settings_on_overdue: Configuration for overdue notifications. Example: { "isToAutosendNotification": true, // whether to send notification automatically "customEmailSubject": "Reminder: Invoice {invoice_number} is overdue", // custom email subject "customEmailBody": "Dear {client_name},...", // custom email body "notifyAfterDays": [1, 3], // days to notify after the due date "notifyInParticularDays": [] // days to notify in particular dates [2025-05-23", "2025-05-24"] } service_start_date: Service period start date (YYYY-MM-DD) by default it's today, should be provided if invoice_type is SERVICES service_end_date: Service period end date (YYYY-MM-DD) by default it's one month from today, should be provided if invoice_type is SERVICES delivery_date: Delivery date for goods (YYYY-MM-DD) by default it's today, should be provided if invoice_type is GOODS Returns: Information about the created invoice and always include the generated invoice pdf url from reportUrl field """ api = ctx.request_context.lifespan_context["api"] company_id = api.company_id if not company_id: return {"error": "No company available. Please authenticate first."} # Use current date if not provided if not issued: issued = datetime.now().strftime("%Y-%m-%d") invoices_url = urljoin( config.api_base_url, f"api/v1/companies/{company_id}/invoices/" ) # Get next invoice number if not provided if not invoice_number: next_invoice_url = urljoin( config.api_base_url, f"api/v1/companies/{company_id}/invoices/next-invoice-number/" ) next_invoice_data = api._make_request("GET", next_invoice_url) invoice_number = next_invoice_data.get("nextInvoiceNumber") # Prepare invoice data invoice_data = { "client": client_id, "invoiceNumber": invoice_number, "issued": issued, "invoicedItems": items, "currency": currency, "language": language, "invoiceType": invoice_type, "isVatIncluded": is_vat_included, "createQr": create_qr, "isToSend": is_to_send, "type": "invoice", "companyId": company_id, "companyEmail": config.NORMAN_EMAIL } # Add optional fields if provided invoice_data["dueTo"] = due_to if due_to else (datetime.now() + timedelta(days=30)).strftime("%Y-%m-%d") invoice_data["paymentTerms"] = payment_terms if payment_terms else "" invoice_data["notes"] = notes if notes else "" invoice_data["bankName"] = bank_name if bank_name else "" invoice_data["iban"] = iban if iban else "" invoice_data["bic"] = bic if bic else "" invoice_data["colorSchema"] = color_schema invoice_data["font"] = font if mailing_data and is_to_send: invoice_data["mailingData"] = mailing_data if settings_on_overdue: invoice_data["settingsOnOverdue"] = settings_on_overdue else: invoice_data["settingsOnOverdue"] = {"isToAutosendNotification": False} if invoice_type == "SERVICES": invoice_data["serviceStartDate"] = service_start_date if service_start_date else datetime.now().strftime("%Y-%m-%d") invoice_data["serviceEndDate"] = service_end_date if service_end_date else (datetime.now() + timedelta(days=30)).strftime("%Y-%m-%d") if invoice_type == "GOODS": invoice_data["deliveryDate"] = delivery_date if delivery_date else datetime.now().strftime("%Y-%m-%d") return api._make_request("POST", invoices_url, json_data=invoice_data) @mcp.tool() async def create_recurring_invoice( ctx: Context, client_id: str, items: list[dict], frequency_type: str, frequency_unit: int, starts_from_date: str, ends_on_date: Optional[str] = None, ends_on_invoice_count: Optional[int] = None, invoice_number: Optional[str] = None, issued: Optional[str] = None, due_to: Optional[str] = None, currency: str = "EUR", payment_terms: Optional[str] = None, notes: Optional[str] = None, language: str = "en", invoice_type: str = "SERVICES", is_vat_included: bool = False, bank_name: Optional[str] = None, iban: Optional[str] = None, bic: Optional[str] = None, create_qr: bool = False, color_schema: str = "#FFFFFF", font: str = "Plus Jakarta Sans", is_to_send: bool = False, settings_on_overdue: Optional[Dict[str, Any]] = None, service_start_date: Optional[str] = None, service_end_date: Optional[str] = None, delivery_date: Optional[str] = None, ) -> Dict[str, Any]: """ Create a recurring invoice that will automatically generate new invoices based on specified frequency. Useful for contracts or services that bill on a regular basis. Always ask for reccurring configuration, for example: - How often to generate invoices (weekly, monthly) - Number of units for frequency (e.g. 1 for monthly = every month, 2 = every 2 months) - Start date - End date - End invoice count (optional) Ask for additional information if needed, for example: - If the client is not found, ask for the client details and create a new client if necessary. - If the invoice number is not provided, ask for it. - If the due date is not provided, ask for it. - If the payment terms are not provided, ask for it. - If the bank details are not provided, ask for it. Args: client_id: ID of the client for the invoice items: List of invoice items, each containing name, quantity, rate, vatRate and total frequency_type: How often to generate invoices ("weekly", "monthly") frequency_unit: Number of units for frequency (e.g. 1 for monthly = every month, 2 = every 2 months) starts_from_date: Date to start generating invoices from (YYYY-MM-DD) ends_on_date: Optional end date for recurring invoices (YYYY-MM-DD). Either ends_on_date or ends_on_invoice_count should be provided. ends_on_invoice_count: Optional number of invoices to generate before stopping. Either ends_on_date or ends_on_invoice_count should be provided. invoice_number: Base invoice number (will be auto-generated if not provided) issued: Issue date in YYYY-MM-DD format due_to: Due date in YYYY-MM-DD format currency: Invoice currency (EUR, USD), by default it's EUR payment_terms: Payment terms text notes: Additional notes language: Invoice language (en, de) invoice_type: Type of invoice (SERVICES, GOODS) is_vat_included: Whether prices include VAT bank_name: Name of the bank iban: IBAN for payments bic: BIC/SWIFT code create_qr: Whether to create payment QR code color_schema: Invoice style color (hex code) font: Invoice font (e.g. "Plus Jakarta Sans", "Inter") is_to_send: Whether to send invoices automatically to client settings_on_overdue: Configuration for overdue notifications service_start_date: Service period start date (for SERVICES type) service_end_date: Service period end date (for SERVICES type) delivery_date: Delivery date (for GOODS type) Returns: Information about the created recurring invoice setup and always include the generated invoice pdf url from reportUrl field """ api = ctx.request_context.lifespan_context["api"] company_id = api.company_id if not company_id: return {"error": "No company available. Please authenticate first."} if not issued: issued = starts_from_date recurring_invoices_url = urljoin( config.api_base_url, f"api/v1/companies/{company_id}/recurring-invoices/" ) # Get next invoice number if not provided if not invoice_number: next_invoice_url = urljoin( config.api_base_url, f"api/v1/companies/{company_id}/invoices/next-invoice-number/" ) next_invoice_data = api._make_request("GET", next_invoice_url) invoice_number = next_invoice_data.get("nextInvoiceNumber") # Prepare recurring invoice data invoice_data = { "client": client_id, "invoiceNumber": invoice_number, "recurringNumber": invoice_number, "issued": issued, "invoicedItems": items, "currency": currency, "language": language, "invoiceType": invoice_type, "isVatIncluded": is_vat_included, "createQr": create_qr, "isToSend": is_to_send, "isRecurring": True, "frequencyType": frequency_type, "frequencyUnit": frequency_unit, "startsFromDate": starts_from_date, "type": "invoice", "companyId": company_id, "companyEmail": config.NORMAN_EMAIL } # Add conditional end parameters if ends_on_date: invoice_data["endsOnDate"] = ends_on_date if ends_on_invoice_count: invoice_data["endsOnInvoiceCount"] = ends_on_invoice_count if not ends_on_date and not ends_on_invoice_count: invoice_data["endsOnInvoiceCount"] = 3 # Add optional fields invoice_data["dueTo"] = due_to if due_to else (datetime.strptime(issued, "%Y-%m-%d") + timedelta(days=30)).strftime("%Y-%m-%d") invoice_data["paymentTerms"] = payment_terms if payment_terms else "" invoice_data["notes"] = notes if notes else "" invoice_data["bankName"] = bank_name if bank_name else "" invoice_data["iban"] = iban if iban else "" invoice_data["bic"] = bic if bic else "" invoice_data["colorSchema"] = color_schema invoice_data["font"] = font if settings_on_overdue: invoice_data["settingsOnOverdue"] = settings_on_overdue else: invoice_data["settingsOnOverdue"] = {"isToAutosendNotification": False} if invoice_type == "SERVICES": invoice_data["serviceStartDate"] = service_start_date if service_start_date else starts_from_date invoice_data["serviceEndDate"] = service_end_date if service_end_date else (datetime.strptime(starts_from_date, "%Y-%m-%d") + timedelta(days=30)).strftime("%Y-%m-%d") if invoice_type == "GOODS": invoice_data["deliveryDate"] = delivery_date if delivery_date else starts_from_date return api._make_request("POST", recurring_invoices_url, json_data=invoice_data) @mcp.tool() async def get_invoice( ctx: Context, invoice_id: str ) -> Dict[str, Any]: """ Get detailed information about a specific invoice. Args: invoice_id: ID of the invoice to retrieve Returns: Detailed invoice information """ api = ctx.request_context.lifespan_context["api"] company_id = api.company_id if not company_id: return {"error": "No company available. Please authenticate first."} invoice_url = urljoin( config.api_base_url, f"api/v1/companies/{company_id}/invoices/{invoice_id}/" ) return api._make_request("GET", invoice_url) @mcp.tool() async def send_invoice( ctx: Context, invoice_id: str, subject: str, body: str, additional_emails: Optional[List[str]] = None, is_send_to_company: bool = False, custom_client_email: Optional[str] = None ) -> Dict[str, Any]: """ Send an invoice via email. Args: invoice_id: ID of the invoice to send subject: Email subject line body: Email body content additional_emails: List of additional email addresses to send to is_send_to_company: Whether to send the copy to the company email (Owner) custom_client_email: Custom email address for the client (By default the email address of the client is used if it is set) Returns: Response from the send invoice request """ api = ctx.request_context.lifespan_context["api"] company_id = api.company_id if not company_id: return {"error": "No company available. Please authenticate first."} send_url = urljoin( config.api_base_url, f"api/v1/companies/{company_id}/invoices/{invoice_id}/send/" ) send_data = { "subject": subject, "body": body, "isSendToCompany": is_send_to_company } if additional_emails: send_data["additionalEmails"] = additional_emails if additional_emails else [] if custom_client_email: send_data["customClientEmail"] = custom_client_email return api._make_request("POST", send_url, json_data=send_data) @mcp.tool() async def send_invoice_overdue_reminder( ctx: Context, invoice_id: str, subject: str, body: str, additional_emails: Optional[List[str]] = None, is_send_to_company: bool = False, custom_client_email: Optional[str] = None ) -> Dict[str, Any]: """ Send an overdue payment reminder for an invoice via email. Args: invoice_id: ID of the invoice to send reminder for subject: Email subject line body: Email body content additional_emails: List of additional email addresses to send to is_send_to_company: Whether to send the copy to the company email (Owner) custom_client_email: Custom email address for the client (By default the email address of the client is used if it is set) Returns: Response from the send overdue reminder request """ api = ctx.request_context.lifespan_context["api"] company_id = api.company_id if not company_id: return {"error": "No company available. Please authenticate first."} send_url = urljoin( config.api_base_url, f"api/v1/companies/{company_id}/invoices/{invoice_id}/send-on-overdue/" ) send_data = { "subject": subject, "body": body, "isSendToCompany": is_send_to_company } if additional_emails: send_data["additionalEmails"] = additional_emails if additional_emails else [] if custom_client_email: send_data["customClientEmail"] = custom_client_email return api._make_request("POST", send_url, json_data=send_data) @mcp.tool() async def link_transaction( ctx: Context, invoice_id: str, transaction_id: str ) -> Dict[str, Any]: """ Link a transaction to an invoice. Args: invoice_id: ID of the invoice transaction_id: ID of the transaction to link Returns: Response from the link transaction request """ api = ctx.request_context.lifespan_context["api"] company_id = api.company_id if not company_id: return {"error": "No company available. Please authenticate first."} link_url = urljoin( config.api_base_url, f"api/v1/companies/{company_id}/invoices/{invoice_id}/link-transaction/" ) link_data = { "transaction": transaction_id } return api._make_request("POST", link_url, json_data=link_data) @mcp.tool() async def get_einvoice_xml( ctx: Context, invoice_id: str ) -> Dict[str, Any]: """ Get the e-invoice XML for a specific invoice. Args: invoice_id: ID of the invoice to get XML for Returns: E-invoice XML data """ api = ctx.request_context.lifespan_context["api"] company_id = api.company_id if not company_id: return {"error": "No company available. Please authenticate first."} xml_url = urljoin( config.api_base_url, f"api/v1/companies/{company_id}/invoices/{invoice_id}/xml/" ) try: response = requests.get( xml_url, headers={"Authorization": f"Bearer {api.access_token}"}, timeout=config.NORMAN_API_TIMEOUT ) response.raise_for_status() # Return the XML content as a string return {"xml_content": response.text} except requests.exceptions.RequestException as e: logger.error(f"Failed to get e-invoice XML: {str(e)}") if hasattr(e, 'response') and e.response is not None: logger.error(f"Response: {e.response.text}") return {"error": f"Failed to get e-invoice XML: {str(e)}"} @mcp.tool() async def list_invoices( ctx: Context, status: Optional[str] = None, name: Optional[str] = None, from_date: Optional[str] = None, to_date: Optional[str] = None, limit: Optional[int] = 100 ) -> Dict[str, Any]: """ List invoices with optional filtering. Args: status: Filter by invoice status (draft, pending, sent, paid, overdue, uncollectible) name: Filter by invoice (client) name from_date: Filter invoices created after this date (YYYY-MM-DD) to_date: Filter invoices created before this date (YYYY-MM-DD) limit: Maximum number of invoices to return (default 100) Returns: List of invoices matching the criteria """ api = ctx.request_context.lifespan_context["api"] company_id = api.company_id if not company_id: return {"error": "No company available. Please authenticate first."} invoices_url = urljoin( config.api_base_url, f"api/v1/companies/{company_id}/invoices/" ) # Build query parameters params = {} if status: params["status"] = status if from_date: params["dateFrom"] = from_date if to_date: params["dateTo"] = to_date if limit: params["limit"] = limit if name: params["name"] = name return api._make_request("GET", invoices_url, params=params)