Skip to main content
Version: 📄 MX

Devoluciones

Endpoint para la generación de documentos del tipo devolución/anulaciones de ventas. (Nota de crédito electrónica, nota de débito electrónica).

info

Siempre se debe referenciar el id del documento venta que se desea devolver junto a sus detalles.

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

  • Creación de nota de crédito Ver

Estructura JSON

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

Response /returns/1.json
{
"href": "https://api.bsale.com.mx/v1/returns/1.json",
"id": 1,
"code": "137615600351",
"returnDate": 1376107200,
"motive": "Cambio a Factura",
"type": 1,
"priceAdjustment": 0,
"editTexts": 0,
"amount": 27541,
"office": {
"href": "https://api.bsale.com.mx/v1/offices/1.json",
"id": "1"
},
"reference_document": {
"href": "https://api.bsale.com.mx/v1/documents/472.json",
"id": "472"
},
"credit_note": {
"href": "https://api.bsale.com.mx/v1/documents/477.json",
"id": "477"
},
"details": {
"href": "https://api.bsale.com.mx/v1/returns/1/details.json"
}
}

Atributos

AtributoDescripciónTipo dato
hrefurl de la devoluciónString
ididentificador único de la devoluciónInteger
codecódigo interno único de la la devoluciónString
returnDatefecha de la devoluciónInteger
motiverazón de por que fue efectuada la devoluciónString
typeidentifica si la forma de pago de la devoluciónInteger
priceAdjustmentindica si la nota de crédito relacionada fue por ajuste de precio No(0) o Si(1)Boolean
editTextsindica si la nota de crédito relacionada fue por corrección de texto (forma) No(0) o Si(1)Boolean
amountmonto total de la devoluciónFloat
officenodo que indica la relación con la sucursal en la que fue emitida la devolución.
reference_documentnodo que indica la relación con el documento de referencia que se devuelve.
credit_notenodo que indica el documento nota de crédito.
detailsnodo que indica los detalles de la devolución.

GET lista de devoluciones

  • GET /v1/returns.json retorna todas las devoluciones.

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.
  • returndate, Permite filtrar por fecha de devolución.
  • code, filtra por código de la devolución.
  • type, filtra por tipo de devolución.
  • officeid, Permite filtrar por sucursal.
  • referencedocumentid, filtra por documento de referencia.
  • creditnoteid, filtra por el id de la nota de crédito.

Ejemplos

  • GET /v1/returns.json?limit=10&offset=0
  • GET /v1/returns.json?fields=[returndate,motive]
  • GET /v1/returns.json?expand=[reference_document,credit_note,details]
Response /returns.json
{
"href": "https://api.bsale.com.mx/v1/returns.json",
"count": 49,
"limit": 2,
"offset": 0,
"items": [
{
"href": "https://api.bsale.com.mx/v1/returns/1.json",
"id": 1,
"code": "137615600351",
"returnDate": 1376107200,
"motive": "Cambio a Factura",
"type": 1,
"priceAdjustment": 0,
"editTexts": 0,
"amount": 27541,
"office": {
"href": "https://api.bsale.com.mx/v1/offices/1.json",
"id": "1"
},
"reference_document": {
"href": "https://api.bsale.com.mx/v1/documents/472.json",
"id": "472"
},
"credit_note": {
"href": "https://api.bsale.com.mx/v1/documents/477.json",
"id": "477"
},
"details": {
"href": "https://api.bsale.com.mx/v1/returns/1/details.json"
}
},
{
"href": "https://api.bsale.com.mx/v1/returns/2.json",
"id": 2,
"code": "137668322351",
"returnDate": 1376625600,
"motive": "error de ventas",
"type": 0,
"priceAdjustment": 0,
"editTexts": 0,
"amount": 21488,
"office": {
"href": "https://api.bsale.com.mx/v1/offices/1.json",
"id": "1"
},
"reference_document": {
"href": "https://api.bsale.com.mx/v1/documents/527.json",
"id": "527"
},
"credit_note": {
"href": "https://api.bsale.com.mx/v1/documents/529.json",
"id": "529"
},
"details": {
"href": "https://api.bsale.com.mx/v1/returns/2/details.json"
}
}
]
}

GET una devolución

  • GET /v1/returns/1.json retorna una única devolución.

Parámetros

  • expand, permite expandir instancias y colecciones.

Ejemplos

  • GET /v1/returns/1.json?expand=[credit_note]
Response /returns.json
{
"href": "https://api.bsale.com.mx/v1/returns/1.json",
"id": 1,
"code": "137615600351",
"returnDate": 1376107200,
"motive": "Cambio a Factura",
"type": 1,
"priceAdjustment": 0,
"editTexts": 0,
"amount": 27541,
"office": {
"href": "https://api.bsale.com.mx/v1/offices/1.json",
"id": "1"
},
"reference_document": {
"href": "https://api.bsale.com.mx/v1/documents/472.json",
"id": "472"
},
"credit_note": {
"href": "https://api.bsale.com.mx/v1/documents/477.json",
"id": "477"
},
"details": {
"href": "https://api.bsale.com.mx/v1/returns/1/details.json"
}
}

GET detalles de una devolución

  • GET /v1/returns/1/details.json
Response /returns/1/details.json
{
"href": "https://api.bsale.com.mx/v1/returns/1/details.json",
"count": 2,
"limit": 25,
"offset": 0,
"items": [
{
"href": "https://api.bsale.com.mx/v1/returns/1/details/1.json",
"id": 1,
"quantity": 2.8,
"quantityDevStock": 2.8,
"variantStock": 59.37,
"variantCost": 3200
},
{
"href": "https://api.bsale.com.mx/v1/returns/1/details/2.json",
"id": 2,
"quantity": 1.64,
"quantityDevStock": 1.64,
"variantStock": 45.44,
"variantCost": 3200
}
]
}

