PCE AP Write API — Technical & Testing Guide (Internal)

1. Service overview

1.1 Actions

This package accepts only the three actions above. stageApIntake, updateApIntake, createPurchaseReq, and updatePurchaseReq return INVALID_ACTION. API intake review and purchase requests are not in this package.

Supported transaction types: vendorbill \| expensereport \| vendorcredit \| vendorprepayment.

2. Code layout

ap/
  restlets/
    PCE_RL_AP_Write.js          # RESTlet entry (writes API call log each request)
  suitelets/
    PCE_SL_ApWriteSmoke.js      # AP Write smoke Suitelet
    PCE_SL_AP_CsvImport.js      # CSV import Suitelet (POST→GET PRG)
  libraries/
    PCE_LIB_AP_CsvImportReplay.js  # replay CSV result UI from write log
    PCE_LIB_AP_WriteReturnCode.js  # returnCode mapping and applyReturnCode
    PCE_LIB_AP_WritePayload.js  # action / shape / alias normalization
    PCE_LIB_AP_InvoiceSave.js   # validate and save the official AP invoice
    PCE_LIB_AP_WriteDfo.js      # no-op in the public package; a customer branch replaces it
    PCE_LIB_AP_Validate.js      # AP business rules (MOF-aligned)
    PCE_LIB_AP_Lookup.js        # format / tax / deduction / track code↔id
    PCE_LIB_AP_Period.js        # ROC YYYMM / filing period
    PCE_LIB_AP_WriteLog.js      # persist customrecord_pce_ap_write_log
    PCE_AP_Fields.js            # field script id constants
  clientscripts/                # UI (separate from this API)
  userevents/
    PCE_UE_APInvoice_DefaultValues.js  # beforeSubmit → Validate
  common/
    PCE_LIB_TaxId.js            # Taiwan tax ID check (used by Validate)

2.0 API call log (customrecord_pce_ap_write_log)

Every POST (and rejected GET) creates one log row after the handler finishes. Log write failures are recorded only in the Execution Log and do not change the API response.

UI: Lists → Custom → PCE AP Write 呼叫紀錄. After deploy, grant the integration role Create on this custom record.

2.1 POST flow

flowchart TD
  A[POST body] --> B[validatePayloadShape]
  B -->|invalid| F[fail shape error]
  B -->|valid| C{action}
  C -->|apInvoiceOnly| D[normalize + validate + create invoices]
  C -->|transactionOnly| E[resolveOrCreateTransaction]
  C -->|transactionWithApInvoices| G[resolveOrCreateTransaction]
  G --> D2[normalize + validate + create invoices with parent]
  D --> H[ok + warnings]
  E --> H
  D2 --> H
  D -->|validate error| X[fail PCE_AP_INVOICE_VALIDATION_ERROR]
  D2 -->|validate error| X

流程圖原文

resolveOrCreateTransaction: if transaction.id is set, load the existing record; else if type=vendorbill and purchaseOrderId is set, record.transform (purchaseorder → vendorbill) and overwrite quantities from itemLines[].orderline / quantity (unlisted PO lines → quantity 0); otherwise use existing record.create + fields/lines.

2.2 Dual validation gates

1. RESTlet: buildValidatedInvoiceData → validateRecord; no save on failure.
2. UE: On record.save, beforeSubmit validates again (CSV / WS / UI / RESTLET depending on deployment context).

Field rules (required, forbidden, one-of, tax tolerance, track, period, error codes) are in AP validation rules.

Select fields (format / tax type / deduction / summary mark) accept a business code (e.g. "21") or an internal id, resolved via resolveSelectValue + Lookup. AP formats 21 and 25 each have two lookup rows; send invCatCode or docFormatName when using the code alone.

3. Deployment & environment

3.1 SDF / SuiteCloud

