Version: 📄 MX

Clientes

Listar, crear, editar y eliminar clientes. Además podrás consultar pagos a clientes, contar clientes, ver documentos por cliente, agregar direcciones adicionales (casa matriz, sucursal a, b, etc). Endpoints para gestionar tus clientes en Bsale.

Cómo funciona la interfaz de Bsale, mira éstos videos:

Gestión de clientes Ver

info

El RFC, se almacena en el code, es importante que valides el identificador antes de enviar.

Estructura JSON

Al realizar una petición HTTP, el servicio retornara un JSON con la siguiente estructura:

Response /clients.json
{
  "href": "https://api.bsale.com.mx/v1/clients.json",
  "count": 2,
  "limit": 25,
  "offset": 0,
  "items": [
    {
      "href": "https://api.bsale.com.mx/v1/clients/2.json",
      "id": 2,
      "firstName": "Francisco",
      "lastName": "Pullnom",
      "email": "fpull@gmail.com",
      "state": 0,
      "office": {
        "href": "https://api.bsale.com.mx/v1/offices/1.json",
        "id": "1"
      }
    },
    {
      "href": "https://api.bsale.com.mx/v1/clients/1.json",
      "id": 1,
      "firstName": "Asistente",
      "lastName": "bsale",
      "email": "ayuda@bsale.app",
      "state": 0,
      "office": {
        "href": "https://api.bsale.com.mx/v1/offices/1.json",
        "id": "1"
      }
    }
  ]
}

Atributos

Atributo	Descripción	Tipo dato
href	url del clientes	String
id	identificador único del clientes	Integer
firstName	nombre del cliente	String
lastName	apellido del cliente	String
code	RFC del cliente	String
phone	teléfono del cliente	String
company	empresa del cliente	String
note	una descripción del cliente	String
facebook	facebook del cliente	String
twitter	twitter del cliente.	String
hasCredit	indica si el cliente posee crédito No(0) o Si(1)	Boolean
maxCredit	monto máximo de crédito del cliente	Float
state	estado del cliente indica si esta activo(0) o inactivo (1)	Boolean
activity	giro del cliente	String
city	ciudad del cliente	String
municipality	comuna del cliente	String
companyOrPerson	indica si el cliente es persona natural o empresa (0)Persona o (1)Empresa	Boolean
points	cantidad de puntos acumulados del cliente	Integer
pointsUpdated	fecha de la última actualización de puntos	Integer
accumulatePoints	indica si el cliente acumula puntos No(0) o Si(1)	Boolean
sendDte	indica si al cliente se le envía el XML del DTE No(0) o Si(1)	Boolean
prestashopClienId	identificador en prestashop	String
contacts	nodo que indica la relación con los contactos del cliente.
attributes	nodo que indica la relación con los atributos adicionales de un cliente.
addresses	nodo que indica la relación con las direcciones adicionales de un cliente.

GET lista de clientes

GET /v1/clients.json retornará todos los clientes.

Parámetros

limit, limita la cantidad de items de una respuesta JSON, por defecto el limit es 25, el máximo permitido es 50.
offset, permite paginar los items de una respuesta JSON, por defecto el offset es 0.
fields, solo devolver atributos específicos de un recurso
expand, permite expandir instancias y colecciones para traer relaciones en una sola petición.
code, Permite filtrar por RFC del cliente.
firstname, filtra los clientes por nombre.
lastname, filtra los clientes por apellido.
email, filtra los clientes por email.
paymenttypeid, recupera los clientes con forma de pago.
salesconditionid, recupera los clientes por la condición de venta.
state, boolean (0 o 1) indica si los clientes están activos(0) inactivos (1).

Ejemplos

GET /v1/clients.json?limit=10&offset=0
GET /v1/clients.json?fields=[firstname,lastname]
GET /v1/clients.json?state=0
GET /v1/clients.json?code=XAXX010101000
GET /v1/clients.json?paymenttypeid=1
GET /v1/clients.json?expand=[contacts,attributes,payment_type]