GET un detalle de una devolución

  • GET /v1/returns/1/details/1.json
Response /returns/1/details/1.json
{
"href": "https://api.bsale.com.mx/v1/returns/1/details/1.json",
"id": 1,
"quantity": 2.8,
"quantityDevStock": 2.8,
"variantStock": 59.37,
"variantCost": 3200.0
}

POST una devolución

  • POST /v1/returns.json Para crear una devolución y su respectiva nota da crédito se debe enviar un JSON con la siguiente estructura:

Referencias y fechas

{
"documentTypeId": 9,
"officeId": 1,
"referenceDocumentId": 11528,
"emissionDate": 1407384000,
"motive": "Bonificación por pago",
"declare": 1,
"priceAdjustment": 1,
"editTexts": 0,
"type": 1
}
  • documentTypeId, Id del tipo de documento que indicara si es factura, boleta, nota de venta etc. (Integer).
  • officeId, Id de la sucursal donde se emite el documento, si no es especificada el documento quedara asignado a la sucursal por defecto del sistema (Integer).
  • referenceDocumentId, Id del documento original al cual se le va hacer la devolución (Integer).
  • emissionDate, Fecha de emisión de la devolución, se envía en formato GMT (Integer).
  • expirationDate, Fecha vencimiento de la devolución, se envía en formato GMT (Integer).
  • motive, Indica el motivo de la devolución (String).
  • declare, Si se desea declarar el documento al Servicio de impuestos internos se envía 1, en caso contrario un 0 (Boolean).
  • priceAdjustment, Si la devolución corresponde a un ajuste de precio de los productos se envía 1, en caso contrario 0 (Boolean).
  • type, Indica como se va a devolver el dinero del documento, 0 para devolución dinero, 1 para forma pago nueva venta, 2 para abono linea de crédito (Condonación), 3 para otra devolución (Integer).

Cliente de una devolución

Para las notas de crédito es obligatorio especificar el cliente.

note

Para le generación de devoluciones, el cliente es obligatorio. Si el documento de referencia tiene asociado datos de cliente, se deben indicar los mismos datos en la devolución.

{
"client": {
"code": "XAXX010101000",
"city": "Ciudad de México",
"district": "JUAREZ",
"company": "PUBLICO EN GENERAL",
"address": "VARSOVIA 111"
}
}
  • code, Rut del cliente (String).
  • city, Ciudad del cliente (String).
  • company, Razón social del cliente (String).
  • municipality, Comuna del cliente (String).
  • activity, Giro del cliente (String).
  • address, Dirección del cliente (String).
  • firstName, Nombre de persona (String).
  • lastName, Apellido de persona (String).

Detalles de la devolución

Tipos de una devolución

Si se desea crear una devolución para ajustar el precio de los productos, se debe enviar el editTexts en 0 y el priceAdjustment en 1, ademas de enviar en el nodo details solo los detalles que van a cambiar de precio del documento original (quantity = 0, unitValue = nuevo precio)
tip

Además de indicar el referenceDocumentId se debe referenciar el id de detalle de la venta: documentDetailId

Ejemplo devolución cantidades
{
"details": [
{
"documentDetailId": 21493,
"quantity": 1,
"unitValue": 0
}
]
}
tip

Opcionalmente si generas una nota de crédito que ajusta el precio del documento original, puedes cambiar la descripcion del del item con el atributo comment

Ejemplo ajuste de precios
{
"details": [
{
"documentDetailId": 21493,
"comment": "Nueva descripción del item",
"quantity": 1,
"unitValue": 0
}
]
}
  • documentDetailId, Id del [detalle del documento] original que se va a devolver (Integer).
  • quantity, Cantidad a devolver (Float).
  • unitValue, Valor unitario neto del detalle (String). [detalle del documento]

Forma de pago en nueva venta

tip

Para generar este tipo de devolución es obligatorio especificar el cliente.

    "payments": [
{
"recordDate": 1639667641,
"amount": 11900,
"paymentTypeId": 3,
"documentTypeId": 9,
"number": 125
}
]
  • documentTypeId, Id del tipo de documento de la nota de crédito (Integer).
  • number, folio de la nota de crédito devolución (Integer).

Ejemplo JSON

Envío

POST /returns.json
{
"documentTypeId": 9,
"officeId": 1,
"expirationDate": 1407384000,
"emissionDate": 1407384000,
"referenceDocumentId": 11528,
"motive": "Descuento o bonificación",
"declareSii": 1,
"priceAdjustment": 1,
"editTexts": 0,
"type": 1,
"client": {
"code": "XAXX010101000",
"city": "Ciudad de México",
"district": "JUAREZ",
"company": "PUBLICO EN GENERAL",
"address": "VARSOVIA 111"
},
"details": [
{
"documentDetailId": 21493,
"quantity": 0,
"unitValue": 1250
}
]
}

Respuesta

201 Response /returns.json
{
"credit_note": {
"href": "https://api.bsale.com.mx/v1/documents/11539.json",
"id": "11539"
},
"reference_document": {
"href": "https://api.bsale.com.mx/v1/documents/11528.json",
"id": "11528"
},
"amount": 6490,
"code": "140745397411",
"type": 1,
"editTexts": 0,
"href": "https://api.bsale.com.mx/v1/returns/71.json",
"returnDate": 1407384000,
"details": {
"href": "https://api.bsale.com.mx/v1/returns/71/details.json"
},
"office": {
"href": "https://api.bsale.com.mx/v1/offices/1.json",
"id": "1"
},
"motive": "Descuento o bonificación",
"priceAdjustment": 0,
"id": 71
}