n8n-nodes-sphere
v0.1.0
Published
n8n community node for Sphere: real-time tax calculation, customers, products, transactions and transaction exports
Maintainers
Readme
n8n-nodes-sphere
This is an n8n community node for Sphere, the indirect tax platform for sales tax, VAT and GST. Use it to calculate tax in real time inside a billing or checkout workflow, record the finalized invoices and credit notes Sphere reports and files on, and export transactions with their tax breakdown as CSV.
n8n is a fair-code licensed workflow automation platform.
Installation · Credentials · Operations · Things to know · Development
Installation
Follow the installation guide in the n8n community nodes documentation and install n8n-nodes-sphere.
Credentials
Create an API key in Sphere under Settings > API Keys, or ask Sphere support for one. Keys start with sph_. Paste it into a Sphere API credential.
The credential test sends an empty tax calculation: Sphere answers a valid key with a validation error and an invalid one with unauthorized_access, so nothing is created. Customers, products and transactions need a key that Sphere has provisioned for the Transaction API; a key without it gets a 403 on those operations only.
Operations
| Resource | Operations | | --- | --- | | Tax | Calculate | | Transaction | Create or Update, Get, Cancel | | Customer | Create or Update, Get | | Product | Create or Update, Get | | Export | Create, Get, Cancel |
- Tax > Calculate returns the tax per line and jurisdiction, a
sphere_tax_calculation_idto store on the invoice or payment, andtotal_tax_amount, the tax summed over every line. Nothing is recorded. - Transaction > Create or Update records an invoice or credit note, as a pending draft or finalized. Finalizing runs the tax engine and returns subtotal, tax, total and an invoice link. Pass a
sphere_tax_calculation_idto commit the exact tax quoted earlier instead of recalculating. - Export > Create starts a CSV export. Turn on Wait for Completion to poll until it is ready and Download File to attach the CSV as binary data.
Line items can be entered in the form or passed as a JSON array, which is how the lines of an invoice from an earlier node get mapped in.
Things to know
- Two amount formats. Tax > Calculate takes whole numbers in the smallest currency unit (
10000is 100.00 EUR). Transactions take decimal strings in the main unit ("100.00"). The node labels each. - External IDs are the keys. Sphere has no list endpoints. Every record is created and fetched by the
external_idyou choose, and re-sending the same ID updates the record instead of creating a duplicate. - No tax is not an error. An empty
tax_amountsmeans no tax is due: no registration for the location, an exempt customer or product, or a reverse charge. Turn on Include Taxability Reason to see which. - Products need a tax code. Tax > Calculate fails with
invalid_product_tax_codefor a product without one. Set it in Sphere's Products tab or with Product > Create or Update. - Rate limits. 10 writes and 50 reads per second per key; at most 3 exports running at once.
Compatibility
Built with @n8n/node-cli 0.54. Requires n8n 1.x or later with n8nNodesApiVersion 1.
Development
npm install
npm run dev # runs n8n with the node linked, rebuilding on changes
npm run lint # n8n community node rules
npm test # description and helper tests
npm run buildThe tests check every operation against Sphere's API reference: each URL and method must exist, and each body field the node sends, line item fields included, must be one the endpoint accepts. Sphere publishes the reference as OpenAPI fragments on each docs page; refresh the merged fixture with:
npm run sync:openapiResources
- n8n community nodes documentation
- Sphere Tax Calculation API
- Sphere Transaction API
- Sphere Transaction Export