Response /clients.json 
{
  "href": "https://api.bsale.com.mx/v1/clients.json",
  "count": 112,
  "limit": 25,
  "offset": 0,
  "items": [
    {
      "href": "https://api.bsale.com.mx/v1/clients/65.json",
      "id": 65,
      "firstName": "Público en",
      "lastName": "General",
      "code": "XAXX010101000",
      "phone": "",
      "company": "",
      "facebook": "",
      "twitter": "",
      "hasCredit": 1,
      "maxCredit": "10000.0",
      "state": 1,
      "activity": "Sin Giro",
      "city": "",
      "district": "",
      "address": "",
      "companyOrPerson": 0,
      "points": 0,
      "pointsUpdated": "",
      "accumulatePoints": 0,
      "sendDte": 0,
      "prestashopClienId": 0,
      "contacts": {
        "href": "https://api.bsale.com.mx/v1/clients/65/contacts.json"
      },
      "attributes": {
        "href": "https://api.bsale.com.mx/v1/clients/65/attributes.json"
      },
      "addresses": {
        "href": "https//api.bsale.io/v1/clients/65/addresses.json"
      }
    },
    {
      "href": "https://api.bsale.com.mx/v1/clients/102.json",
      "id": 102,
      "firstName": "Adriana",
      "lastName": "Talhouk",
      "code": "XAXX010101000",
      "phone": "",
      "company": "Adriana Talhouk",
      "note": null,
      "facebook": null,
      "twitter": "",
      "hasCredit": 1,
      "maxCredit": "10000.0",
      "state": 0,
      "activity": "Sin Giro",
      "city": "",
      "district": "",
      "address": "",
      "companyOrPerson": 0,
      "points": 0,
      "pointsUpdated": "",
      "accumulatePoints": 0,
      "sendDte": 0,
      "prestashopClienId": 0,
      "contacts": {
        "href": "https://api.bsale.com.mx/v1/clients/102/contacts.json"
      },
      "attributes": {
        "href": "https://api.bsale.com.mx/v1/clients/102/attributes.json"
      },
      "addresses": {
        "href": "https//api.bsale.io/v1/clients/102/addresses.json"
      }
    }
  ]
}

GET un cliente

GET /v1/clients/80.json retornará un cliente específico.

Parámetros

expand, permite expandir instancias y colecciones para traer relaciones en una sola petición.

Ejemplos

GET /v1/clients/80.json?expand=[contacts,payment_type]

Response /clients/80.json
{
            "href": "https://api.bsale.com.mx/v1/clients/2.json",
            "id": 2,
            "firstName": "NATALIA LILIANA",
            "lastName": "MURO MURO",
            "email": "el@cor.reo",
            "code": "NATL009113WM0",
            "phone": "5527011110",
            "company": "LILIA NATALY VACA TAPIA",
            "note": "",
            "facebook": "",
            "twitter": "",
            "hasCredit": 1,
            "maxCredit": 99999990.0,
            "state": 0,
            "activity": ".",
            "city": "MONTERREY",
            "commerciallyBlocked": 0,
            "district": "MONTERREY",
            "address": "PRO FRANCIA NRO 123",
            "postal_code": "54190",
            "companyOrPerson": 0,
            "accumulatePoints": 1,
            "points": 0.0,
            "pointsUpdated": "",
            "sendDte": 0,
            "isForeigner": 0,
            "prestashopClienId": 0,
            "createdAt": 1668115263,
            "updatedAt": 1668115263,
            "payment_type": {
                "href": "https://api.bsale.com.mx/v1/payment_types/1.json",
                "id": "1"
            },
            "price_list": {
                "href": "https://api.bsale.com.mx/v1/price_lists/1.json",
                "id": "1"
            },
            "contacts": {
                "href": "https://api.bsale.com.mx/v1/clients/2/contacts.json"
            },
            "attributes": {
                "href": "https://api.bsale.com.mx/v1/clients/2/attributes.json"
            },
            "addresses": {
                "href": "https://api.bsale.com.mx/v1/clients/2/addresses.json"
            }
        }

