Skip to main content

Store Management API

The Store Management API allows you to manage store information in the Nilo platform. These endpoints help you create, update, and retrieve store data, including store details, users, credit information, and settings.

Understanding Stores​

Stores in Nilo represent the retail locations that can place orders:

  • Store Structure

    • Unique internal code (matches ERP)
    • Owner and legal information
    • Address and location data
    • User associations (via phone or email)
    • Credit and payment status
    • Settings and configurations
    • Group associations (price lists, stock, promotions)

  • Store Hierarchy

    • Independent entities with unique identifiers
    • Can have multiple associated users
    • Maintain their own credit status
    • Can belong to different groupers
    • Support batch operations for updates

Important Considerations​

  1. Unique Codes: Each store requires a unique internal code that matches your ERP system
  2. User Management: Users are associated via phone number (with country code) or email
  3. Credit System: Stores have credit limits and payment status tracking
  4. Location Data: Stores require accurate address and geolocation information
  5. Multiple Groupers: Stores can belong to multiple promotion groupers if configured
  6. Batch Operations: Support for efficiently updating multiple stores

Single Store Operations​

Create Store​

POST/store

Create a new store in the Nilo platform. This endpoint is used to register all store details including:

  • Store information (owner name, legal details)
  • Address and location data
  • Contact information
  • Group associations

Request Body Parameters​

ParameterTypeRequiredDescription
ownerNamestringYesName of the store owner
ownerIdentifierstringNoOwner identifier
internalCodestringYesStore code (matches ERP)
addressesarrayYesList of store addresses
legalNamestringYesLegal business name
legalIdstringYesLegal business identifier
latitudestringNoStore latitude
longitudestringNoStore longitude
addressFormatstringNoGoogle Maps formatted address
supportContactEmailstringNoEmail for support contact
supportContactPhonestringNoPhone for support contact
promotionGrouperCodestringNoCode for promotion group association
promotionGrouperCodesarrayNoArray of promotion grouper codes (only if multiple grouper configuration is enabled by Nilo)
stockGrouperCodestringNoCode for stock group association
priceListCodestringNoCode for price list association
routeCodestringNoRoute code for delivery
settingsobjectNoStore settings (dropSize, etc.)

addresses array items:

ParameterTypeRequiredDescription
internalCodestringNoAddress code (same as in ERP)
addressLinestringYesFull address
apartmentNumberstringNoApartment/unit number
zipCodestringNoZIP/postal code

settings object:

ParameterTypeRequiredDescription
dropSizeobjectNoMinimum order amount (amount, currency)

Request Body Example​

{
  "ownerName": "Owner name",
  "ownerIdentifier": "Owner identifier",
  "internalCode": "1234",
  "addresses": [
    {
      "internalCode": "1234",
      "addressLine": "25 de mayo 1200, Buenos Aires, Argentina",
      "apartmentNumber": "2",
      "zipCode": "2400"
    }
  ],
  "legalName": "Legal Name S.A.",
  "legalId": "30-12345678-9",
  "latitude": "-34.545278",
  "longitude": "-58.449722",
  "addressFormat": "Av. Pres. Figueroa Alcorta 7597, C1428 Buenos Aires",
  "supportContactEmail": "support@store.com",
  "supportContactPhone": "+5491123456789",
  "promotionGrouperCode": "1234",
  "stockGrouperCode": "6789",
  "priceListCode": "1222",
  "routeCode": "ROUTE1",
  "settings": {
    "dropSize": {
      "amount": 1000,
      "currency": "USD"
    }
  }
}

Response Codes​

CodeDescription
200Successful operation
404Store not found

Get All Stores​

GET/store

Retrieve a paginated list of all stores. This endpoint is useful for:

  • Browsing through the store catalog
  • Implementing cursor-based pagination
  • Filtering stores by enabled status

Query Parameters​

ParameterTypeRequiredDescription
takenumberNoNumber of items per page (default: 50, max: 50)
pagestringNoPage number (default: 1)
cursorstringNoCursor for pagination. First call should pass 0, subsequent calls should use the cursor from the last item of the previous response
enabledbooleanNoFilter by enabled status

