Connecting NetSuite — pull Customers and Invoices into Turtini

The NetSuite connector mirrors your NetSuite Customers into Turtini Accounts and NetSuite Invoices into the AR ledger. It uses Token-Based Authentication (TBA) — no public OAuth app required and no interactive popup. You generate five credentials in your NetSuite org once, paste them into Turtini, and the sync runs on a schedule plus on-demand from there.

Before you connect — gather these in NetSuite:
1. Account ID (from Setup → Company → Company Information) — looks like `1234567` for production or `1234567_SB1` for a sandbox
2. Consumer Key + Consumer Secret — Setup → Integration → Manage Integrations → New, give it a name (e.g. "Turtini Sync"), check "Token-Based Authentication," save, copy both values
3. Token ID + Token Secret — Setup → Users/Roles → Access Tokens → New, pick the user, role, and integration you just created, save, copy both values

The role you bind the token to must have at least:
• Lists → Customers — View
• Transactions → Invoice / Find Transaction — View
• Setup → Web Services — Full (required for SuiteTalk REST)
• Setup → Log in using Access Tokens — Full

How to connect in Turtini:
1. Settings → Integrations → NetSuite card
2. Click "Connect NetSuite"
3. Paste all 5 values — Account ID, Consumer Key, Consumer Secret, Token ID, Token Secret
4. Click "Save + verify"
5. Turtini saves the secrets in Google Cloud Secret Manager (per-org entries) and runs a smoke-test ping against the SuiteTalk REST endpoint to confirm everything works
6. Once verified, the Connect view collapses into a Connected status with Account ID + last-sync timestamp visible

What mirrors over:
• NetSuite Customers → `accounts` (name, email, phone, billing address, ship address, subsidiary, terms)
• NetSuite Invoices → `arInvoices` (invoice number, date, due date, line items, totals, status — open/paid/overdue)
• Bills (Phase 3) — coming, currently disabled with a "Phase 3" pill in the UI

Sync cadence:
• Daily scheduled sync runs nightly
• "Sync now" on the integration card runs the same sync on demand
• Sync is idempotent — keyed on the NetSuite internalid; existing records update in place

Sync scope toggles:
Customers and Invoices each have a checkbox. Defaults are both on. Uncheck either to skip it on the next run — useful if you only want Customer data and you're using a different system for AR.

Why TBA and not OAuth:
TBA is NetSuite's preferred path for server-to-server integrations. It doesn't need an interactive Connected App approval flow, doesn't expire on a 1-hour cadence like NetSuite OAuth tokens, and lets your NetSuite admin scope the role precisely without going through OAuth 2.0 consent. Every credential lives in your org's Secret Manager entry — Turtini doesn't ship a shared NetSuite app and never sees a tenant other than yours.

Updating credentials:
Click "Update credentials" on the integration card to repaste any of the 5 values. The old secret-manager version is disabled (preserving the audit trail) and the new one becomes active.

Disconnect: clears all 5 secrets (disabled, not deleted, so audit history is preserved). Mirrored Customers + Invoices stay in Turtini with their NetSuite internalids intact so you can reconnect without losing the link.

Errors you might see:
• "InvalidLogin" — a Token ID/Secret mismatch or the role doesn't have Web Services permission
• "Permission Violation" — the role can see the integration record but not Customer / Invoice — adjust permissions in NetSuite and try again
• "Bad request" with no body — Account ID format is wrong (production uses just digits; sandboxes use `1234567_SB1`)