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.

Estructura JSON

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

{
    "href": "https://api.bsale.com.pe/v1/clients/76.json",
    "id": 76,
    "firstName": "Gabriel",
    "lastName": "Seguel",
    "email": "gseguel@ejemplo.com.pe",
    "code": "",
    "phone": "",
    "company": "Gabriel Seguel",
    "note": "",
    "facebook": "",
    "twitter": "",
    "hasCredit": 0,
    "maxCredit": null,
    "state": 0,
    "activity": "Sin Giro",
    "city": "Lima",
    "district": "Miraflores",
    "address": "Av  Alfredo Benavides",
    "companyOrPerson": 0,
    "accumulatePoints": 1,
    "points": 0.0,
    "pointsUpdated": "",
    "sendDte": 0,
    "isForeigner": 0,
    "prestashopClienId": 0,
    "createdAt": 1576528834,
    "updatedAt": 1576528834,
    "payment_type": {
        "href": "https://api.bsale.com.pe/v1/payment_types/1.json",
        "id": "1"
    },
    "price_list": {
        "href": "https://api.bsale.com.pe/v1/price_lists/1.json",
        "id": "1"
    },
    "contacts": {
        "href": "https://api.bsale.com.pe/v1/clients/76/contacts.json"
    },
    "attributes": {
        "href": "https://api.bsale.com.pe/v1/clients/76/attributes.json"
    },
    "addresses": {
        "href": "https://api.bsale.com.pe/v1/clients/76/addresses.json"
    }
}
  • href, url del cliente (String).
  • id, identificador único del cliente (Integer).
  • firstName, nombre del cliente (String).
  • lastName, apellido del cliente (String).
  • code, ruc 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.
  • 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).
  • district, distrito 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 retornara todos los clientes.

####Parametros

  • 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.
  • code, Permite filtrar por ruc 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?code=1-9
  • GET /v1/clients.json?paymenttypeid=1
  • GET /v1/clients.json?expand=[contacts,attributes,payment_type]

####Respuesta

{
    "href": "https://api.bsale.com.pe/v1/clients.json",
    "count": 76,
    "limit": 3,
    "offset": 0,
    "items": [
        {
            "href": "https://api.bsale.com.pe/v1/clients/2.json",
            "id": 2,
            "firstName": null,
            "lastName": "",
            "email": "someemail@imaginex.cl",
            "code": "1-9",
            "phone": null,
            "company": "Imaginex",
            "note": null,
            "facebook": null,
            "twitter": null,
            "hasCredit": null,
            "maxCredit": 0.0,
            "state": 0,
            "activity": "giro",
            "city": "Puerto Varas",
            "district": "distrito",
            "address": "direccion",
            "companyOrPerson": 1,
            "accumulatePoints": 0,
            "points": 0.0,
            "pointsUpdated": "",
            "sendDte": 0,
            "isForeigner": null,
            "prestashopClienId": 0,
            "createdAt": 1529818364,
            "updatedAt": 1575590167,
            "contacts": {
                "href": "https://api.bsale.com.pe/v1/clients/2/contacts.json"
            },
            "attributes": {
                "href": "https://api.bsale.com.pe/v1/clients/2/attributes.json"
            },
            "addresses": {
                "href": "https://api.bsale.com.pe/v1/clients/2/addresses.json"
            }
        },
        {
            "href": "https://api.bsale.com.pe/v1/clients/12.json",
            "id": 12,
            "firstName": null,
            "lastName": "",
            "email": "someemail@imaginex.cl",
            "code": "045612547",
            "phone": null,
            "company": "Imaginex",
            "note": null,
            "facebook": null,
            "twitter": null,
            "hasCredit": null,
            "maxCredit": 0.0,
            "state": 0,
            "activity": "giro",
            "city": "Puerto Varas",
            "district": "comuna",
            "address": "direccion",
            "companyOrPerson": 1,
            "accumulatePoints": 0,
            "points": 0.0,
            "pointsUpdated": "",
            "sendDte": 0,
            "isForeigner": 1,
            "prestashopClienId": 0,
            "createdAt": 1550064848,
            "updatedAt": 1550064848,
            "contacts": {
                "href": "https://api.bsale.com.pe/v1/clients/12/contacts.json"
            },
            "attributes": {
                "href": "https://api.bsale.com.pe/v1/clients/12/attributes.json"
            },
            "addresses": {
                "href": "https://api.bsale.com.pe/v1/clients/12/addresses.json"
            }
        },
        {
            "href": "https://api.bsale.com.pe/v1/clients/13.json",
            "id": 13,
            "firstName": null,
            "lastName": "",
            "email": null,
            "code": "123456",
            "phone": null,
            "company": "Imaginex",
            "note": null,
            "facebook": null,
            "twitter": null,
            "hasCredit": null,
            "maxCredit": 0.0,
            "state": 0,
            "activity": "giro",
            "city": "Puerto Varas",
            "district": "comuna",
            "address": "direccion",
            "companyOrPerson": 1,
            "accumulatePoints": 0,
            "points": 0.0,
            "pointsUpdated": "",
            "sendDte": 0,
            "isForeigner": null,
            "prestashopClienId": 0,
            "createdAt": 1550073539,
            "updatedAt": 1550073539,
            "contacts": {
                "href": "https://api.bsale.com.pe/v1/clients/13/contacts.json"
            },
            "attributes": {
                "href": "https://api.bsale.com.pe/v1/clients/13/attributes.json"
            },
            "addresses": {
                "href": "https://api.bsale.com.pe/v1/clients/13/addresses.json"
            }
        }
    ],
    "next": "https://api.bsale.com.pe/v1/clients.json?limit=3&offset=3"
}