Example Usage​

const headers = {
  Authorization: "YOUR_AUTH_TOKEN",
  "x-api-key": "YOUR_API_KEY",
};

fetch(
  "https://tm0cs5kjs6.execute-api.us-east-1.amazonaws.com/dev/store?take=50&cursor=0&enabled=true",
  {
    method: "GET",
    headers: headers,
  }
)
  .then((response) => response.json())
  .then((result) => console.log(result))
  .catch((error) => console.log("error", error));

Upsert Store​

PUT/store

Create a new store or update an existing one based on the internal code. This is useful for:

  • Syncing store data from your ERP
  • Creating stores if they don't exist, updating if they do
  • Simplifying store management logic

Request Body Parameters​

Same as Create Store, with enabled being required:

ParameterTypeRequiredDescription
internalCodestringYesStore code (matches ERP) - used to find existing store
ownerNamestringYesName of the store owner
addressesarrayYesList of store addresses
legalNamestringYesLegal business name
legalIdstringYesLegal business identifier
enabledbooleanYesWhether the store is enabled
ownerIdentifierstringNoOwner identifier
latitudestringNoStore latitude
longitudestringNoStore longitude
addressFormatstringNoGoogle Maps formatted address
supportContactEmailstringNoEmail for support contact
supportContactPhonestringNoPhone for support contact
promotionGrouperCodestringNoCode for promotion group association
promotionGrouperCodesarrayNoArray of promotion grouper codes (only if multiple grouper configuration is enabled)
stockGrouperCodestringNoCode for stock group association
priceListCodestringNoCode for price list association
routeCodestringNoRoute code for delivery
latePayerbooleanNoWhether the store is a late payer
settingsobjectNoStore settings (dropSize, etc.)

Request Body Example​

{
  "internalCode": "1234",
  "ownerName": "Owner name",
  "addresses": [
    {
      "addressLine": "25 de mayo 1200, Buenos Aires, Argentina",
      "zipCode": "2400"
    }
  ],
  "legalName": "Legal Name S.A.",
  "legalId": "30-12345678-9",
  "enabled": true,
  "stockGrouperCode": "6789",
  "priceListCode": "1222"
}

Response Codes​

CodeDescription
200Successful operation
404Store not found

Get Store Details​

GET/store/{code}

Retrieve detailed information about a specific store. This endpoint returns:

  • Store metadata
  • Address information
  • User associations
  • Credit status
  • Group associations

Path Parameters​

ParameterTypeRequiredDescription
codestringYesStore internal code (matches ERP)

Response Codes​

CodeDescription
200Successful operation
404Store not found

Example Usage​

const headers = {
  Authorization: "YOUR_AUTH_TOKEN",
  "x-api-key": "YOUR_API_KEY",
};

fetch("https://tm0cs5kjs6.execute-api.us-east-1.amazonaws.com/dev/store/1234", {
  method: "GET",
  headers: headers,
})
  .then((response) => response.json())
  .then((result) => console.log(result))
  .catch((error) => console.log("error", error));

Update Store​

PUT/store/{code}

Update an existing store's information. This endpoint allows you to:

  • Modify store details
  • Update address information
  • Change group associations
  • Adjust settings

Path Parameters​

ParameterTypeRequiredDescription
codestringYesStore internal code (matches ERP)

Request Body Parameters​

ParameterTypeRequiredDescription
ownerNamestringYesName of the store owner
addressesarrayYesList of store addresses
legalNamestringYesLegal business name
legalIdstringYesLegal business identifier
enabledbooleanYesWhether the store is enabled
ownerIdentifierstringNoOwner identifier
latitudestringNoStore latitude
longitudestringNoStore longitude
addressFormatstringNoGoogle Maps formatted address
supportContactEmailstringNoEmail for support contact
supportContactPhonestringNoPhone for support contact
promotionGrouperCodestringNoCode for promotion group association
promotionGrouperCodesarrayNoArray of promotion grouper codes (only if multiple grouper configuration is enabled)
stockGrouperCodestringNoCode for stock group association
priceListCodestringNoCode for price list association
routeCodestringNoRoute code for delivery
latePayerbooleanNoWhether the store is a late payer
settingsobjectNoStore settings (dropSize, etc.)

