Ejemplos

En esta sección, se consolidan ejemplos prácticos de los payloads en formato JSON para las peticiones y respuestas más comunes al interactuar con la API de EMIZOR. Estos ejemplos te servirán de referencia rápida durante tu desarrollo.

1. Autenticación (Obtener Token)

Para consumir la mayoría de los servicios, necesitas obtener un token Bearer enviando tus credenciales.

Petición (Request):

{
  "grant_type": "client_credentials",
  "client_id": "<TU_CLIENT_ID_PROVISTO_POR_EMIZOR>",
  "client_secret": "<TU_CLIENT_SECRET_PROVISTO_POR_EMIZOR>"
}

Respuesta Exitosa (200 OK):

{
  "token_type": "Bearer",
  "expires_in": 31536000,
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImp0..."
}

2. Validación de NIT

Antes de emitir una factura con un NIT específico, es recomendable validarlo.

Respuesta Exitosa (200 OK):

{
  "status": "success",
  "data": {
    "codigo": 0,
    "descripcion": "ACTIVO"
  }
}

Nota: Si el código es 0, el NIT es válido. Si es 1, es inválido (y requiere confirmación del usuario para forzar la emisión).

3. Creación de un Punto de Venta

Si necesitas crear un punto de venta mediante la API para una sucursal específica.

Petición (Request):

{
  "nombre": "Ventas Mostrador 1",
  "descripcion": "Caja principal de la sucursal",
  "tipo": 0
}

Respuesta Exitosa (200 OK):

{
  "status": "success",
  "data": {
    "codigo": 1,
    "nombre": "Ventas Mostrador 1",
    "descripcion": "Caja principal de la sucursal",
    "tipo": {
      "codigo": 0,
      "descripcion": "Punto de Venta Fijo"
    },
    "codigoSucursal": 0
  }
}

4. Emisión de Factura de Compra-Venta

El siguiente es un payload completo de ejemplo para emitir una factura estándar de Compra-Venta. Asegúrate de incluir el branchCode (Código de la sucursal) en la URL al realizar la petición.

Petición (Request):

{
  "numeroFactura": 9999999998,
  "nombreRazonSocial": "Juan Perez",
  "codigoPuntoVenta": 9999,
  "fechaEmision": "2021-01-25T18:03:00.000Z",
  "cafc": "101A6A36DA839",
  "codigoExcepcion": 0,
  "descuentoAdicional": 0,
  "montoGiftCard": 0,
  "codigoTipoDocumentoIdentidad": 5,
  "numeroDocumento": "12345678",
  "complemento": "",
  "codigoCliente": "CLI-001",
  "codigoMetodoPago": 26,
  "numeroTarjeta": 10000000000000000,
  "montoTotal": 100.50,
  "codigoMoneda": 154,
  "montoTotalMoneda": 100.50,
  "usuario": "roberto.lopez",
  "emailCliente": "juan.perez@example.com",
  "telefonoCliente": "70000000",
  "extras": {
    "uniqueCode": "UNIQ-12345",
    "facturaTicket": "TICKET-98765"
  },
  "codigoLeyenda": 1,
  "montoTotalSujetoIva": 100.50,
  "tipoCambio": 1,
  "detalles": [
    {
      "codigoProducto": "PROD-A01",
      "codigoActividadSin": "106110",
      "codigoProductoSin": 99999999,
      "descripcion": "Producto de Ejemplo A",
      "unidadMedida": 57,
      "precioUnitario": 50.25,
      "subTotal": 100.50,
      "cantidad": 2,
      "numeroSerie": "",
      "montoDescuento": 0,
      "numeroImei": ""
    }
  ]
}

Nota: Los valores como codigoMoneda (154 = Boliviano), codigoTipoDocumentoIdentidad (5 = NIT) y unidadMedida (57 = Unidad) deben ser obtenidos previamente mediante los servicios de sincronización paramétrica.

Ejemplo de emisión de facturas en diferentes escenarios

EJEMPLO #1

Usando CI
Descuento por producto y adicional (montoDescuento, descuentoAdicional) respectivamente
Código de unidad usado 57 (productos)

{
  "numeroFactura": 1,
  "codigoTipoDocumentoIdentidad": 1,
  "complemento": null,
  "usuario": "Jorge",
  "montoTotal": 140,
  "montoTotalSujetoIva": 140,
  "emailCliente": "Jorge.ramos@example.com",
  "telefonoCliente": null,
  "codigoCliente": "cod-234234",
  "numeroDocumento": "7643242",
  "nombreRazonSocial": "Manuel Garcia",
  "detalles": [
    {
      "subTotal": 150,
      "montoDescuento": 18,
      "unidadMedida": 57,
      "codigoProducto": "HAM-0923",
      "codigoActividadSin": "610000",
      "codigoProductoSin": 99100,
      "cantidad": 8,
      "precioUnitario": 21,
      "descripcion": "Hamburguesa doble queso"
    }
  ],
  "extras":{
    "terminos":"Términos de facturación",
    "notas":"Notas adicionales de la factura",
    "nombreContacto":"Mario Borges",
    "facturaTicket":"f1025-F5G645FT01"
  },
  "descuentoAdicional": 10
}

EJEMPLO #2

El cliente no provee datos para su facturación
Descuento por producto y adicional (montoDescuento, descuentoAdicional) respectivamente
Código de unidad usado 57 (productos)

