Endpoints para Ubicación

La entidad Location representa un lugar asociado a un socio comercial. Cada ubicación incluye una serie de atributos que la describen además de información relevante para los socios comerciales.

Características Comunes de las Ubicaciones

1. Identificación Única: Cada ubicación tiene un identificador único id que las distingue de otras ubicaciones en el sistema. Además cuenta con un campo idRemote, que hace referencia al id que puede estar almacenado en la base de datos del ERP del cliente.

2. Datos de Ubicación: Típicamente, una ubicación tiene información asociada como nombre, dirección, ciudad, estado, código postal, datos del socio comercial asociado y otros detalles.

3. Actividades y Registro: Las actividades realizadas por una ubicación dentro del sistema, como la creación, modificación o eliminación de recursos, pueden ser registradas.

4. Socio Comercial: Se almacena información básica sobre el socio comercial al que pertenece la ubicación, como nombre de contacto y nombre comercial.

Importancia en la API

Nuestra API ofrece endpoints específicos para gestionar y manipular ubicaciones dentro del sistema. Estos endpoints permiten realizar operaciones como la creación, actualización, recuperación y eliminación de información de ubicaciones de forma estructurada y segura.

Endpoints

GET/Location/getLocation

Obtención de una Lista Paginada de Ubicaciones.

Descripción

Este endpoint recupera una lista paginada de ubicaciones del sistema. Permite a los clientes obtener datos de ubicaciones basados en parámetros de paginación como el número de página (page) y el número de ítems por página (pageSize). La respuesta incluye información detallada sobre cada ubicación, incluyendo su ID, dirección, estado, código postal, marca de tiempo de última actualización e información de socio comercial.

Parámetros

Nombre	Descripción	Tipo	Valor Predeterminado
page	Número de página	Integer	1
pageSize	Número de ítems por página	Integer	10

Respuestas