Request Body Example​

{
  "ownerName": "Owner name",
  "ownerIdentifier": "Owner identifier",
  "addresses": [
    {
      "internalCode": "1234",
      "addressLine": "25 de mayo 1200, Buenos Aires, Argentina",
      "apartmentNumber": "2",
      "zipCode": "2400"
    }
  ],
  "latitude": "-34.545278",
  "longitude": "-58.449722",
  "addressFormat": "Av. Pres. Figueroa Alcorta 7597, C1428 Buenos Aires",
  "legalName": "Legal Name S.A.",
  "legalId": "30-12345678-9",
  "enabled": true,
  "supportContactEmail": "support@store.com",
  "supportContactPhone": "+5491123456789",
  "promotionGrouperCode": "1234",
  "stockGrouperCode": "6789",
  "priceListCode": "1222",
  "routeCode": "1234",
  "latePayer": false,
  "settings": {
    "dropSize": {
      "amount": 1000,
      "currency": "USD"
    }
  }
}

Response Codes​

CodeDescription
200Successful operation
404Store not found

Example Usage​

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

const data = {
  ownerName: "Updated Owner Name",
  addresses: [
    {
      addressLine: "New Address Line",
      apartmentNumber: "3",
      zipCode: "2401",
    },
  ],
  legalName: "Updated Legal Name",
  promotionGrouperCode: "5678",
};

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

Change Store Status​

PUT/store/{code}/status

Enable or disable a store. This endpoint allows you to:

  • Control store visibility
  • Manage store access
  • Update operational status

Path Parameters​

ParameterTypeRequiredDescription
codestringYesStore internal code (matches ERP)

Request Body Parameters​

ParameterTypeRequiredDescription
enabledbooleanYesWhether the store should be enabled

Request Body Example​

{
  "enabled": true
}

Example Usage​

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

const data = {
  enabled: true,
};

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

Manage Store Users​

Add User by Phone​

PUT/store/{code}/add/user

Add a user to a store using their phone number. This endpoint allows:

  • Associating new users with the store via phone
  • Setting up user access
  • Managing store personnel

Path Parameters​

ParameterTypeRequiredDescription
codestringYesStore internal code (matches ERP)

Request Body Parameters​

ParameterTypeRequiredDescription
countryCodestringYesCountry code with + prefix (e.g., "+54")
phonestringYesPhone number without country code
namestringNoUser's name

Request Body Example​

{
  "countryCode": "+54",
  "phone": "1123456789",
  "name": "John Doe"
}

Response Codes​

CodeDescription
200Successful operation
404Store not found

Example Usage​

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

const data = {
  countryCode: "+54",
  phone: "1123456789",
  name: "John Doe",
};

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

Add User by Email​

PUT/store/{code}/add/user-email

Add a user to a store using their email address. This endpoint allows:

  • Associating new users with the store via email
  • Setting up user access for email-based authentication
  • Managing store personnel

Path Parameters​

ParameterTypeRequiredDescription
codestringYesStore internal code (matches ERP)

Request Body Parameters​

ParameterTypeRequiredDescription
emailstringYesUser's email
namestringNoUser's name

Request Body Example​

{
  "email": "user@example.com",
  "name": "John Doe"
}

Response Codes​

CodeDescription
200Successful operation
404Store not found

Example Usage​

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

const data = {
  email: "user@example.com",
  name: "John Doe",
};

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

Remove Users​

PUT/store/{code}/remove/user

Remove users from a store. This endpoint enables:

  • Removing user associations
  • Managing access control
  • Updating store personnel

Path Parameters​

ParameterTypeRequiredDescription
codestringYesStore internal code (matches ERP)

Request Body Parameters​

ParameterTypeRequiredDescription
usersarrayYesArray of users to remove

users array items:

ParameterTypeRequiredDescription
countryCodestringYesCountry code with + prefix (e.g., "+54")
phonestringYesPhone number without country code

Request Body Example​

{
  "users": [
    {
      "countryCode": "+54",
      "phone": "1123456789"
    },
    {
      "countryCode": "+54",
      "phone": "1198765432"
    }
  ]
}