GET atributos de un cliente

GET /v1/clients/796/attributes.json Retornará los atributos asociados al cliente.

{
  "href": "https://api.bsale.com.mx/v1/clients/796/attributes.json",
  "count": 4,
  "limit": 25,
  "offset": 0,
  "items": [
    {
      "href": "https://api.bsale.com.mx/v1/dynamic_attributes/44.json",
      "id": 44,
      "name": "Rubro",
      "value": ""
    },
    {
      "href": "https://api.bsale.com.mx/v1/dynamic_attributes/72.json",
      "id": 72,
      "name": "NOMBRE FANTASIA",
      "value": ""
    },
    {
      "href": "https://api.bsale.com.mx/v1/dynamic_attributes/73.json",
      "id": 73,
      "name": "Incluir en listas",
      "value": ""
    },
    {
      "href": "https://api.bsale.com.mx/v1/dynamic_attributes/76.json",
      "id": 76,
      "name": "Número Cliente interno",
      "value": ""
    }
  ]
}

GET cantidad de clientes

GET /v1/clients/count.json Retornará cantidades de registros.
state, boolean (0 o 1) indica si los clientess están activos(0) inactivos (1).

{
   "count": 14541
}

Contactos

GET contactos de un cliente

GET /v1/clients/55/contacts.json retornará los contactos asociados al cliente.

{
  "href": "https://api.bsale.com.mx/v1/clients/4/contacts.json",
  "count": 2,
  "limit": 25,
  "offset": 0,
  "items": [
    {
      "href": "https://api.bsale.com.mx/v1/clients/4/contacts/31.json",
      "id": 31,
      "firstName": "Andres",
      "lastName": "Villanueva",
      "phone": "2220936",
      "email": "a.villanueva@gmail.com"
    },
    {
      "href": "https://api.bsale.com.mx/v1/clients/4/contacts/32.json",
      "id": 32,
      "firstName": "Juana ",
      "lastName": "Jeldres",
      "phone": "2220928",
      "email": "recepcion@gmail.com"
    }
  ]
}

GET un único contacto de un cliente

GET /v1/clients/4/contacts/31.json Retornará un contacto asociado al cliente.

Response /clients/156/attributes/93.json
{
   "href": "https://api.bsale.com.mx/v1/clients/4/contacts/31.json",
   "id": 31,
   "firstName": "Carlitos",
   "lastName": "Finster ",
   "phone": "2220936",
   "email": "Charles-Chuckie-Finster@rugrats.com"
}

POST un contacto de un cliente

POST /v1/clients/55/contacts.json

Para crear un contacto de cliente, se debe enviar un JSON con la siguiente estructura:

Ejemplo JSON

Envío

{
   "firstName": "Tommy",
   "lastName": "Vercetti",
   "phone": "966542311",
   "email": "tvercetti@vc.com"
}

Respuesta

{
  "href": "https://api.bsale.com.mx/v1/clients/55/contacts/1.json",
  "id": 1,
  "firstName": "Tommy",
  "lastName": "Vercetti",
  "phone": "966542311",
  "email": "tvercetti@vc.com"
}

DELETE un contacto de un cliente

DELETE /v1/clients/55/contacts/1.json Cambia el estado del contacto.

Direcciones

GET lista de direcciones de un cliente

GET /v1/clients/55/addresses.json retornará las direcciones asociadas al cliente.

Parámetros

address, permite filtrar por dirección (String).
city, permite filtrar por ciudad (String).
municipality, permite filtrar por comuna (String).
state, permite filtrar por estado (Boolean).

Ejemplos

GET /v1/clients/55/addresses.json?address=la quebrada 1189
GET /v1/clients/55/addresses.json?city=santiago
GET /v1/clients/55/addresses.json?city=santiago&municipality=providencia
GET /v1/clients/55/addresses.json?state=0

