Skip to main content
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.io/v1/clients.json",
"count": 2,
"limit": 25,
"offset": 0,
"items": [
{
"href": "https://api.bsale.io/v1/clients/2.json",
"id": 2,
"firstName": "Francisco",
"lastName": "Pullnom",
"email": "fpull@gmail.com",
"state": 0,
"office": {
"href": "https://api.bsale.io/v1/offices/1.json",
"id": "1"
}
},
{
"href": "https://api.bsale.io/v1/clients/1.json",
"id": 1,
"firstName": "Asistente",
"lastName": "bsale",
"email": "ayuda@bsale.app",
"state": 0,
"office": {
"href": "https://api.bsale.io/v1/offices/1.json",
"id": "1"
}
}
]
}

Atributos

AtributoDescripci贸nTipo dato
hrefurl del clientesString
ididentificador 煤nico del clientesInteger
firstNamenombre del clienteString
lastNameapellido del clienteString
codeRFC del clienteString
phonetel茅fono del clienteString
companyempresa del clienteString
noteuna descripci贸n del clienteString
facebookfacebook del clienteString
twittertwitter del cliente.String
hasCreditindica si el cliente posee cr茅dito No(0) o Si(1)Boolean
maxCreditmonto m谩ximo de cr茅dito del clienteFloat
stateestado del cliente indica si esta activo(0) o inactivo (1)Boolean
activitygiro del clienteString
cityciudad del clienteString
municipalitycomuna del clienteString
companyOrPersonindica si el cliente es persona natural o empresa (0)Persona o (1)EmpresaBoolean
pointscantidad de puntos acumulados del clienteInteger
pointsUpdatedfecha de la 煤ltima actualizaci贸n de puntosInteger
accumulatePointsindica si el cliente acumula puntos No(0) o Si(1)Boolean
sendDteindica si al cliente se le env铆a el XML del DTE No(0) o Si(1)Boolean
prestashopClienIdidentificador en prestashopString
contactsnodo que indica la relaci贸n con los contactos del cliente.
attributesnodo que indica la relaci贸n con los atributos adicionales de un cliente.
addressesnodo 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.io/v1/clients.json",
"count": 112,
"limit": 25,
"offset": 0,
"items": [
{
"href": "https://api.bsale.io/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.io/v1/clients/65/contacts.json"
},
"attributes": {
"href": "https://api.bsale.io/v1/clients/65/attributes.json"
},
"addresses": {
"href": "https//api.bsale.io/v1/clients/65/addresses.json"
}
},
{
"href": "https://api.bsale.io/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.io/v1/clients/102/contacts.json"
},
"attributes": {
"href": "https://api.bsale.io/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.io/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.io/v1/payment_types/1.json",
"id": "1"
},
"price_list": {
"href": "https://api.bsale.io/v1/price_lists/1.json",
"id": "1"
},
"contacts": {
"href": "https://api.bsale.io/v1/clients/2/contacts.json"
},
"attributes": {
"href": "https://api.bsale.io/v1/clients/2/attributes.json"
},
"addresses": {
"href": "https://api.bsale.io/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.io/v1/clients/796/attributes.json",
"count": 4,
"limit": 25,
"offset": 0,
"items": [
{
"href": "https://api.bsale.io/v1/dynamic_attributes/44.json",
"id": 44,
"name": "Rubro",
"value": ""
},
{
"href": "https://api.bsale.io/v1/dynamic_attributes/72.json",
"id": 72,
"name": "NOMBRE FANTASIA",
"value": ""
},
{
"href": "https://api.bsale.io/v1/dynamic_attributes/73.json",
"id": 73,
"name": "Incluir en listas",
"value": ""
},
{
"href": "https://api.bsale.io/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.io/v1/clients/4/contacts.json",
"count": 2,
"limit": 25,
"offset": 0,
"items": [
{
"href": "https://api.bsale.io/v1/clients/4/contacts/31.json",
"id": 31,
"firstName": "Andres",
"lastName": "Villanueva",
"phone": "2220936",
"email": "a.villanueva@gmail.com"
},
{
"href": "https://api.bsale.io/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.io/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.io/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.io/v1/clients/55/addresses.json",
"count": 2,
"limit": 25,
"offset": 0,
"items": [
{
"href": "https://api.bsale.io/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.io/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.io/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.io/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.io/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.io/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.io/v1/clients/67/contacts.json"
},
"prestashopClienId": 0,
"activity": "Venta de ropa",
"hasCredit": 1,
"facebook": "",
"company": "Particular",
"code": "XAXX010101000",
"href": "https://api.bsale.io/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.io/v1/clients/67/contacts.json"
},
"prestashopClienId": 0,
"activity": "Venta de ropa",
"hasCredit": 1,
"facebook": "",
"company": "Particular",
"code": "XAXX010101000",
"href": "https://api.bsale.io/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.io/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.io/v1/payment_types/2.json",
"id": "2"
},
"sale_condition": {
"href": "https://api.bsale.io/v1/sale_conditions/1.json",
"id": "2"
},
"contacts": {
"href": "https://api.bsale.io/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"
}