Response Codes​

CodeDescription
200Successful operation
404Store not found

Example Usage​

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

const data = {
  users: [
    { countryCode: "+54", phone: "1123456789" },
    { countryCode: "+54", phone: "1198765432" },
  ],
};

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

Manage Store Credit​

POST/store/{code}/credit

Update store credit information. This endpoint allows:

  • Setting credit limits
  • Managing credit availability
  • Updating payment terms

Path Parameters​

ParameterTypeRequiredDescription
codestringYesStore internal code (matches ERP)

Request Body Parameters​

ParameterTypeRequiredDescription
creditLimitnumberYesNew credit limit for the store

Request Body Example​

{
  "creditLimit": 5000
}

Example Usage​

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

const data = {
  creditLimit: 5000,
};

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

Payment Status Management​

Set as Defaulter​

POST/store/{code}/debtor

Mark a store as a defaulter. When a store is marked as a defaulter:

  • New orders are blocked
  • Credit access is restricted
  • Payment status is updated

Path Parameters​

ParameterTypeRequiredDescription
codestringYesStore internal code (matches ERP)

Example Usage​

const headers = {
  Authorization: "YOUR_AUTH_TOKEN",
  "x-api-key": "YOUR_API_KEY",
};

fetch(
  "https://tm0cs5kjs6.execute-api.us-east-1.amazonaws.com/dev/store/1234/debtor",
  {
    method: "POST",
    headers: headers,
  }
)
  .then((response) => response.json())
  .then((result) => console.log(result))
  .catch((error) => console.log("error", error));

Set as Late Payer​

POST/store/{code}/latepayer

Mark a store as a late payer. This status means:

  • Store can place new orders
  • Credit access is restricted
  • Payment status is monitored

Path Parameters​

ParameterTypeRequiredDescription
codestringYesStore internal code (matches ERP)

Example Usage​

const headers = {
  Authorization: "YOUR_AUTH_TOKEN",
  "x-api-key": "YOUR_API_KEY",
};

fetch(
  "https://tm0cs5kjs6.execute-api.us-east-1.amazonaws.com/dev/store/1234/latepayer",
  {
    method: "POST",
    headers: headers,
  }
)
  .then((response) => response.json())
  .then((result) => console.log(result))
  .catch((error) => console.log("error", error));

Batch Operations​

Update Store Settings​

POST/batch/store/setting

Update settings for multiple stores simultaneously. This endpoint is useful for:

  • Bulk configuration updates
  • Standardizing store settings
  • Efficient store management

Request Body Parameters​

ParameterTypeRequiredDescription
storesarrayYesArray of store settings to update

Request Body Example for Batch Store Settings​

{
  "stores": [
    {
      "storeCode": "1234",
      "settings": {
        "credit": 5000,
        "debtor": false,
        "latePayer": false,
        "allowPartialDelivery": true,
        "minimumOrderAmount": 1000
      }
    },
    {
      "storeCode": "5678",
      "settings": {
        "credit": 10000,
        "debtor": true,
        "latePayer": true,
        "allowPartialDelivery": false,
        "minimumOrderAmount": 2000
      }
    }
  ]
}

Example Usage​

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

const data = {
  stores: [
    {
      storeCode: "1234",
      settings: {
        credit: 5000,
        debtor: false,
        latePayer: false,
        allowPartialDelivery: true,
        minimumOrderAmount: 1000,
      },
    },
    {
      storeCode: "5678",
      settings: {
        credit: 10000,
        debtor: true,
        latePayer: true,
        allowPartialDelivery: false,
        minimumOrderAmount: 2000,
      },
    },
  ],
};

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

Batch Store Updates​

POST/batch/store

Perform updates on multiple stores simultaneously. This endpoint supports:

  • Creating multiple stores
  • Updating existing stores
  • Upserting store data

Request Body Parameters​

ParameterTypeRequiredDescription
createarrayNoArray of stores to create
updatearrayNoArray of stores to update
upsertarrayNoArray of stores to upsert
removearrayNoArray of store codes to remove

Request Body Example for Batch Store​