{
  "numeroFactura": 1,
  "codigoTipoDocumentoIdentidad": 5,
  "complemento": null,
  "usuario": "Jorge",
  "montoTotal": 140,
  "montoTotalSujetoIva": 140,
  "emailCliente": "Jorge.ramos@example.com",
  "telefonoCliente": null,
  "codigoCliente": "cod-234234",
  "numeroDocumento": "99002",
  "nombreRazonSocial": "CONTROL TRIBUTARIO",
  "detalles": [
    {
      "subTotal": 150,
      "montoDescuento": 18,
      "unidadMedida": 57,
      "codigoProducto": "HAM-0923",
      "codigoActividadSin": "610000",
      "codigoProductoSin": 99100,
      "cantidad": 8,
      "precioUnitario": 21,
      "descripcion": "Hamburguesa doble queso"
    }
  ],
  "extras":{
    "terminos":"Términos de facturación",
    "notas":"Notas adicionales de la factura",
    "nombreContacto":"Mario Borges",
    "facturaTicket":"f1025-F5G645FT02"
  },
  "descuentoAdicional": 10
}

EJEMPLO #3

Usando NIT (codigoTipoDocumentoIdentidad = 5)
Descuento por producto y adicional (montoDescuento, descuentoAdicional) respectivamente
Código de unidad usado 57 (productos)

{
  "numeroFactura": 1,
  "codigoTipoDocumentoIdentidad": 5,
  "complemento": null,
  "usuario": "Jorge",
  "montoTotal": 140,
  "montoTotalSujetoIva": 140,
  "emailCliente": "Jorge.ramos@example.com",
  "telefonoCliente": null,
  "codigoCliente": "cod-234234",
  "numeroDocumento": "1239823101",
  "codigoExcepcion": "0",
  "nombreRazonSocial": "EMPRESA S.R.L.",
  "detalles": [
    {
      "subTotal": 150,
      "montoDescuento": 18,
      "unidadMedida": 57,
      "codigoProducto": "HAM-0923",
      "codigoActividadSin": "610000",
      "codigoProductoSin": 99100,
      "cantidad": 8,
      "precioUnitario": 21,
      "descripcion": "Hamburguesa doble queso",
      "facturaTicket":"f1025-F5G645FT03"
    }
  ],
  "extras":{
    "terminos":"Términos de facturación",
    "notas":"Notas adicionales de la factura",
    "nombreContacto":"Mario Borges"
  },
  "descuentoAdicional": 10
}

EJEMPLO #4

Usando CI y COMPLEMENTO
Descuento por producto y adicional (montoDescuento, descuentoAdicional) respectivamente
Código de unidad usado 57 (productos)

{
  "numeroFactura": 1,
  "codigoTipoDocumentoIdentidad": 1,
  "complemento": "A1",
  "usuario": "Jorge",
  "montoTotal": 140,
  "montoTotalSujetoIva": 140,
  "emailCliente": "Jorge.ramos@example.com",
  "telefonoCliente": null,
  "codigoCliente": "cod-234234",
  "numeroDocumento": "2345345",
  "nombreRazonSocial": "Juan Perez",
  "detalles": [
    {
      "subTotal": 150,
      "montoDescuento": 18,
      "unidadMedida": 57,
      "codigoProducto": "HAM-0923",
      "codigoActividadSin": "610000",
      "codigoProductoSin": 99100,
      "cantidad": 8,
      "precioUnitario": 21,
      "descripcion": "Hamburguesa doble queso"
    }
  ],
  "extras":{
    "terminos":"Términos de facturación",
    "notas":"Notas adicionales de la factura",
    "nombreContacto":"Mario Borges",
    "facturaTicket":"f1025-F5G645FT04"
  },
  "descuentoAdicional": 10
}

EJEMPLO #5

Usando CI y COMPLEMENTO
Sin descuentos
Código de unidad usado 58 (servicios)

{
  "numeroFactura": 1,
  "codigoTipoDocumentoIdentidad": 1,
  "complemento": "A1",
  "usuario": "Jorge",
  "montoTotal": 20,
  "montoTotalSujetoIva": 20,
  "emailCliente": "Jorge.ramos@example.com",
  "telefonoCliente": null,
  "codigoCliente": "cod-234234",
  "numeroDocumento": "2345345",
  "nombreRazonSocial": "Juan Perez",
  "detalles": [
    {
      "subTotal": 20,
      "montoDescuento": null,
      "unidadMedida": 58,
      "codigoProducto": "SER-213432",
      "codigoActividadSin": "610000",
      "codigoProductoSin": 99100,
      "cantidad": 1,
      "precioUnitario": 20,
      "descripcion": "Servicio de entrega"
    }
  ],
  "extras":{
    "terminos":"Términos de facturación",
    "notas":"Notas adicionales de la factura",
    "nombreContacto":"Mario Borges",
    "facturaTicket":"f1025-F5G645FT05"
  },
  "descuentoAdicional": null
}

1. Autenticación (Obtener Token)​

2. Validación de NIT​

3. Creación de un Punto de Venta​

4. Emisión de Factura de Compra-Venta​

Ejemplo de emisión de facturas en diferentes escenarios​

1. Autenticación (Obtener Token)

2. Validación de NIT

3. Creación de un Punto de Venta

4. Emisión de Factura de Compra-Venta

Ejemplo de emisión de facturas en diferentes escenarios