GET único cliente

  • GET /v1/clients/76.json retornara un cliente específico.

####Parametros

  • expand, permite expandir instancias y colecciones.

####Ejemplos

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

####Respuesta

{
    "href": "https://api.bsale.com.pe/v1/clients/76.json",
    "id": 76,
    "firstName": "Gabriel",
    "lastName": "Seguel",
    "email": "gseguel@ejemplo.com.pe",
    "code": "",
    "phone": "",
    "company": "Gabriel Seguel",
    "note": "",
    "facebook": "",
    "twitter": "",
    "hasCredit": 0,
    "maxCredit": null,
    "state": 0,
    "activity": "Sin Giro",
    "city": "Lima",
    "district": "Miraflores",
    "address": "Av  Alfredo Benavides",
    "companyOrPerson": 0,
    "accumulatePoints": 1,
    "points": 0.0,
    "pointsUpdated": "",
    "sendDte": 0,
    "isForeigner": 0,
    "prestashopClienId": 0,
    "createdAt": 1576528834,
    "updatedAt": 1576528834,
    "payment_type": {
        "href": "https://api.bsale.com.pe/v1/payment_types/1.json",
        "id": "1"
    },
    "price_list": {
        "href": "https://api.bsale.com.pe/v1/price_lists/1.json",
        "id": "1"
    },
    "contacts": {
        "href": "https://api.bsale.com.pe/v1/clients/76/contacts.json"
    },
    "attributes": {
        "href": "https://api.bsale.com.pe/v1/clients/76/attributes.json"
    },
    "addresses": {
        "href": "https://api.bsale.com.pe/v1/clients/76/addresses.json"
    }
}


GET lista de contactos de un cliente

  • GET /v1/clients/76/contacts.json
{
    "href": "https://api.bsale.com.pe/v1/clients/76/contacts.json",
    "count": 2,
    "limit": 25,
    "offset": 0,
    "items": [
        {
            "href": "https://api.bsale.com.pe/v1/clients/76/contacts/2.json",
            "id": 2,
            "firstName": "Hernan",
            "lastName": "Saez",
            "phone": "994282800",
            "email": "hsaez@ejemplo.com.pe"
        },
        {
            "href": "https://api.bsale.com.pe/v1/clients/76/contacts/3.json",
            "id": 3,
            "firstName": "Romina",
            "lastName": "Rodriguez",
            "phone": "970010002",
            "email": "rrodriguez@ejemplo.com.pe"
        }
    ]
}

GET un único contacto de un cliente

  • GET /v1/clients/76/contacts/2.json
{
    "href": "https://api.bsale.com.pe/v1/clients/76/contacts/2.json",
    "id": 2,
    "firstName": "Hernan",
    "lastName": "Saez",
    "phone": "994282800",
    "email": "hsaez@ejemplo.com.pe"
}

POST un contacto de un cliente

  • POST /v1/clients/76/contacts.json

Se debe enviar un Json con la siguiente estructura.

{
    "href": "https://api.bsale.com.pe/v1/clients/76/contacts/4.json",
    "id": 4,
    "firstName": "Juan",
    "lastName": "Matamala",
    "phone": "966542311",
    "email": "jmatamala@gmail.com"
}

####Respuesta

{
    "href": "https://api.bsale.com.pe/v1/clients/76/contacts/1.json",
    "id": 1,
    "firstName": "Juan",
    "lastName": "Matamala",
    "phone": "966542311",
    "email": "jmatamala@gmail.com"
}

DELETE un contacto de un cliente

  • DELETE /v1/clients/76/contacts/1.json elimina el contacto respondiendo un estado HTTP 204

GET lista de direcciones de un cliente

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

####Parámetros

  • address, permite filtrar por dirección (String).
  • city, permite filtrar por ciudad (String).
  • district, permite filtrar por distrito (String).
  • state, permite filtrar por estado (Boolean).

