smartbill-invoicing

What This Skill Does

The smartbill-invoicing skill provides a robust, deterministic interface for interacting with the SmartBill.ro API within the OpenClaw environment. By utilizing the scripts/smartbill_cli.py utility, this skill abstracts the complexities of HTTP request handling, payload normalization, and API authentication. It is designed to safely bridge the gap between raw financial data and the SmartBill platform, ensuring that invoice generation is consistent, validated, and repeatable. The tool supports end-to-end invoice lifecycle management, including payload validation, series discovery, draft creation, final issuance, and PDF retrieval.

Installation

To integrate this skill into your environment, run the following command in your OpenClaw terminal: clawhub install openclaw/skills/skills/maverick-ai-tech/smartbill-invoicing

Ensure you have configured your environment variables before initiating any API requests. The essential variables include SMARTBILL_USERNAME and SMARTBILL_TOKEN. For production use, it is highly recommended to also set SMARTBILL_COMPANY_VAT_CODE to avoid repetitive inputs.

Use Cases

• Automated Billing: Automatically generate invoices based on task completion or project closure metadata without manual portal entry.
• Invoice Archiving: Programmatically fetch and store PDFs of issued invoices into local organizational folders for auditing purposes.
• Compliance Validation: Use the tool as a pre-processing step to ensure invoice payloads meet SmartBill schema requirements before attempted submission.
• Series Management: Programmatically list available invoice series to ensure correct document numbering and tax compliance when generating invoices for different departments or revenue streams.

Example Prompts

1. "Validate the invoice payload found in references/invoice-example.json and print the normalized structure."
2. "Create an invoice from data/client_invoice.json but only perform a dry-run to ensure the fields map correctly."
3. "Fetch the PDF for invoice series 'FACT' number '0052' and save it as reports/invoice_0052.pdf."

Tips & Limitations

Always use the --dry-run flag when creating new invoice templates to verify the data structure. When downloading PDFs, strictly adhere to the zero-padded string format (e.g., '0012') for invoice numbers, as failing to do so will result in an API error. The CLI automatically handles JSON wrapping; you do not need to worry if your input file is wrapped in an invoice object or is a flat JSON structure. Finally, please monitor your API usage logs, as repetitive failed requests due to misconfiguration may trigger SmartBill rate limiting policies.