ERP → Salesforce¶

ERP is the client. Salesforce is the server. Auth is the OAuth client credentials described under How the systems connect, against /services/data/v67.0. If ERP has no instance URL and no token, the local row is still saved and this call is not made.

POST /api/vendors¶

TER-KA-BLR-01 must already exist, at level Territory, and be Active.

{
  "name": "Speedy Service",
  "territoryCode": "TER-KA-BLR-01",
  "gstNumber": "29fghij5678k1z2",
  "panNumber": "fghij5678k",
  "contactPhone": "9822011223",
  "pincode": "560025"
}

ERP uppercases the GSTIN and the PAN, allocates VN-00001, saves the row as Active, upserts Salesforce, then answers HTTP 201. On a successful first create the body includes "vendorCode": "VN-00001", "recordType": "Vendor", "syncStatus": "Synced", and "salesforceRecordId": "00100000000000VAAA". A failed push still returns 201, with "syncStatus": "Failed".

HTTP	`error`	`message`
400	`invalid_json`	`invalid request body`
400	`validation_error`	`name is required`
400	`validation_error`	`territory code is required`
400	`validation_error`	`GST number is required`
400	`validation_error`	`invalid GST number format`
400	`validation_error`	`PAN number is required`
400	`validation_error`	`invalid PAN number format`
400	`validation_error`	`contact phone must be exactly 10 digits`
400	`validation_error`	`pincode must be exactly 6 digits`
400	`validation_error`	`territory not found`
400	`validation_error`	`territory must be a Territory-level record`
400	`validation_error`	`territory must be active`
409	`conflict`	`a vendor with this GST number already exists`

Record type lookup¶

Before the first vendor upsert in a process, ERP loads the Account record types and keeps them for later calls.

GET /services/data/v67.0/query?q=SELECT Id, DeveloperName FROM RecordType WHERE SObjectType = 'Account'

RecordTypeId in the vendor body is the Id whose DeveloperName is Vendor. A missing Vendor record type fails the upsert with account record type "Vendor" not found in org. The local row becomes Failed.

PATCH Account by vendor code¶

The code is in the URL, not the body.

PATCH /services/data/v67.0/sobjects/Account/Vendor_Code__c/VN-00001
Authorization: Bearer {access token}
Content-Type: application/json

{
  "RecordTypeId": "012000000000007AAA",
  "Name": "Speedy Service",
  "GST_Registration_Number__c": "29FGHIJ5678K1Z2",
  "PAN_Number__c": "FGHIJ5678K",
  "Territory__r": { "Territory_Code__c": "TER-KA-BLR-01" },
  "Contact_Phone__c": "9822011223",
  "BillingPostalCode": "560025",
  "Account_Status__c": "Active"
}

012000000000007AAA stands for the Vendor record type id returned by the query above.

Salesforce field	Example	Where ERP got it
`Vendor_Code__c`	`VN-00001`	the URL. External id. Allocated by ERP. Not in the body
`RecordTypeId`	`012000000000007AAA`	the Account record type whose developer name is `Vendor`
`Name`	`Speedy Service`	`name`
`GST_Registration_Number__c`	`29FGHIJ5678K1Z2`	`gstNumber`, uppercased. Omitted when blank
`PAN_Number__c`	`FGHIJ5678K`	`panNumber`, uppercased. Omitted when blank
`Territory__r.Territory_Code__c`	`TER-KA-BLR-01`	`territoryCode`. Omitted when blank
`Contact_Phone__c`	`9822011223`	`contactPhone`. Omitted when blank
`BillingPostalCode`	`560025`	`pincode`. Omitted when blank
`Account_Status__c`	`Active`	`status`

A first create is HTTP 201 with an id. ERP stores that id on the vendor. An update of a code Salesforce already has is HTTP 204 with an empty body. ERP treats the empty body as a failure: vendor upsert: empty id (status 204). The local row becomes Failed, and the id stored from the first create is left as it was. See Salesforce → ERP.

The log reference is vendorCode=VN-00001 name="Speedy Service" recordType=Vendor territory=TER-KA-BLR-01 gst=29FGHIJ5678K1Z2 pan=FGHIJ5678K status=Active. A failure is written to the ERP integration log. ERP does not post an Integration_Log__c for a vendor.

POST /api/vendors/VN-00001/sync-to-salesforce sends the same PATCH again. Success is HTTP 200:

{
  "erpCode": "VN-00001",
  "accountType": "Vendor",
  "status": "Synced"
}

A Salesforce error on this retry is HTTP 500 internal_error with message internal server error. A missing code is HTTP 404 not_found with message vendor not found.

POST /api/vendors/sync-unsynced runs the same upsert for every vendor, ordered by code. The query returns rows already marked Synced, so a second pass hits the empty 204 and counts those as failed. The answer is HTTP 200, for example { "synced": 1, "failed": 0 }.

PATCH /api/vendors/VN-00001¶

The URL is the code. The body is the same shape as the create, without a wrapper. The code cannot be changed. GSTIN uniqueness ignores this vendor's own number.

{
  "name": "Speedy Service",
  "territoryCode": "TER-KA-BLR-01",
  "gstNumber": "29FGHIJ5678K1Z2",
  "panNumber": "FGHIJ5678K",
  "contactPhone": "9822011999",
  "pincode": "560025"
}

ERP answers HTTP 200 and sends the same PATCH, with "Contact_Phone__c": "9822011999". Because Salesforce already has VN-00001, that PATCH is HTTP 204 with an empty body, and the local row becomes Failed.

PATCH /api/vendors/VN-00001/deactivate¶

The request has no body. ERP sets the vendor Inactive and sends the full Account body again, with "Account_Status__c": "Inactive". The log operation is Deactivate.

ERP answers HTTP 200:

{
  "vendorCode": "VN-00001",
  "status": "Inactive",
  "salesforceRecordId": "00100000000000VAAA",
  "recordType": "Vendor"
}

A vendor that is already Inactive returns that body and does not call Salesforce. A failed push still returns this body. The row's syncStatus is Failed, and the answer does not include syncStatus.

Service request and assignment¶

These two calls stay in ERP. Salesforce receives nothing from them.

A service request needs an active vendor. The first code is SR-00001.

{
  "vendorCode": "VN-00001",
  "description": "Annual service of the display cooler"
}

POST /api/service-requests answers HTTP 201 with "requestCode": "SR-00001" and "status": "Open".

An asset assignment needs an active vendor and an asset id. The first code is AS-00001.

{
  "vendorCode": "VN-00001",
  "assetId": "COOLER-1001"
}

POST /api/asset-service-assignments answers HTTP 201 with "assignmentCode": "AS-00001" and "status": "Open".

HTTP	`error`	`message`
400	`validation_error`	`vendor code is required`
400	`validation_error`	`description is required`
400	`validation_error`	`asset id is required`
400	`validation_error`	`vendor is inactive and cannot be used for new service requests or assignments`
404	`not_found`	`vendor not found`

ERP to Salesforce