{
  "create": [
    {
      "ownerName": "Owner name",
      "ownerIdentifier": "Owner identifier",
      "internalCode": "1234",
      "addresses": [
        {
          "internalCode": "1234",
          "addressLine": "25 de mayo 1200, Buenos aires, Argentina",
          "apartmentNumber": "2",
          "zipCode": "2400"
        }
      ],
      "latitude": "-34.545278°",
      "longitude": "-58.449722",
      "addressFormat": "Av. Pres. Figueroa Alcorta 7597, C1428 Buenos Aires",
      "legalName": "legal name",
      "legalId": "legal id",
      "supportContactEmail": "string",
      "supportContactPhone": "string",
      "promotionGrouperCode": "1234",
      "stockGrouperCode": "6789",
      "pricelistCode": "1222",
      "routeCode": "1234",
      "settings": {
        "dropSize": {
          "amount": 1000,
          "currency": "USD"
        }
      }
    }
  ],
  "update": [
    {
      "ownerName": "Owner name updated",
      "ownerIdentifier": "Owner identifier updated",
      "internalCode": "5678",
      "addresses": [
        {
          "internalCode": "5678",
          "addressLine": "New address",
          "apartmentNumber": "3",
          "zipCode": "2401"
        }
      ],
      "latitude": "-34.545278°",
      "longitude": "-58.449722",
      "addressFormat": "New complete address",
      "legalName": "new legal name",
      "legalId": "new legal id",
      "enabled": true,
      "supportContactEmail": "new@email.com",
      "supportContactPhone": "1234567890",
      "promotionGrouperCode": "PROMO2",
      "stockGrouperCode": "STOCK2",
      "pricelistCode": "PRICE2",
      "routeCode": "ROUTE2",
      "latePayer": true,
      "settings": {
        "dropSize": {
          "amount": 2000,
          "currency": "USD"
        }
      }
    }
  ],
  "upsert": [
    {
      "internalCode": "9012",
      "ownerName": "Owner name upsert",
      "ownerIdentifier": "Owner identifier upsert",
      "addresses": [
        {
          "internalCode": "9012",
          "addressLine": "Upsert address",
          "apartmentNumber": "4",
          "zipCode": "2402"
        }
      ],
      "latitude": "-34.545278°",
      "longitude": "-58.449722",
      "addressFormat": "Upsert complete address",
      "legalName": "upsert legal name",
      "legalId": "upsert legal id",
      "enabled": true,
      "supportContactEmail": "upsert@email.com",
      "supportContactPhone": "0987654321",
      "promotionGrouperCode": "PROMO3",
      "stockGrouperCode": "STOCK3",
      "pricelistCode": "PRICE3",
      "routeCode": "ROUTE3",
      "latePayer": false,
      "settings": {
        "dropSize": {
          "amount": 3000,
          "currency": "USD"
        }
      }
    }
  ],
  "remove": ["9012"]
}

Example Usage​

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

const data = {
  create: [
    {
      ownerName: "Owner 1",
      internalCode: "1234",
      addresses: [
        {
          addressLine: "Address 1",
          zipCode: "2400",
        },
      ],
      legalName: "Legal Name 1",
    },
    {
      ownerName: "Owner 2",
      internalCode: "5678",
      addresses: [
        {
          addressLine: "Address 2",
          zipCode: "2401",
        },
      ],
      legalName: "Legal Name 2",
    },
  ],
  update: [
    {
      ownerName: "Updated Owner Name",
      ownerIdentifier: "Updated Owner Identifier",
      internalCode: "5678",
      addresses: [
        {
          internalCode: "5678",
          addressLine: "New Address",
          apartmentNumber: "3",
          zipCode: "2401",
        },
      ],
      latitude: "-34.545278°",
      longitude: "-58.449722",
      addressFormat: "New Complete Address",
      legalName: "Updated Legal Name",
      enabled: true,
      supportContactEmail: "updated@email.com",
      supportContactPhone: "1234567890",
      promotionGrouperCode: "PROMO2",
      stockGrouperCode: "STOCK2",
      pricelistCode: "PRICE2",
      routeCode: "ROUTE2",
      latePayer: true,
      settings: {
        dropSize: {
          amount: 2000,
          currency: "USD",
        },
      },
    },
  ],
  upsert: [
    {
      internalCode: "9012",
      ownerName: "Upsert Owner Name",
      ownerIdentifier: "Upsert Owner Identifier",
      addresses: [
        {
          internalCode: "9012",
          addressLine: "Upsert Address",
          apartmentNumber: "4",
          zipCode: "2402",
        },
      ],
      latitude: "-34.545278°",
      longitude: "-58.449722",
      addressFormat: "Upsert Complete Address",
      legalName: "Upsert Legal Name",
      legalId: "Upsert Legal ID",
      enabled: true,
      supportContactEmail: "upsert@email.com",
      supportContactPhone: "0987654321",
      promotionGrouperCode: "PROMO3",
      stockGrouperCode: "STOCK3",
      pricelistCode: "PRICE3",
      routeCode: "ROUTE3",
      latePayer: false,
      settings: {
        dropSize: {
          amount: 3000,
          currency: "USD",
        },
      },
    },
  ],
  remove: ["9012"],
};

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

