Sales Representatives API

The Sales Representatives API allows you to manage sales representatives (sales reps) in the Nilo platform. Sales reps are associated with commercial routes and can be assigned to stores for order management and customer relationship purposes.

Understanding Sales Representatives

Sales representatives in Nilo are linked to your commercial route structure:

Sales Rep Structure
- Unique internal code for identification
- Name and contact information (phone with country code)
- Association with a commercial route
- Enabled/disabled status

Important Considerations

Unique Codes: Each sales rep requires a unique internal code (same as in your ERP)
Commercial Routes: Sales reps can be associated with a commercial route for territory management
Contact Info: Country code and phone are required for communication features
Status Control: Use enabled/disabled instead of deleting sales reps

Single Operations

Upsert Sales Representative

PUT/sales-rep

Create or update a single sales representative. If a sales rep with the same internal code exists, it will be updated; otherwise, a new one will be created.

Request Body Parameters

Parameter	Type	Required	Description
internalCode	string	No	Unique sales rep code (same as in ERP)
name	string	Yes	Sales representative full name
countryCode	string	Yes	Phone country code (e.g., "+54")
phone	string	Yes	Phone number
enabled	boolean	Yes	Whether the sales rep is active
commertialRouteInternalCode	string	No	Commercial route internal code to associate

Request Body Example

{
  "internalCode": "SR-001",
  "name": "Juan Pérez",
  "countryCode": "+54",
  "phone": "1155443322",
  "enabled": true,
  "commertialRouteInternalCode": "ROUTE-NORTH"
}

Response Codes

Code	Description
200	Successful operation
400	Validation error
401	Unauthorized
403	Forbidden - Insufficient permissions

Example Usage

Javascript
Python

const headers = {
  Authorization: "YOUR_AUTH_TOKEN",
  "x-api-key": "YOUR_API_KEY",
  "Content-Type": "application/json",
};

const data = {
  internalCode: "SR-001",
  name: "Juan Pérez",
  countryCode: "+54",
  phone: "1155443322",
  enabled: true,
  commertialRouteInternalCode: "ROUTE-NORTH",
};

fetch(
  "https://tm0cs5kjs6.execute-api.us-east-1.amazonaws.com/dev/sales-rep",
  {
    method: "PUT",
    headers: headers,
    body: JSON.stringify(data),
  }
)
  .then((response) => response.json())
  .then((result) => console.log(result))
  .catch((error) => console.log("error", error));

import requests

url = "https://tm0cs5kjs6.execute-api.us-east-1.amazonaws.com/dev/sales-rep"

headers = {
    'Authorization': 'YOUR_AUTH_TOKEN',
    'x-api-key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
}

data = {
    "internalCode": "SR-001",
    "name": "Juan Pérez",
    "countryCode": "+54",
    "phone": "1155443322",
    "enabled": True,
    "commertialRouteInternalCode": "ROUTE-NORTH"
}

response = requests.put(url, headers=headers, json=data)
print(response.text)

Batch Operations

Batch Upsert Sales Representatives

POST/batch/sales-rep

This endpoint allows you to create or update multiple sales representatives at once. The operation is processed asynchronously.

Use this endpoint when you need to:

Synchronize your sales team from your ERP or CRM system
Onboard multiple sales representatives simultaneously
Bulk update sales rep assignments to commercial routes

Request Body Parameters

Parameter	Type	Required	Description
upsert	array	Yes	Array of sales representative objects
upsert[].id	integer	No	Sales rep ID (required for updates)
upsert[].internalCode	string	No	Unique sales rep code (same as in ERP)
upsert[].name	string	No	Sales representative full name
upsert[].countryCode	string	No	Phone country code (e.g., "+54")
upsert[].phone	string	No	Phone number
upsert[].enabled	boolean	No	Whether the sales rep is active
upsert[].commertialRouteInternalCode	string	No	Commercial route internal code to associate

Request Body Example

{
  "upsert": [
    {
      "internalCode": "SR-001",
      "name": "Juan Pérez",
      "countryCode": "+54",
      "phone": "1155443322",
      "enabled": true,
      "commertialRouteInternalCode": "ROUTE-NORTH"
    },
    {
      "internalCode": "SR-002",
      "name": "María López",
      "countryCode": "+54",
      "phone": "1166554433",
      "enabled": true,
      "commertialRouteInternalCode": "ROUTE-SOUTH"
    },
    {
      "internalCode": "SR-003",
      "name": "Carlos García",
      "countryCode": "+54",
      "phone": "1177665544",
      "enabled": false,
      "commertialRouteInternalCode": null
    }
  ]
}

Response Codes

