Location Endpoints

The Location entity represents a place associated with a business partner. Each location includes a series of attributes that describe it as well as information relevant to business partners.

Common Location Characteristics

Unique Identification: Each location has a unique identifier id that distinguishes them from other locations in the system. It also has an idRemote field, which refers to the id that may be stored in the client's ERP database.
Location Data: Typically, a location has associated information such as name, address, city, state, postal code and other contact details.
Activities and Logging: Activities performed by a location within the system, such as creation, modification, or deletion of resources, may be logged.
Business Partner: Basic information about the business partner to which the location belongs, such as contact name and business name, is stored.

Importance in the API

Our API offers specific endpoints to manage and manipulate locations within the system. These endpoints enable operations such as creation, updating, retrieval, and deletion of location information in a structured and secure manner.

Endpoints

GET/Location/getLocation

Retrieve a paginated list of locations.

Description

This endpoint retrieves a paginated list of locations from the system. It allows clients to fetch locations data based on pagination parameters such as page number (page) and items per page (pageSize). The response includes detailed information about each location, including their ID, idRemote, business partner information, name, address, city, state, postal code, country, created at and last update timestamp.

Parameters

Name	Description	Type	Default Value
`id`	Location Id	Integer optional	1
`page`	Page number	Integer	1
`pageSize`	Number of items per page	Integer	10

Responses

JSON

  {
      "data": [
          {
          "id": "string",
          "idRemote": "string",
          "businessPartner": {
              "id": "string",
              "idRemote": "string",
              "contactName": "string",
              "commercialName": "string"
          },
          "name": "string",
          "address": "string",
          "city": "string",
          "state": {
            "id": "string",
            "description": "string",
            "iso": "string"
          },
          "postalCode": "string",
          "default": true,
          "active": true,
          "shippingAddress": true,
          "billingAddress": true, 
          "country": {
              "id": "string",
              "description": "string",
              "iso": "string"
          },  
          "createdAt": "string",
          "updatedAt": "string"
          }
      ],
      "pagination": {
          "totalItems": 0,
          "itemsPerPage": 0,
          "currentPage": 0,
          "totalPages": 0,
          "nextPageUrl": "string"
      }
  }

XML

  <?xml version="1.0" encoding="UTF-8"?>
  <export>
    <data>
      <item>
        <id>string</id>
        <idRemote>string</idRemote>
        <businessPartner>
          <id>string</id>
          <idRemote>string</idRemote>
          <contactName>string</contactName>
          <commercialName>string</commercialName>
        </businessPartner>
        <name>string</name>
        <address>string</address>
        <city>string</city>
        <state>
          <id>string</id>
          <description>string</description>
          <iso>string</iso>
        </state>
        <postalCode>string</postalCode>
        <default>true</default>
        <active>true</active>
        <shippingAddress>true</shippingAddress>
        <billingAddress>true</billingAddress>
        <country>
          <id>string</id>
          <description>string</description>
          <iso>string</iso>
        </country>
        <createdAt>string</createdAt>
        <updatedAt>string</updatedAt>
      </item>
    </data>
    <pagination>
      <totalItems>0</totalItems>
      <itemsPerPage>0</itemsPerPage>
      <currentPage>0</currentPage>
      <totalPages>0</totalPages>
      <nextPageUrl>string</nextPageUrl>
    </pagination>
  </export>      

👉Try it out🌱

GET/Location/updatedFrom

Retrieve locations from a modification date

Description

This endpoint retrieves a paginated list of locations from the system, starting from a specific modification date using the parameter date. It allows clients to fetch locations data based on pagination parameters such as page number (page) and items per page (pageSize). The response includes detailed information about each location, including their ID, idRemote, business partner information, name, address, city, state, postal code, country, created at and last update timestamp.

Parameters

Name	Description	Type	Default Value
`date`	Updated Date	String required	1999-01-01
`page`	Page number	Integer	1
`pageSize`	Number of items per page	Integer	10

Responses

JSON

  {
      "data": [
          {
          "id": "string",
          "idRemote": "string",
          "businessPartner": {
              "id": "string",
              "idRemote": "string",
              "contactName": "string",
              "commercialName": "string"
          },
          "name": "string",
          "address": "string",
          "city": "string",
          "state": {
            "id": "string",
            "description": "string",
            "iso": "string"
          },
          "postalCode": "string",
          "default": true,
          "active": true,
          "shippingAddress": true,
          "billingAddress": true, 
          "country": {
              "id": "string",
              "description": "string",
              "iso": "string"
          },  
          "createdAt": "string",
          "updatedAt": "string"
          }
      ],
      "pagination": {
          "totalItems": 0,
          "itemsPerPage": 0,
          "currentPage": 0,
          "totalPages": 0,
          "nextPageUrl": "string"
      }
  }

XML

  <?xml version="1.0" encoding="UTF-8"?>
  <export>
    <data>
      <item>
        <id>string</id>
        <idRemote>string</idRemote>
        <businessPartner>
          <id>string</id>
          <idRemote>string</idRemote>
          <contactName>string</contactName>
          <commercialName>string</commercialName>
        </businessPartner>
        <name>string</name>
        <address>string</address>
        <city>string</city>
        <state>
          <id>string</id>
          <description>string</description>
          <iso>string</iso>
        </state>
        <postalCode>string</postalCode>
        <default>true</default>
        <active>true</active>
        <shippingAddress>true</shippingAddress>
        <billingAddress>true</billingAddress>
        <country>
          <id>string</id>
          <description>string</description>
          <iso>string</iso>
        </country>
        <createdAt>string</createdAt>
        <updatedAt>string</updatedAt>
      </item>
    </data>
    <pagination>
      <totalItems>0</totalItems>
      <itemsPerPage>0</itemsPerPage>
      <currentPage>0</currentPage>
      <totalPages>0</totalPages>
      <nextPageUrl>string</nextPageUrl>
    </pagination>
  </export>      