Response Types​

Success Response​

{
  "code": 200,
  "message": "Operation successful",
  "data": {
    "ownerName": "Owner name",
    "internalCode": "1234",
    "addresses": [
      {
        "addressLine": "25 de mayo 1200, Buenos aires, Argentina",
        "apartmentNumber": "2",
        "zipCode": "2400"
      }
    ],
    "enabled": true
  }
}

Error Response Examples​

Store Not Found​

{
  "code": 404,
  "message": "Store not found"
}

Validation Error​

{
  "code": 400,
  "message": "Invalid store data",
  "errors": [
    {
      "field": "internalCode",
      "message": "Internal code is required"
    }
  ]
}

Best Practices​

  1. Store Management

    • Use consistent naming conventions
    • Maintain accurate address information
    • Implement proper status management
    • Keep store information up to date

  2. User Management

    • Validate user information
    • Maintain user access records
    • Document user changes
    • Implement user removal procedures

  3. Credit Management

    • Monitor credit limits
    • Track payment history
    • Document status changes
    • Implement credit checks

  4. Performance Optimization

    • Use batch operations for multiple updates
    • Implement caching strategies
    • Monitor API usage
    • Optimize data synchronization

Common Use Cases​

  1. Initial Store Setup

    • Create store profile
    • Configure user access
    • Set up credit limits
    • Configure group associations

  2. Store Maintenance

    • Update store information
    • Manage user access
    • Monitor credit status
    • Adjust store settings

  3. Bulk Operations

    • Import multiple stores
    • Update store settings
    • Modify group associations
    • Sync store data

  4. Credit Management

    • Monitor payment status
    • Update credit limits
    • Handle defaulters
    • Process credit changes

Implementation Guidelines​

  1. Store Creation

    • Validate required fields
    • Check for duplicate codes
    • Process address data
    • Set up initial configurations

  2. User Management

    • Validate user credentials
    • Handle user permissions
    • Manage user associations
    • Track user activities

  3. Credit Handling

    • Implement credit checks
    • Process payment status
    • Handle credit updates
    • Monitor credit usage

  4. Batch Processing

    • Validate batch data
    • Handle partial failures
    • Implement rollback
    • Report batch results

Security​

All API endpoints require two types of authentication:

  1. API Key in header: x-api-key
  2. Authorization token in header: Authorization

Required Permissions​

For store management endpoints, the following permissions are required:

  • For read operations: supplier/store.read
  • For write operations: supplier/store.write
  • For batch operations: supplier/store.bulkwrite
  • For credit operations: supplier/credit.write

Error Handling​

  1. Input Validation

    • Validate store codes
    • Verify address data
    • Check user information
    • Validate credit data

  2. Error Responses

    • Use appropriate HTTP codes
    • Provide clear messages
    • Include field-level errors
    • Add error tracking

  3. Recovery Procedures

    • Handle network failures
    • Implement retries
    • Maintain data consistency
    • Log error details

  4. Monitoring

    • Track error rates
    • Monitor API performance
    • Alert on critical errors
    • Analyze error patterns