{
  "href": "https://api.bsale.com.mx/v1/clients/55/addresses.json",
  "count": 2,
  "limit": 25,
  "offset": 0,
  "items": [
    {
      "href": "https://api.bsale.com.mx/v1/clients/55/addresses/8.json",
      "id": 8,
      "addressName": "SUC 1",
      "address": "SOTERO SANZ 100",
      "city": "STGO",
      "district": "ECATEPEC",
      "state": 0
    },
    {
      "href": "https://api.bsale.com.mx/v1/clients/55/addresses/9.json",
      "id": 9,
      "addressName": "SUC 2",
      "address": "PEDRO DE VALDIVIA 200",
      "city": "STGO",
      "district": "LAS FUENTES ECATEPEC",
      "state": 0
    }
  ]
}

GET una única dirección de un cliente

GET /v1/clients/55/addresses/8.json

{
  "href": "https://api.bsale.com.mx/v1/clients/55/addresses/8.json",
  "id": 8,
  "addressName": "SUC 1",
  "address": "SOTERO SANZ 100",
  "city": "CDMX",
  "district": "MONTERREY",
  "state": 0
}

POST una dirección de un cliente

POST /v1/clients/55/addresses.json

Para crear una dirección de cliente, se debe enviar un JSON con la siguiente estructura:

Ejemplo JSON

Envío

{
  "addressName": "SUC 3",
  "address": "NUNCIO MONSEÑOR SOTERO SANZ 100, OF. 401",
  "city": "CDMX",
  "district": "MONTERREY",
}

Respuesta

{
  "href": "https://api.bsale.com.mx/v1/clients/55/addresses/6.json",
  "id": 6,
  "addressName": "SUC 3",
  "address": "NUNCIO MONSEÑOR SOTERO SANZ 100, OF. 401",
  "city": "CDMX",
  "district": "MONTERREY",
  "state": 0
}

PUT una dirección de un cliente

PUT /v1/clients/55/addresses/6.json

Se debe enviar un Json con la siguiente estructura

Ejemplo JSON

Envío

{
  "addressName": "SUC 4",
  "address": "OF. 401",
  "city": "CDMX",
  "district": "MONTERREY",
}

Respuesta

{
  "href": "https://api.bsale.com.mx/v1/clients/55/addresses/6.json",
  "id": 6,
  "addressName": "SUC 4",
  "address": "OF. 401",
  "city": "CDMX",
  "district": "MONTERREY",
  "state": 0
}

DELETE una dirección de un cliente

DELETE /v1/clients/55/addresses/6.json Cambia el estado de la dirección

Respuesta

{
  "href": "https://api.bsale.com.mx/v1/clients/55/addresses/6.json",
  "id": 6,
  "addressName": "SUC 4",
  "address": "OF. 401",
  "city": "CDMX",
  "district": "MONTERREY",
  "state": 1
}

POST un cliente

POST /v1/clients.json

Para crear un cliente, se debe enviar un JSON con la siguiente estructura:

Ejemplo JSON

Envío

{
  "facebook": "",
  "district": "CDMX",
  "phone": "66287196",
  "activity": "Venta de ropa",
  "city": "CDMX",
  "maxCredit": 100000,
  "hasCredit": 1,
  "accumulatePoints": 1,
  "lastName": "Paredes",
  "note": "Cliente parodia",
  "firstName": "Armando",
  "company": "Particular",
  "address": "Los trigales 372",
  "email": "armando@paredes.mx",
  "twitter": "",
  "code": "XAXX010101000"
}

Atributos (opcional)

Si se desean crear atributos especiales para el cliente se debe enviar la siguiente estructura.

{
  "facebook": "",
  "district": "CDMX",
  "phone": "66287196",
  "activity": "Venta de ropa",
  "city": "CDMX",
  "maxCredit": 100000,
  "hasCredit": 1,
  "accumulatePoints": 1,
  "lastName": "Muñoz",
  "note": "Cliente premiun",
  "firstName": "Marcela",
  "company": "Particular",
  "address": "Los trigales 372",
  "email": "mmunoz@bsale.com.mx",
  "twitter": "",
  "code": "XAXX010101000",
  "dynamicAttributes": [
    {
      "description": "21/03/1983",
      "dynamicAttributeId": 24
    }
  ]
}