Code	Description
202	Accepted - Operation in processing
400	Validation error
403	Unauthorized

Response Example

{
  "code": 202,
  "batchIds": {},
  "message": "Operation in processing"
}

Example Usage

Javascript
Python

const headers = {
  Authorization: "YOUR_AUTH_TOKEN",
  "x-api-key": "YOUR_API_KEY",
  "Content-Type": "application/json",
};

const data = {
  upsert: [
    {
      internalCode: "SR-001",
      name: "Juan Pérez",
      countryCode: "+54",
      phone: "1155443322",
      enabled: true,
      commertialRouteInternalCode: "ROUTE-NORTH",
    },
    {
      internalCode: "SR-002",
      name: "María López",
      countryCode: "+54",
      phone: "1166554433",
      enabled: true,
      commertialRouteInternalCode: "ROUTE-SOUTH",
    },
  ],
};

fetch(
  "https://tm0cs5kjs6.execute-api.us-east-1.amazonaws.com/dev/batch/sales-rep",
  {
    method: "POST",
    headers: headers,
    body: JSON.stringify(data),
  }
)
  .then((response) => response.json())
  .then((result) => console.log(result))
  .catch((error) => console.log("error", error));

import requests

url = "https://tm0cs5kjs6.execute-api.us-east-1.amazonaws.com/dev/batch/sales-rep"

headers = {
    'Authorization': 'YOUR_AUTH_TOKEN',
    'x-api-key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
}

data = {
    "upsert": [
        {
            "internalCode": "SR-001",
            "name": "Juan Pérez",
            "countryCode": "+54",
            "phone": "1155443322",
            "enabled": True,
            "commertialRouteInternalCode": "ROUTE-NORTH"
        },
        {
            "internalCode": "SR-002",
            "name": "María López",
            "countryCode": "+54",
            "phone": "1166554433",
            "enabled": True,
            "commertialRouteInternalCode": "ROUTE-SOUTH"
        }
    ]
}

response = requests.post(url, headers=headers, json=data)
print(response.text)

Error Codes

When an operation fails, the API returns a structured error response:

{
  "code": 409,
  "message": "INTERNAL_CODE_ALREADY_EXISTS",
  "object": {
    "statusCode": 409,
    "code": "INTERNAL_CODE_ALREADY_EXISTS",
    "message": "Sales rep not found",
    "entity": "salesRep",
    "entityCode": "SR-001",
    "timestamp": "2026-05-18T15:16:47.000Z"
  }
}

The object field provides additional context about the error:

Field	Description
`statusCode`	HTTP status code
`code`	Error code (same as top-level `message`)
`message`	Human-readable error description
`entity`	Entity type that caused the error
`entityCode`	The internalCode of the entity involved
`timestamp`	When the error occurred (ISO 8601)

400 — Bad Request

Error Code	Description
`INVALID_COUNTRY_CODE`	The provided country code is null or invalid
`INVALID_USERNAME`	The username format is not valid

404 — Not Found

Error Code	Description
`SALES_REP_NOT_FOUND`	The sales representative does not exist
`SALES_REP_NOT_EXIST`	The sales rep ID provided does not match any existing record
`COMMERTIAL_ROUTE_NOT_EXIST`	The specified commercial route does not exist

409 — Conflict

Error Code	Description
`USERNAME_ALREADY_EXIST_IN_SFA`	The phone number is already registered as another sales rep
`USERNAME_ALREADY_EXIST_IN_PWA`	The phone number is already registered as a store user
`COMMERTIAL_ROUTE_ALREADY_ASSIGNED`	The commercial route is already assigned to another sales rep
`INTERNAL_CODE_ALREADY_EXISTS`	A sales rep with the same internal code already exists

Security

Authentication

All endpoints require two types of authentication:

API Key in header: x-api-key
Authorization token in header: Authorization

Understanding Sales Representatives​

Important Considerations​

Single Operations​

Upsert Sales Representative​

Request Body Parameters​

Request Body Example​

Response Codes​

Example Usage​

Batch Operations​

Batch Upsert Sales Representatives​

Request Body Parameters​

Request Body Example​

Response Codes​

Response Example​

Example Usage​

Error Codes​

400 — Bad Request​

404 — Not Found​

409 — Conflict​

Security​

Authentication​

Tana

Understanding Sales Representatives

Important Considerations

Single Operations

Upsert Sales Representative

Request Body Parameters

Request Body Example

Response Codes

Example Usage

Batch Operations

Batch Upsert Sales Representatives

Request Body Parameters

Request Body Example

Response Codes

Response Example

Example Usage

Error Codes

400 — Bad Request

404 — Not Found

409 — Conflict

Security

Authentication