Salesforce Integration Guide

1. Overview

On cart submit, the API validates the payload, maps frontend dates to the Apex contract, exchanges OAuth credentials for an access_token and instance_url, posts the quote to Salesforce, and returns { success, message } to the browser.

1. Validate payload (CreateCartDto / CartItemDto)
2. Map cart[].DATE → cart[].DATA
3. Obtain OAuth token via SALES_FORCE_AUTH_URL / SALES_FORCE_GRANT_TYPE
4. Send POST {instance_url}/services/apexrest/Quote/
5. Proxy Apex { success, message } to the client

2. Architecture

The integration is implemented by POST /api/cart (CartController), OAuth in SalesforceTokenService, and Apex submission in CartService.

flowchart LR
  Browser["Browser / scripts.js"]
  CartEndpoint["POST /api/cart"]
  CartController["CartController"]
  Mapper["DATE to DATA mapper"]
  CartService["CartService"]
  Token["SalesforceTokenService"]
  Apex["Apex REST /Quote/"]
  SF[("Salesforce CRM")]

  Browser --> CartEndpoint
  CartEndpoint --> CartController
  CartController --> Mapper
  Mapper --> CartService
  CartService --> Token
  Token --> CartService
  CartService --> Apex
  Apex --> SF
  SF --> Apex
  Apex --> CartService
  CartService --> CartController
  CartController --> Browser
            

3. End-to-end journey

Happy path from the embedded cart UI through validation, mapping, OAuth, Apex Quote creation, and the JSON response shown to the user. On failure after mapping, an asynchronous SMTP alert may also be sent.

sequenceDiagram
  participant UI as scripts.js
  participant API as CartController
  participant Map as QuoteMapper
  participant Svc as CartService
  participant OAuth as TokenService
  participant Apex as ApexREST
  participant Mail as ErrorMail

  UI->>API: POST /api/cart
  API->>API: Validate DTO
  API->>Map: Map DATE to DATA
  Map->>Svc: QuotePayload
  Svc->>OAuth: refresh token
  OAuth-->>Svc: access_token + instance_url
  Svc->>Apex: POST /services/apexrest/Quote/
  alt success
    Apex-->>Svc: 200 success true
    Svc-->>API: Quote result
    API-->>UI: success message
  else business or transport error
    Apex-->>Svc: 400 / 5xx / network
    Svc-->>API: Mapped error
    API-->>UI: success false + message
    API->>Mail: Async failure alert
  end
            

4. Authentication

Each cart submission performs a fresh OAuth exchange (no in-memory token cache). The token URL and grant type come from environment variables; SALES_FORCE_ENV is only a label for logs and e-mails and does not select the OAuth host.

5. API contracts

Public endpoint

• Method: POST
• Path: /api/cart
• Handler: CartController.create()
• Validation: global/controller ValidationPipe with whitelist + forbid non-whitelisted

Request payload

{
  "cnpj": "12345678000199",
  "company": "Example Corp",
  "PV": "PV123",
  "PVZ": "PVZ456",
  "email": "user@example.com",
  "user": "jdoe",
  "language": "pt",
  "defaultDate": "2026-06-05",
  "cart": [
    {
      "ID": "01tXXXXXXXXXXXXXXX",
      "QTY": "2",
      "PARTNUMBER": "MAT-001",
      "DATE": "2026-06-05"
    }
  ]
}

Success response (HTTP 200)

{
  "success": true,
  "message": "Quote created successfully"
}

Business error (HTTP 400 from Salesforce)

{
  "success": false,
  "message": "Product not found"
}

Apex REST

POST {instance_url}{SALES_FORCE_QUOTE_PATH} with Authorization: Bearer {access_token}. Apex resolves Account by cnpj and Product2 by cart[].ID (TDS ID), and creates Opportunity + Quote + QuoteLineItem server-side.

6. Payload mapping

The mapper builds the Apex body from the validated DTO. Item dates prefer DATA, then DATE, then root defaultDate. Empty or null dates omit DATA.

flowchart TB
  subgraph Frontend["Frontend scripts.js"]
    TDS["data-tds-id preferred"]
    Fallback["else PARTNUMBER + PARENT"]
    DateField["DATE on cart item"]
    DefaultDate["defaultDate query/root"]
  end

  subgraph API["html-parser"]
    ResolveID["cart[].ID"]
    MapDate["DATE to DATA"]
    Payload["QuotePayload"]
  end

  subgraph Apex["Salesforce Apex"]
    Account["Account by cnpj"]
    Product["Product2 by TDS ID"]
    Quote["Opportunity + Quote + QLI"]
  end

  TDS --> ResolveID
  Fallback --> ResolveID
  DateField --> MapDate
  DefaultDate --> MapDate
  ResolveID --> Payload
  MapDate --> Payload
  Payload --> Account
  Payload --> Product
  Account --> Quote
  Product --> Quote
            

7. Error handling & retries

flowchart TD
  Start["Cart submit"] --> Validate["Validate DTO"]
  Validate -->|invalid| Client400["HTTP 400 validation"]
  Validate -->|ok| OAuth["OAuth token exchange"]
  OAuth -->|transient 502/503/504 or network| OAuthRetry["Retry up to 3"]
  OAuthRetry --> OAuth
  OAuth -->|client error| Auth500["500 Unable to authenticate"]
  OAuth -->|ok| Quote["POST Apex Quote"]
  Quote -->|401 or 403| Reauth["Fresh OAuth + retry up to 3"]
  Reauth --> Quote
  Quote -->|400| Biz400["400 success false + message"]
  Quote -->|network| Svc503["503 Unable to reach Salesforce"]
  Quote -->|timeout| Svc504["504 timed out"]
  Quote -->|5xx| Svc500["500 Salesforce service error"]
  Quote -->|200| Ok["200 success true"]
  Auth500 --> Mail["Async e-mail alert"]
  Biz400 --> Mail
  Svc503 --> Mail
  Svc504 --> Mail
  Svc500 --> Mail
            

• OAuth: up to 3 automatic retries on network errors or HTTP 502/503/504. Client errors such as invalid_grant are not retried.
• Apex REST: on HTTP 401 or 403, a new OAuth exchange runs and the quote request is retried up to 3 times (SALESFORCE_MAX_RETRIES).
• DTO validation failures do not trigger e-mail alerts.

8. Observability

Every cart submission emits structured Winston logs correlated by requestId and flow: "cart". Logs go to the console and to logs/combined-*.log (hourly rotation, 14-day retention).

E-mail alerts

After payload mapping, failures (Salesforce 400, auth, network, timeout, 5xx) trigger an asynchronous internal e-mail via QuotationErrorNotificationService / MailService. Content includes requestId, timestamp, SALES_FORCE_ENV, error summary, and the full Apex JSON payload. Disable with SMTP_ENABLED=false.

9. Go-live gates / UAT notes

Known Salesforce UAT issues

• HTTP 500 — getPricebookByAccountId: Account has no Pricebook; Apex throws QueryException instead of structured 400. Fix data and harden Apex.
• HTTP 500 — account not found: unknown CNPJ can surface as NullPointerException. Apex should return structured 400.

Manual QA checklist (sandbox)

• Happy path (200) — valid cnpj, company, and known Product2 TDS IDs → { success: true }
• Product not found (400) — unknown cart[].ID → { success: false, message: "..." }
• Account not found (400) — unknown cnpj → structured business error (after Apex hardening)

10. Related source files