@timbro/payments 0.1.0-next.1 → 0.1.0-next.2

package/README.md

@@ -1,6 +1,12 @@
 # `@timbro/payments`
 
-Node 24 ESM SDK for merchant Payments and their payment-linked fiscal documents.
+Node 24 ESM SDK for merchant Payments, their payment-linked fiscal documents, and the merchant
+business that onboards them.
+
+`apiKey` takes either merchant key. A secret key (`sk_test_…` or `sk_live_…`) creates and reads
+Payments; an administrator key, which the owner creates and names in the Workspace business
+settings, also administers the business and its Merchant Accounts. Keys are additive: creating another one,
+of either kind, never retires the keys you already use.
 
 Each Payment create request supplies one immutable `source` coordinate and one tagged `sale` snapshot. `source.id` and `source.version` remain stable across credential rotation and retries; `idempotencyKey` remains the HTTP command retry key.
 
@@ -13,7 +19,7 @@ Use `amount_only` when the adapter has only a payable amount. This variant canno
 ```ts
 import { createTimbroPayments } from "@timbro/payments";
 
-const timbro = createTimbroPayments({ secretKey: process.env.TIMBRO_PAYMENTS_SECRET_KEY });
+const timbro = createTimbroPayments({ apiKey: process.env.TIMBRO_PAYMENTS_SECRET_KEY });
 const payment = await timbro.payments.create({
   idempotencyKey: "create-order-123",
   source: { id: "odoo:pos.order:123", version: "7" },
@@ -166,13 +172,96 @@ CardNet Ztrans full refunds are implemented for test mode with deterministic rec
 
 Before collecting the rest of a merchant's onboarding details, verify its RNC
 against the current DGII directory snapshot. The operation is read-only and
-returns the canonical taxpayer name for the form to use. It currently requires
-an existing merchant secret key; tenant bootstrap and human administrator
-authentication are separate onboarding work:
+returns the canonical taxpayer name for the form to use. Either merchant key
+calls it:
 
 ```ts
 const verification = await timbro.merchantOnboarding.verifyRnc({ rnc: "101000155" });
 // verification.legalName is the Directory's registered name.
 ```
 
+## Onboard the merchant business
+
+The business belongs to the key's tenant, so no call names it. Claiming the business and handing
+over the certificate file stay with the person who holds them; everything else is one resource.
+Read it, act on the first requirement your integration owns, and read it again:
+
+```ts
+const admin = createTimbroPayments({ apiKey: process.env.TIMBRO_ADMIN_KEY });
+
+let business = await admin.merchantBusiness.retrieve();
+business = await admin.merchantBusiness.update({
+  capabilities: { electronicInvoicing: { requested: true } },
+  fiscalDetails: {
+    commercialName: "Café Duarte",
+    address: "Calle El Conde 101",
+    location: { municipalityCode: "320100" },
+    phone: "+18095550142",
+    defaultIncomeType: "01",
+  },
+});
+business = await admin.merchantBusiness.importSigningCertificate({
+  certificateP12Base64: p12.toString("base64"),
+  password: certificatePassword,
+});
+// Timbro sends the TesteCF document itself; poll until DGII answers.
+business = await admin.merchantBusiness.retrieve();
+if (business.capabilities.electronicInvoicing.status === "active") {
+  const { credential, fiscalOrigin } = await admin.merchantBusiness.issueSandboxCredential({
+    idempotencyKey: "sandbox-credential-1",
+  });
+}
+```
+
+Each entry of `business.requirements` names its `owner`: `merchant` entries are yours to resolve,
+and `field` points into the representation when a field answers it. `dgii` and `timbro` entries
+wait, `provider` entries wait on the acquirer, and `operator` entries need Timbro support. `update` replaces each member it carries, and
+an `expectedRevision` refuses a stale write with `merchant_business_revision_conflict`.
+Electronic invoicing onboards against DGII's TesteCF environment only. The certificate import is
+the one call that carries the PKCS#12 archive; send it only from a machine that already holds the
+file, and do not resend it once `fiscalSetup.signingCertificate.sha256` matches.
+`retryTestFiscalDocument()` sends a new TesteCF document only when none is processing or
+accepted. `issueSandboxCredential` returns the ERP credential once and retires the one issued
+before it; the same `idempotencyKey` replays it.
+
+## Every published operation
+
+`timbro.client` is the typed low-level client for every operation in the published document,
+with the same key and transport. Requests, responses, and Problem bodies are typed from the
+generated `paths`, `components`, and `operations`, which the package also exports:
+
+```ts
+import { createTimbroPayments, type components } from "@timbro/payments";
+
+const { data, error, response } = await timbro.client.POST("/v1/api_keys/rotate", {
+  params: { header: { "idempotency-key": "rotate-2026-09" } },
+});
+if (error !== undefined) {
+  console.error(response.status, error.code);
+}
+type Requirement = components["schemas"]["MerchantBusinessRequirement"];
+```
+
+The facade covers every published merchant operation except `rotateApiKey`,
+`createPreCreationJourneyRequest`, and `chooseFiscalDocument`, which the client reaches directly.
+
+## From a terminal
+
+The published document is served at `https://api.timbro.dev/openapi.json`, so a
+generic OpenAPI client needs nothing from Timbro. With [Restish](https://rest.sh), register the
+API once and pass a test administrator key on each call, from an environment variable rather than
+your shell history:
+
+```sh
+restish api configure timbro https://api.timbro.dev
+restish timbro retrieve-merchant-business -H "Authorization: Bearer $TIMBRO_ADMIN_KEY"
+restish timbro update-merchant-business -H "Authorization: Bearer $TIMBRO_ADMIN_KEY" \
+  'capabilities.electronicInvoicing.requested: true'
+jq -n --arg p12 "$(base64 -w0 certificate.p12)" --arg password "$CERTIFICATE_PASSWORD" \
+  '{certificateP12Base64: $p12, password: $password}' |
+  restish timbro import-merchant-business-signing-certificate -H "Authorization: Bearer $TIMBRO_ADMIN_KEY"
+```
+
+Restish names each command after the operation ID in kebab case. Timbro ships no CLI of its own.
+
 `@timbro/payments` serves payment consumers. `@timbro/sdk` is the consumer-neutral fiscal SDK for ERPs, POS systems, payment systems, and other direct fiscal integrations. Neither package depends on or re-exports the other.