JSON

  {
      "data": [
          {
          "id": "string",
          "idRemote": "string",
          "businessPartner": {
              "id": "string",
              "idRemote": "string",
              "contactName": "string",
              "comercialName": "string"
          },
          "name": "string",
          "address": "string",
          "city": "string",
          "state": "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>
          <comercialName>string</comercialName>
        </businessPartner>
        <name>string</name>
        <address>string</address>
        <city>string</city>
        <state>string</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>      

👉Prueba este endpoint🌱

GET/Location/updatedFrom

Obtención de Ubicaciones desde una fecha de modificación

Descripción

Este endpoint recupera una lista paginada de ubicaciones del sistema, desde una fecha de modificación utilizando el parámetro date. Permite a los clientes obtener datos de ubicaciones basados en parámetros de paginación como el número de página (page) y el número de ítems por página (pageSize). La respuesta incluye información detallada sobre cada ubicación, incluyendo su ID, dirección, estado, código postal, marca de tiempo de última actualización e información de socio comercial.

Parámetros

Nombre	Descripción	Tipo	Valor Predeterminado
updated	Fecha de actualización	String	1999-01-01 01:00:00
page	Número de página	Integer	1
pageSize	Número de ítems por página	Integer	10

Respuestas

JSON

  {
      "data": [
          {
          "id": "string",
          "idRemote": "string",
          "businessPartner": {
              "id": "string",
              "idRemote": "string",
              "contactName": "string",
              "comercialName": "string"
          },
          "name": "string",
          "address": "string",
          "city": "string",
          "state": "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>
          <comercialName>string</comercialName>
        </businessPartner>
        <name>string</name>
        <address>string</address>
        <city>string</city>
        <state>string</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>      

👉Prueba este endpoint🌱

POST/Location/create

Registro de Ubicaciones en la API: Uso del Método POST

Actualmente, nuestro método POST en la API está configurado para aceptar únicamente datos en formato JSON. Para registrar ubicaciones de manera efectiva, es esencial seguir un proceso que asegure la integridad de los datos y el correcto funcionamiento del sistma.

Proceso de Registro:

1. Creación de Business Partner: Para crear una ubicación es obligatorio relacionarla con un Socio Comercial. El atributo businessPartnerId debe contener un identificador válido y registrado en la base de datos. 👉Registrar Business Partner🌱

Detalles del Método POST:

Este método sirve para crear y asignar una dirección física (Localización) a un Socio Comercial. Los atributos stateId y countryId hacen referencia a las entidades State y Country respectivamente. Debes adjuntar un identificador válido para que la petición funcione correctamente. Además debes tener en cuenta que el State que adjuntes en la petición debe perteneecr al País referenciado.

Parámetros obligatorios:

Nombre	Descripción	Tipo
idRemote	Identificador de la nueva Localización	String
businessPartnerId	Identificador del Socio Comercial al cual se va a asignar la nueva Localización	String
countryId	Identificador del País de la nueva Localización	String
name	Nombre de la nueva Localización	String
address	Dirección de la nueva Localización	String
city	Nombre de la población de la nueva Localización	String
shippingAddress	Determina si la nueva Localización debe ser establecida como dirección de envío	Boolean
billingAddress	Determina si la nueva Localización debe ser establecida como dirección de facturación	Boolean
active	Determina si la nueva Localización está activa	Boolean
default	Determina si la nueva Localización es la localización por defecto	Boolean

Una petición completa debe seguir el siguiente esquema:

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

Es posible añadir varias ubicaciones a través de la misma solicitud separándolos con comas dentro del array en el cuerpo de la solicitud.

👉Prueba este endpoint🌱

PUT/Location/update/{id}

Actualización de Ubicaciones

Descripción

El método PUT de nuestra API permite a los clientes actualizar los datos de ubicaciones utilizando el parámetro id. Este campo id puede ser tanto el identificador propio del sistema B2B como el idRemote que usted nos proporciona al registrar las ubicaciones en nuestra plataforma. De esta manera nuestra plataforma garantiza una gestión eficiente y precisa de la información de las ubicaciones.

Debes tener en cuenta que puedes actualizar cualquier atributo de una Localización existente menos el Socio Comercial asignado a la misma a través de este endpoint. Si quieres actualizar esta información debes hacerlo desde el endpoint de actualización de Socio Comercial.

👉Endpoints Business Partner🌱

Parámetros

Nombre	Descripción	Tipo
id	Identificador de Ubicación	String

No es necesario incluir toda la estructura JSON, solo debes incluir los atributos que quieras modificar.

Cuerpo de la solicitud:

Para actualizar enteramente una Localización, el cuerpo de la solicitud debe seguir el siguiente esquema:

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

👉Prueba este endpoint🌱

DELETE/Location/delete/{id}

Eliminación de Ubicaciones

Descripción

Este endpoint permite la eliminación de ubicaciones utilizando su identificador único. Este campo id puede ser tanto el identificador generado por la base de datos del B2B como el idRemote que usted nos proporciona al registrar las ubicaciones. Una vez eliminada, la Ubicación se registra en el Historial de Eliminados.

⚠️No se podrá eliminar una Ubicación que tenga asociado un Socio Comercial.

Parámetros

Nombre	Descripción	Tipo
id	Identificador de Ubicación	String

👉Prueba este endpoint🌱

Posibles Errores en la Respuesta

Error	Código	Respuesta
Este error ocurre cuando no se puede establecer una conexión con la base de datos. Es un problema interno del servidor.	500	{"code": 500,"error": "Database connection failed."}
Este error ocurre cuando no puede insertar o actualizar y en la dbs de pruebas.	500	{"code": 500,"error": "Invalid connection name, you cannot insert in default"}
Este error indica que falta un parametro.	400	{"code": 400,"error": "Parameter $parameter is required"}
Este error indica que no está autorizado.	401	{"code": 401,"error": "Unauthorized"}
Este error indica que no ha sido posible encontrar la Ubicación.	404	{"code": 404,"error": "No entity found for Location with $id."}
Este error ocurre cuando intenta insertar una ubicación que ya existe.	409	{"code": 409,"error": "Duplicate entry"}
Este error ocurre cuando intenta enviar demasiadas solicitudes en un corto periodo de tiempo.	429	{"code": 429,"error": "Too Many Requests"}