👉Try it out🌱

POST/Location/create

Location Registration in the API: Using the POST Method

Currently, our POST method in the API exclusively handles JSON format. To effectively register locations, it is crucial to follow a process that ensures data integrity and proper system functionality.

Registration Process:

Creation of Business Partner: To create a location, it is mandatory to relate it to a Business Partner. The businessPartnerId attribute must contain a valid identifier registered in the database.
👉Register Business Partner🌱

Mandatory Parameters:

Name	Description	Type
`idRemote`	Identifier of the new Location	String
`businessPartnerId`	Identifier of the Business Partner to whom the new Location will be assigned	String
`countryId`	Identifier of the Country of the new Location	String
`name`	Name of the new Location	String
`address`	Address of the new Location	String
`city`	Name of the city of the new Location	String
`shippingAddress`	Indicates whether the new Location should be set as the shipping address	Boolean
`billingAddress`	Indicates whether the new Location should be set as the billing address	Boolean
`active`	Indicates whether the new Location is active	Boolean
`default`	Indicates whether the new Location is the default location	Boolean
`countryId`	Country Id	String

A complete request must follow the following outline:

[
  {
      "idRemote": "string",
      "businessPartnerId": "string",
      "name": "string",
      "address": "string",
      "city": "string",
      "stateId": "string",
      "countryId": "string",
      "postalCode": "string",
      "default": true,
      "active": true,
      "shippingAddress": true,
      "billingAddress": true,
      "countryId": "string"
  }
]

It is possible to add multiple locations through the same request by separating them with commas within the array in the body of the request.

👉Try it out🌱

PUT/Location/update/{id}

Updating locations

Description

The PUT method of our API allows clients to update locations data using the id parameter. This id field can be either the B2B system's own identifier or the idRemote you provide when registering locations on our platform. In this way, our platform guarantees efficient and accurate location information management.

Please note that you can update any attribute of an existing Location except the Business Partner assigned to it through this endpoint. If you want to update this information you must do so from the Business Partner update endpoint.

👉Business Partner Endpoints🌱

Parameters

Name	Description	Type
`id`	Location identifier	String required

It is not necessary to include the entire JSON structure, you should only include the attributes you want to modify.

Request body:

To fully update a Location, the request body must follow the following scheme:

{
  "idRemote": "string",
  "name": "string",
  "address": "string",
  "city": "string",
  "stateId": "string",
  "postalCode": "string",
  "default": true,
  "active": true,
  "shippingAddress": true,
  "billingAddress": true,
  "countryId": "string",
}

👉Try it out🌱

DELETE/Location/delete/{id}

Removing Locations

Description

This endpoint allows the deletion of locations using their unique identifier. This id field can be either the identifier generated by the B2B database or the idRemote you provide when registering locations. Once deleted, the Location is recorded in the Deleted History.

⚠️A Location that has a Business Partner associated with it cannot be deleted.

Parameters

Name	Description	Type
`id`	Location identifier	String required

👉Try it out🌱

Possible Response Errors

Error	Response Status	Response Body
This error occurs when a connection to the database cannot be established. It is an internal server problem.	500	`{"code": 500,"error": "Database connection failed."}`
This error occurs when you cannot insert or update items into the database.	500	`{"code": 500,"error": "Invalid connection name, you cannot insert in default"}`
This error occurs when a parameter is missing.	400	`{"code": 400,"error": "Parameter $parameter is required"}`
This error occurs when you are not authorized.	401	`{"code": 401,"error": "Unauthorized."}`
This error occurs when the Location could not be found.	404	`{"code": 404,"error": "No entity found for Location with $id."}`
This error occurs when you try to insert a Location that already exists.	409	`{"code": 409,"error": "Duplicate entry"}`
This error occurs when you try to send too many requests in a short period of time.	429	`{"code": 429,"error": "Too Many Requests"}`

Location Endpoints

Common Location Characteristics​

Importance in the API​

Endpoints​

GET/Location/getLocation​

Description​

Parameters​

Responses​

JSON​

XML​

GET/Location/updatedFrom​

Description​

Parameters​

Responses​

JSON​

XML​

POST/Location/create​

Location Registration in the API: Using the POST Method​

Registration Process:​

Mandatory Parameters:​

PUT/Location/update/{id}​

Description​

Parameters​

Request body:​

DELETE/Location/delete/{id}​

Description​

Parameters​

Possible Response Errors​

Common Location Characteristics

Importance in the API

Endpoints

GET/Location/getLocation

Description

Parameters

Responses

JSON

XML

GET/Location/updatedFrom

Description

Parameters

Responses

JSON

XML

POST/Location/create

Location Registration in the API: Using the POST Method

Registration Process:

Mandatory Parameters:

PUT/Location/update/{id}

Description

Parameters

Request body:

DELETE/Location/delete/{id}

Description

Parameters

Possible Response Errors