####Ejemplos

  • GET /v1/clients/76/addresses.json?address=la quebrada 1189
  • GET /v1/clients/76/addresses.json?city=santiago
  • GET /v1/clients/76/addresses.json?city=santiago&district=providencia
  • GET /v1/clients/76/addresses.json?state=0
{
    "href": "https://api.bsale.com.pe/v1/clients/76/addresses.json",
    "count": 2,
    "limit": 25,
    "offset": 0,
    "items": [
        {
            "href": "https://api.bsale.com.pe/v1/clients/76/addresses/1.json",
            "id": 1,
            "addressName": "Sucursal 1",
            "address": "Calle Bellavista",
            "city": "Lima",
            "district": "Miraflores",
            "state": 0
        },
        {
            "href": "https://api.bsale.com.pe/v1/clients/76/addresses/2.json",
            "id": 2,
            "addressName": "Sucursal 2",
            "address": "Calle Bellavista 2",
            "city": "Lima",
            "district": "Miraflores",
            "state": 0
        }
    ]
}

GET una única dirección de un cliente

  • GET /v1/clients/76/addresses/2.json
{
    "href": "https://api.bsale.com.pe/v1/clients/76/addresses/2.json",
    "id": 2,
    "addressName": "Sucursal 2",
    "address": "Calle Bellavista 2",
    "city": "Lima",
    "district": "Miraflores",
    "state": 0
}

POST una dirección de un cliente

  • POST /v1/clients/76/addresses.json

Se debe enviar un Json con la siguiente estructura.

{
  "addressName": "Sucursal 3",
  "address": "Calle Bellavista 69",
  "city": "Lima",
  "district": "Miraflores"
}

####Respuesta

{
    "href": "https://api.bsale.com.pe/v1/clients/76/addresses/3.json",
    "id": 3,
    "addressName": "Sucursal 3",
    "address": "Calle Bellavista 69",
    "city": "Lima",
    "district": "Miraflores",
    "state": 0
}

PUT una dirección de un cliente

  • PUT /v1/clients/76/addresses/3.json

Se debe enviar un Json con la siguiente estructura.

{
  "addressName": "Sucursal 3",
  "address": "Calle Libertad n XXXX",
  "city": "Lima",
  "district": "Miraflores"
}

####Respuesta

{
    "href": "https://api.bsale.com.pe/v1/clients/76/addresses/3.json",
    "id": 3,
    "addressName": "Sucursal 3",
    "address": "Calle Libertad n XXXX",
    "city": "Lima",
    "district": "Miraflores",
    "state": 0
}

DELETE una dirección de un cliente

  • DELETE /v1/clients/76/addresses/3.json cambia el estado de una dirección.

####Respuesta

{
    "href": "https://api.bsale.com.pe/v1/clients/76/addresses/3.json",
    "id": 3,
    "addressName": "Sucursal 3",
    "address": "Calle Libertad n XXXX",
    "city": "Lima",
    "district": "Miraflores",
    "state": 1
}

GET atributos de un cliente

  • GET /v1/clients/76/attributes.json

####Respuesta

{
    "href": "https://api.bsale.com.pe/v1/clients/76/attributes.json",
    "count": 3,
    "limit": 25,
    "offset": 0,
    "items": [
        {
            "href": "https://api.bsale.com.pe/v1/dynamic_attributes/32.json",
            "id": 32,
            "name": "Cumpleaños",
            "value": "04/12/2019"
        },
        {
            "href": "https://api.bsale.com.pe/v1/dynamic_attributes/33.json",
            "id": 33,
            "name": "Edad",
            "value": "32"
        },
        {
            "href": "https://api.bsale.com.pe/v1/dynamic_attributes/34.json",
            "id": 34,
            "name": "Producto Más Comprado",
            "value": "Chocolate Amargo"
        }
    ]
}

GET cantidad de clientes

  • GET /v1/clients/count.json

####Parametros

  • state, permite filtrar por estado, activos (0) inactivos (1).

####Respuesta

{
  "count": 66
}

GET documentos pendientes de pago

  • GET /v1/clients/unpaid_documents.json

####Parametros

  • clientid, Permite filtrar por id del cliente.
  • code, Permite filtrar por ruc del cliente.
  • comparisondate, Permite separar los documentos vencidos de los por vencer, por defecto es la fecha del momento de la consulta.

####Ejemplos

  • GET /v1/clients/unpaid_documents.json?code=7513098-8
  • GET /v1/clients/unpaid_documents.json?clientid=1
  • GET /v1/clients/unpaid_documents.json?comparisondate=1437436800
  • GET /v1/clients/unpaid_documents.json?code=7513098-8&comparisondate=1437436800

####Respuesta