Respuesta

{
  "companyOrPerson": 0,
  "address": "Los trigales 372",
  "lastName": "Muñoz",
  "sendDte": 0,
  "city": "CDMX",
  "state": 0,
  "twitter": "",
  "firstName": "Marcela",
  "id": 67,
  "district": "CDMX",
  "maxCredit": 100000,
  "accumulatePoints": 1,
  "note": "Cliente premiun",
  "phone": "66287196",
  "contacts": {
    "href": "https://api.bsale.com.mx/v1/clients/67/contacts.json"
  },
  "prestashopClienId": 0,
  "activity": "Venta de ropa",
  "hasCredit": 1,
  "facebook": "",
  "company": "Particular",
  "code": "XAXX010101000",
  "href": "https://api.bsale.com.mx/v1/clients/67.json"
}

Cliente extranjero

Si el cliente es extranjero se debe enviar el atributo isForeigner en 1, por defecto este valor es 0, esto es necesario para los documentos de exportación.

{
  "client": {
    "city": "Hawai",
    "company": "Mountain Apple Company Inc",
    "district": "Honolulu",
    "activity": "Musician",
    "address": "izhawaii dot com #100 street",
    "email": "Israel@Kamakawiwo.ole",
    "isForeigner": 1
  }
}

Cliente persona moral

Si el cliente es persona moral, se debe enviar el cliente de la siguiente manera

    "client": {
        "code": "CACX7605101P8",
        "company": "XOCHILT CASAS CHAVEZ",
        "activity": "Giro Informática",
        "district": "Colonia cliente",
        "city": "Ciudad cliente",
        "address": "Dirección cliente",
        "email": "api@bsale.com.mx",
        "postalCode": "10740",
        "regime": "612"
    },

Cliente persona física

Si el cliente es persona física, se debe enviar el cliente de la siguiente manera

    "client": {
        "code": "CACX7605101P8",
        "district": "Colonia cliente",
        "city": "Ciudad cliente",
        "address": "Dirección cliente",
        "firstName": "Andés",
        "lastName": "León",
        "email": "api@bsale.cl",
        "postalCode": "10740",
        "regime": "612"
    },

PUT un cliente

PUT /v1/clients/67.json

Se debe enviar un Json con la siguiente estructura

Ejemplo JSON

Envío

{
  "id": "67",
  "facebook": "",
  "district": "ROMA NORTE",
  "phone": "66287196",
  "activity": "Venta de ropa",
  "city": "CIUDAD DE MEXICO",
  "maxCredit": 100000,
  "hasCredit": 1,
  "lastName": "Muñoz",
  "note": "Cliente premiun",
  "firstName": "Marcela",
  "company": "Particular",
  "address": "Los trigales 372",
  "email": "mmunoz@bsale.com.mx",
  "twitter": "",
  "accumulatePoints": 1,
  "priceListId": 0
}

Respuesta

{
  "companyOrPerson": 0,
  "address": "Los trigales 372",
  "lastName": "Muñoz",
  "sendDte": 0,
  "city": "CIUDAD DE MEXICO",
  "state": 0,
  "twitter": "",
  "firstName": "Marcela",
  "id": 67,
  "district": "ROMA NORTE",
  "maxCredit": 100000,
  "accumulatePoints": 1,
  "note": "Cliente premiun",
  "phone": "66287196",
  "contacts": {
    "href": "https://api.bsale.com.mx/v1/clients/67/contacts.json"
  },
  "prestashopClienId": 0,
  "activity": "Venta de ropa",
  "hasCredit": 1,
  "facebook": "",
  "company": "Particular",
  "code": "XAXX010101000",
  "href": "https://api.bsale.com.mx/v1/clients/67.json"
}