• Script object: src/Objects/Scripts/customscript_pce_rl_ap_write.xml
• FileCabinet: ap/restlets/, ap/suitelets/, ap/libraries/* (see deploy.xml)
• After deploy, confirm Script Deployment Released and isdeployed = T

3.2 Permissions & integration

3.3 External URL

Customization → Scripting → Script Deployments → PCE RL AP Write → copy External URL.

https://{accountId}.restlets.api.netsuite.com/app/site/hosting/restlet.nl?script={scriptId}&deploy={deployId}

Account ID and numeric script/deploy IDs are environment-specific (scriptid strings ≠ URL numeric IDs).

4. Error codes (technical)

Implementation: ap/libraries/PCE_LIB_AP_WriteReturnCode.js; RESTlet ok() / fail() and the end of enrichResponseWithRequest() call applyReturnCode().

4.0 returnCode ranges

4.1 Payload shape (before business try)

1020–1027 are reserved for API intake review and purchase requests. This package does not return them.

4.2 Runtime (catch → fail)

Partial success: processApInvoices / multi-transaction loops catch per item and continue. findSuccessfulWriteByRequestId also treats returnCode=0004 / partialSuccess as committed to avoid duplicate creates on retry.

Response shape always includes returnCode / returnMessage:

{
  "success": false,
  "returnCode": "2001",
  "returnMessage": "AP_INVOICE_VALIDATION_FAILED",
  "error": {
    "code": "PCE_AP_INVOICE_VALIDATION_ERROR",
    "message": "...",
    "details": null
  }
}

5. Testing strategy

5.1 Unit tests (local, no NetSuite)

npm test
npm run test:ap-validate
npm run test:ap-write-payload
npm run test:ap-csv

Contract changes: update PCE_LIB_AP_WritePayload.js + unit tests first, then RESTlet and docs.

5.2 Account smoke tests (consultants / QA)

1. GET → expect success: false, error.code: PCE_METHOD_NOT_ALLOWED (GET is not allowed).
2. POST validateOnly: true + valid apInvoiceOnly → no new records.
3. POST bad tax ID / track → PCE_AP_INVOICE_VALIDATION_ERROR + details.
4. POST real apInvoiceOnly write → confirm in UI.
5. POST transactionWithApInvoices → confirm VB/ER/VC/Prepayment parent + child list.
6. Attach a second invoice via existing transaction.id → verify 1:N.
7. (Optional) With a usable PO: vendorbill + purchaseOrderId + itemLines[].orderline / quantity → confirm partial billing and unlisted lines at quantity 0.

5.3 Postman / curl

• Import docs/postman/PCE-AP-Write.postman_collection.json
• Run 0. Auth → Get Access Token first; collection auth = Bearer {{accessToken}}
• M2M JWT helper: docs/postman/generate-client-assertion.js
• Content-Type: application/json
• validateOnly on transactionOnly checks shape only, not NetSuite transaction mandatories

5.4 Test data checklist

• [x] Lookup: formats 21–29, tax type, deduction, summary mark (Round C)
• [x] Track table populated for period/format (11508 / format 21: CA, CB)
• [x] Vendor / subsidiary / account (Round C fixtures)
• [x] UE deployed with RESTLET execution context
• [x] Client scripts do not affect RESTlet path (expected; RESTlet writes OK)

5.5 Account smoke results (transactionOnly)

Account: TD2905095 (Chesley's Dev Environment). RESTlet: customscript_pce_rl_ap_write / customdeploy_pce_rl_ap_write. Action: transactionOnly (records actually created). Primary fixtures: Vendor 944 (Lancome), Subsidiary 8 (US East), Employee 1086, Expense account 415, Bank 422, Currency 1, Location 11.

Round A — SDF Installation smoke (2026-08-04)

Raw JSON: test/results/ap-write-smoke-result.json

Round B — Browser MCP + Suitelet smoke (2026-08-04)

Entry: /app/site/hosting/scriptlet.nl?script=customscript_pce_sl_ap_write_smoke&deploy=customdeploy_pce_sl_ap_write_smoke&action=run (Suitelet calls the production AP Write RESTlet via https.requestRestlet under the logged-in session.)

Raw JSON: test/results/ap-write-browser-smoke-result.json

Round C — Browser MCP full checklist §5.2 (2026-08-04)

Entry: …&action=checklist Local unit tests: npm test → 49/49 Pass.

JSON: test/results/ap-write-checklist-result.json

Fixes during test: checkbox fileBizTax as boolean; docDate parsed via N/format to Date.

Notes

• GET is not allowed; expect PCE_METHOD_NOT_ALLOWED (use docs + validateOnly POST instead of a health GET).
• Vendor Prepayment needs a Bank account (not AP); set account / payment after subsidiary / entity (sourcing clears early values).
• Smoke Suitelet must skip vendors with internal id ≤ 0 (e.g. -3) or NetSuite returns INVALID_FLD_VALUE.

6. Troubleshooting

Execution Log keywords: PCE AP Write RESTlet failed, PCE AP Write log failed. Prefer PCE AP Write 呼叫紀錄 Request/Response when debugging.

7. Known limitations

1. Transaction fields are not PCE-validated (including custom fields) — keys under transaction.fields / expenseLines / itemLines go straight to setValue / setCurrentSublistValue with no whitelist. Standard and custom fields (custbody_ / custcol_, etc.) are pass-through; mandatories, types, and permissions are enforced by NetSuite / the customer’s form. See integration guide §6.0.
2. transactionOnly + validateOnly — shape only.
3. Existing AP invoices stay unchanged. id / externalId on an invoice payload are ignored. This API does not update a PCE AP invoice that already exists.
4. No delete/void via this API.
5. Duplicate invoice concurrency — Validate checks duplicates; race possible under load.
6. requestId idempotency — looks up successful writes in the call log; custom records have no true unique constraint, so extreme concurrent same-requestId races remain possible (serial retries + UUID are fine in practice).
7. Legacy script rename — retire old BPM-named deployments if present; use customscript_pce_rl_ap_write.

8. Change impact (consultants)

9. Related assets

Document version aligned with SuiteApp com.netsuite.pceguitw AP Write RESTlet.