{
  "overdueDebt": 40000,
  "upcomingDebt": 30000,
  "totalDebt": 70000,
  "client": {
    "href": "https://api.bsale.com.pe/v1/clients/1.json",
    "id": 1,
    "firstName": "Roberto",
    "lastName": "",
    "code": "7513098-8",
    "company": "Roberto Manquilla"
  },
  "overdue_documents": [
    {
      "href": "https://api.bsale.com.pe/v1/documents/6514.json",
      "id": 6514,
      "name": "Factura Electronica",
      "number": 123123123217,
      "emissionDate": 1437436800,
      "expirationDate": 1437436800,
      "totalAmount": 20000,
      "totalAmountOwed": 20000
    },
    {
      "href": "https://api.bsale.com.pe/v1/documents/6515.json",
      "id": 6515,
      "name": "Factura Electronica",
      "number": 123123123218,
      "emissionDate": 1437436800,
      "expirationDate": 1437436800,
      "totalAmount": 20000,
      "totalAmountOwed": 20000
    }
  ],
  "upcoming_documents": [
    {
      "href": "https://api.bsale.com.pe/v1/documents/6520.json",
      "id": 6520,
      "name": "Factura Electronica",
      "number": 123123123220,
      "emissionDate": 1437523200,
      "expirationDate": 1440201600,
      "totalAmount": 30000,
      "totalAmountOwed": 30000
    }
  ]
}
  • overdueDebt, deuda vencida (Float).
  • upcomingDebt, deuda por vencer (Float).
  • totalDebt, deuda total (Float).
  • client, nodo que indica el cliente al cual se le emitieron los documentos.
  • overdue_documents, nodo que indica los documentos vencidos.
  • upcoming_documents, nodo que indica los documentos por vencer.

POST un cliente

  • POST /v1/clients.json

Se debe enviar un Json con la siguiente estructura.

{
  "facebook": "",
  "district": "Miraflores",
  "phone": "66287196",
  "activity": "Venta de ropa",
  "city": "Santiago",
  "maxCredit": 100000,
  "hasCredit": 1,
  "accumulatePoints":1,
  "lastName": "Muñoz",
  "note": "Cliente ingresado por canal venta",
  "firstName": "Marcela",
  "company": "Particular",
  "address": "Los trigales 372",
  "email": "api@bsale.cl",
  "twitter": "",
  "code": "2-7"
}

También se pueden enviar atributos dinámicos al momento de crear el cliente

{
  "facebook": "",
  "district": "Miraflores",
  "phone": "66287196",
  "activity": "Venta de ropa",
  "city": "Santiago",
  "maxCredit": 100000,
  "hasCredit": 1,
  "accumulatePoints":1,
  "lastName": "Muñoz",
  "note": "Cliente ingresado por canal venta",
  "firstName": "Marcela",
  "company": "Particular",
  "address": "Los trigales 372",
  "email": "api@bsale.cl",
  "twitter": "",
  "code": "2-7",
  "dynamicAttributes": [
    {
      "description": "21/03/1983",
      "dynamicAttributeId": 24
    }
  ]
}

####Respuesta

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

PUT un cliente

  • PUT /v1/clients/67.json

Se debe enviar un Json con la siguiente estructura.

{
  "id": "67",
  "facebook": "",
  "district": "Puerto Montt",
  "phone": "66287196",
  "activity": "Venta de ropa",
  "city": "Puerto Montt",
  "maxCredit": 100000,
  "hasCredit": 1,
  "lastName": "Muñoz",
  "note": "Cliente premiun",
  "firstName": "Marcela",
  "company": "Particular",
  "address": "Los trigales 372",
  "email": "mmunoz@.email.cl",
  "twitter": "",
  "accumulatePoints":1,
}

####Respuesta

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

DELETE un cliente

  • DELETE /v1/clients/30.json cambia el estado del cliente.
{
  "href": "https://api.bsale.com.pe/v1/clients/30.json",
  "id": 30,
  "firstName": "Andres",
  "lastName": "Vasquez",
  "code": "1-9",
  "phone": "220800",
  "company": "Servicios varios",
  "note": "",
  "facebook": "",
  "twitter": "",
  "hasCredit": 1,
  "maxCredit": "9100",
  "state": 1,
  "activity": "",
  "city": "Puerto Montt",
  "district": "Puerto Montt",
  "address": "Avda. Diego Portales 100",
  "companyOrPerson": 1,
  "sendDte": 0,
  "prestashopClienId": 0,
  "payment_type": {
    "href": "https://api.bsale.com.pe/v1/payment_types/2.json",
    "id": "2"
  },
  "sale_condition": {
    "href": "https://api.bsale.com.pe/v1/sale_conditions/1.json",
    "id": "2"
  },
  "contacts": {
    "href": "https://api.bsale.com.pe/v1/clients/30/contacts.json"
  }
}