DELETE un cliente virtualmente

DELETE /v1/clients/30.json Cambia el estado del cliente

danger

El cliente no estará visible mediante interfaz y tendrá un state 99. Sus documentos asociado NO se eliminarán.

{
  "href": "https://api.bsale.com.mx/v1/clients/30.json",
  "id": 30,
  "firstName": "Andres",
  "lastName": "Vasquez",
  "code": "XAXX010101000",
  "phone": "220800",
  "company": "Servicios varios",
  "note": "",
  "facebook": "",
  "twitter": "",
  "hasCredit": 1,
  "maxCredit": "9100",
  "state": 1,
  "activity": "",
  "city": "CIUDAD DE MEXICO",
  "district": "ROMA NORTE",
  "address": "Avda. Diego Portales 100",
  "companyOrPerson": 1,
  "sendDte": 0,
  "prestashopClienId": 0,
  "payment_type": {
    "href": "https://api.bsale.com.mx/v1/payment_types/2.json",
    "id": "2"
  },
  "sale_condition": {
    "href": "https://api.bsale.com.mx/v1/sale_conditions/1.json",
    "id": "2"
  },
  "contacts": {
    "href": "https://api.bsale.com.mx/v1/clients/30/contacts.json"
  }
}

PUT puntos de cliente

PUT /v1/clients/points.json

Parámetros

type, 0 aumenta, 1 resta puntos (Boolean)
clientId, Id de cliente (integer).
description, Descripción asociada al registro (String)
points, Cantidad de puntos a registrar (integer)
orderId, Id registro asociado (opcional) (String)

Response /clients/points.json?clientId=54
{
  "type": 0,
  "clientId": 18,
  "description": "Suma puntos 2",
  "points": 1,
  "orderId": "1"
}

Clientes

Estructura JSON​

Atributos​

GET lista de clientes​

Parámetros​

Ejemplos​

GET un cliente​

Parámetros​

Ejemplos​

GET atributos de un cliente​

GET cantidad de clientes​

Contactos​

GET contactos de un cliente​

GET un único contacto de un cliente​

POST un contacto de un cliente​

Ejemplo JSON​

Envío​

Respuesta​

DELETE un contacto de un cliente​

Direcciones​

GET lista de direcciones de un cliente​

Parámetros​

Ejemplos​

GET una única dirección de un cliente​

POST una dirección de un cliente​

Ejemplo JSON​

Envío​

Respuesta​

PUT una dirección de un cliente​

Ejemplo JSON​

Envío​

Respuesta​

DELETE una dirección de un cliente​

Respuesta​

POST un cliente​

Ejemplo JSON​

Envío​

Atributos (opcional)​

Respuesta​

Cliente extranjero​

Cliente persona moral​

Cliente persona física​

PUT un cliente​

Ejemplo JSON​

Envío​

Respuesta​

DELETE un cliente virtualmente​

PUT puntos de cliente​

Parámetros​

Estructura JSON

Atributos

GET lista de clientes

Parámetros

Ejemplos

GET un cliente

Parámetros

Ejemplos

GET atributos de un cliente

GET cantidad de clientes

Contactos

GET contactos de un cliente

GET un único contacto de un cliente

POST un contacto de un cliente

Ejemplo JSON

Envío

Respuesta

DELETE un contacto de un cliente

Direcciones

GET lista de direcciones de un cliente

Parámetros

Ejemplos

GET una única dirección de un cliente

POST una dirección de un cliente

Ejemplo JSON

Envío

Respuesta

PUT una dirección de un cliente

Ejemplo JSON

Envío

Respuesta

DELETE una dirección de un cliente

Respuesta

POST un cliente

Ejemplo JSON

Envío

Atributos (opcional)

Respuesta

Cliente extranjero

Cliente persona moral

Cliente persona física

PUT un cliente

Ejemplo JSON

Envío

Respuesta

DELETE un cliente virtualmente

PUT puntos de cliente

Parámetros