UpConta API

# Comprobantes

Consideraciones:

  • Los comprobantes electrónicos van a tomar el ambiente de prubas o producción del SRI que esté configurado dentro de UpConta, y esta configuración afecta tanto a la emisión como a la visualización de comprobantes.
  • Cuando el comprobante ha sido emitido se envía un correo electrónico al cliente y a la empresa, en el cual se adjunta el PDF y el XML del comprobante autorizada.

El proceso de emisión de comprobantes electrónicos cuentan con tres sencillos pasos:

  1. Se debe escoger el id del establecimiento y el punto de emisión para emitir el comprobante. Ejemplo: 001-002
  2. Se da forma al cuerpo del comprobante y se envia al SRI para su emisión.
  3. Se comprueba que el comprobante haya sido emitido.

# Recursos

# Información tributaria

interface infoTributaria: {
  /**
   *  Establecimiento
   */
  estab: string;
  /**
   *  Punto de emisión
   */
  ptoEmi: string;
}

# Tabla de información adicional

interface InfoAdicional {
  nombre: string;
  valor: string;
}

# Estado de comprobantes

El comprobante electrónico cuenta con los siguientes estados:

  • issued: El comprobante ha sido autorizada.
  • sent: El comprobante ha sido enviada al SRI y esta pendiente de autorización.
  • failed: El comprobante contiene errores y no a sido autorizada por el SRI. Es posible editar El comprobante para solventar los errores.
  • canceled: El comprobante ha sido anulada en el sistema.
  • draft: El comprobante esta en borrador.
  • offline: El comprobante esta en modo offline.

# Modo offline

  • Si el SRI esta fuera de servicio el comprobante se quedará en modo offline de tipo recepcion o autorizacion
    • recepcion cuando el servicio de recepción de comprobantes electrónicos del SRI no está disponible
    • autorizacion cuando el servicio de autorización de comprobantes electrónicos del SRI no está disponible
  • Todos los comprobantes que tengan este estado se intentaran emitir automáticamente por UpConta después de un periodo de tiempo.

# Opciones de comprobantes

Todos los comprobantes comparten las mismas opciones.

GET https://api-test.upconta.com/v3/administrative/invoices/get-options

# Ejemplo de respuesta
{
  "Impuestos": [
    {
      "id": "2",
      "description": "IVA"
    },
    {
      "id": "3",
      "description": "ICE"
    },
    {
      "id": "5",
      "description": "IRBPNR"
    }
  ],
  "FormasDePago": [
    {
      "id": "01",
      "description": "SIN UTILIZACION DEL SISTEMA FINANCIERO"
    },
    {
      "id": "15",
      "description": "COMPENSACIÓN DE DEUDAS"
    },
    {
      "id": "16",
      "description": "TARJETA DE DÉBITO"
    },
    {
      "id": "17",
      "description": "DINERO ELECTRÓNICO"
    },
    {
      "id": "18",
      "description": "TARJETA PREPAGO"
    },
    {
      "id": "19",
      "description": "TARJETA DE CRÉDITO"
    },
    {
      "id": "20",
      "description": "OTROS CON UTILIZACION DEL SISTEMA FINANCIERO"
    },
    {
      "id": "21",
      "description": "ENDOSO DE TÍTULOS 21"
    }
  ],
  "TiposDePersona": [
    {
      "id": "01",
      "description": "Persona natural"
    },
    {
      "id": "02",
      "description": "Sociedad"
    }
  ],
  "GuardadoDefecto": [
    {
      "id": "emitir",
      "description": "Emitir comprobante"
    },
    {
      "id": "borrador",
      "description": "Guardar como borrador"
    },
    {
      "id": "emision-lote",
      "description": "Guardar para emisión por lote"
    }
  ],
  "PorcentajesDeIVA": [
    {
      "id": "0",
      "description": "0%",
      "value": 0
    },
    {
      "id": "2",
      "description": "12%",
      "value": 0.12
    },
    {
      "id": "4",
      "description": "15%",
      "value": 0.15
    },
    {
      "id": "5",
      "description": "5%",
      "value": 0.05
    },
    {
      "id": "6",
      "description": "No objeto de impuesto",
      "value": 0
    },
    {
      "id": "7",
      "description": "Excento de IVA",
      "value": 0
    },
    {
      "id": "8",
      "description": "8%",
      "value": 0.08
    },
    {
      "id": "10",
      "description": "13%",
      "value": 0.13
    }
  ],
  "TiposDeComprobante": [
    {
      "id": "01",
      "description": "Factura"
    },
    {
      "id": "02",
      "description": "Nota de venta"
    },
    {
      "id": "03",
      "description": "Liquidación de compra"
    },
    {
      "id": "04",
      "description": "Nota de Crédito"
    },
    {
      "id": "05",
      "description": "Nota de Débito"
    },
    {
      "id": "06",
      "description": "Guía de Remisión"
    },
    {
      "id": "07",
      "description": "Comprobante de Retención"
    },
    {
      "id": "08",
      "description": "Liquidacion de Compra"
    },
    {
      "id": "11",
      "description": "Ticket de Avión"
    }
  ],
  "PorcentajesDeIRBPNR": [
    {
      "id": "5001",
      "description": "Botellas plásticas no retornables",
      "value": 0.02
    }
  ],
  "TiposDeIdentificacion": [
    {
      "id": "04",
      "description": "RUC"
    },
    {
      "id": "05",
      "description": "Cédula"
    },
    {
      "id": "06",
      "description": "Pasaporte"
    },
    {
      "id": "08",
      "description": "Identificación del exterior"
    },
    {
      "id": "09",
      "description": "Placa"
    }
  ]
}

# Facturación electrónica

# Recursos

# Tabla de pagos

interface Pago {
  formaPago: string;
  total: number;
}

Consideraciones:

  • formaPago es el id de FormasDePago. Revisar opciones
  • Pueden existir varios pagos, la condición es que la suma de sus totales de el total de la factura.

# Tabla de detalles

interface Detalle {
  /**
   * El ID del producto en UpConta.
   */
  product: string;
  /**
   * El ID del stock generado al registrar la factura.
   */
  stock?: string;
  /**
   * Cuando se crea la factura este campo no es necesario, ya que se llena con
   * la información del producto guardada en la base de datos.
   */
  codigoPrincipal: string;
  /**
   * Si no se proporciona toma la descripción del producto guardada en la base
   * de datos.
   */
  descripcion: string;
  /**
   * Valor por defecto `1`
   */
  cantidad: number;
  /**
   * Si no se proporciona toma el precio del producto guardada en la base de
   * datos.
   */
  precioUnitario: number;
  /**
   * Debe ser un valor menor al precio total sin impuestos.
   */
  descuentoInicial?: number;
  /**
   * El valor del descuento para la base imponible. Este campo es manejado por
   * UpConta, si se requiere aplicar descuento se debe utilizar el
   * `descuentoInicial`.
   */
  descuento?: number;
  /**
   * `precioUnitario * cantidad - descuentoInicial`. Este campo es calculado por
   * el UpConta.
   */
  precioTotalSinImpuesto: number;
  /**
   * Este campo es calculado por UpConta.
   */
  impuestos: Impuesto[];
}

Consideraciones

  • Los productos creados previamente pueden o no tener el precio ya incluido pero este puede sustituirse libremente en detalle.
  • El descuentoInicial es un valor menor al la multiplicación de precioUnitario * cantidad.
  • Si no se proporciona un cliente la factura se la emite a un consumidor final.
  • Un consumidor final solo puede emitir facturas menores a $50.
  • El campo infoFactura es opcional y dentro de este se encuenta formaPago.
  • Si no se proporciona el campo infoFactura se paga automáticamente el total con una forma de pago por defecto de 01 correspondiente a SIN UTILIZACION DEL SISTEMA FINANCIERO.
  • Es posible que este proceso demore unos cuantos segundos. Esto se debe a que el servidor del SRI tarda un tiempo en procesar la información.

# Obtener facturas

GET https://api-test.upconta.com/v3/administrative/invoices

# Ejemplo de respuesta

{
  "page": 1,
  "total": 237,
  "data": [
    {
      "_id": "66228b09d436ba5f5bab0c30",
      "status": "draft",
      "infoTributaria": {
        "ambiente": "1",
        "estab": "001",
        "ptoEmi": "002",
        "tipoEmision": "1",
        "codDoc": "01",
        "esRegimenGeneral": false,
        "razonSocial": "desarrollo",
        "ruc": "1725843695001",
        "dirMatriz": "TORRE BOREAL",
        "secuencial": "BORRADOR-47"
      },
      "_movements": [
        {
          "type": "created",
          "user": "608adf6a375dfd83381ba163",
          "nota": "Creado por desarrollador",
          "date": "2024-04-19T15:17:29.346Z"
        },
        {
          "type": "draft",
          "user": "608adf6a375dfd83381ba163",
          "nota": "Guardado como borrador por desarrollador",
          "date": "2024-04-19T15:17:29.363Z"
        }
      ],
      "client": "662171740dbc2d448f653183",
      "charged": false,
      "waybills": [],
      "generateStock": "emision",
      "infoFactura": {
        "obligadoContabilidad": "NO",
        "totalDescuento": 2,
        "propina": 0,
        "moneda": "DOLAR",
        "totalConImpuestos": [
          {
            "codigo": "2",
            "codigoPorcentaje": "4",
            "baseImponible": 18,
            "valor": 2.7
          }
        ],
        "pagos": [
          {
            "formaPago": "01",
            "total": 20.7
          }
        ],
        "tipoIdentificacionComprador": "05",
        "razonSocialComprador": "Carlos",
        "identificacionComprador": "1752478450",
        "direccionComprador": "",
        "totalSinImpuestos": 18,
        "importeTotal": 20.7,
        "dirEstablecimiento": "TORRE BOREAL"
      },
      "detalles": [
        {
          "product": "662253f04939e1ab31a7477e",
          "cantidad": 2,
          "precioUnitario": 10,
          "descuentoInicial": 2,
          "descuento": 2,
          "_id": "66228b09d436ba5f5bab0c31",
          "impuestos": [
            {
              "codigo": "2",
              "codigoPorcentaje": "4",
              "tarifa": 15,
              "baseImponible": 18,
              "valor": 2.7
            }
          ],
          "codigoPrincipal": "COMP002",
          "descripcion": "Computadoras",
          "precioTotalSinImpuesto": 18
        }
      ],
      "notasCredito": [],
      "notasDebito": [],
      "issueDate": "2024-04-19T15:17:29.346Z",
      "infoAdicional": [],
      "attachments": [],
      "reembolsos": [],
      "porcentajeDescuentoGlobal": 0,
      "__v": 0
    }
  ]
}

Donde:

  • client: El id del cliente a quien se va a emitir la factura. Si no se proporciona se emite a un consumidor final.
  • infoTributaria: Es la información que se envia al SRI para emitir el comprobante. Revisar modelo información tributaria.
  • status: El estado de la factura. issued si la factura a sido autorizada. sent si la factura fue enviada pero aun no se ha autorizado (revisar ). canceled si la factura se ha anulado.draft si la factura está como borrador. failed si se envio al SRI pero este no ha autorizado su emisión.
  • issueDate: La fecha de emisión de la factura.
  • authorizationDate: La fecha en que la factura fue autorizada.

# Obtener factura

GET https://api-test.upconta.com/v3/administrative/invoices/:id

  • Para obtener todos los campos del comprabante es necesario $getAllFields

GET https://api-test.upconta.com/v3/administrative/invoices/:id?$getAllFields=true

# Ejemplo de respuesta

{
  "_id": "66228b09d436ba5f5bab0c30",
  "status": "draft",
  "infoTributaria": {
    "ambiente": "1",
    "estab": "001",
    "ptoEmi": "002",
    "tipoEmision": "1",
    "codDoc": "01",
    "esRegimenGeneral": false,
    "razonSocial": "desarrollo",
    "ruc": "1725843695001",
    "dirMatriz": "TORRE BOREAL",
    "secuencial": "BORRADOR-47"
  },
  "_movements": [
    {
      "type": "created",
      "user": "608adf6a375dfd83381ba163",
      "nota": "Creado por desarrollador",
      "date": "2024-04-19T15:17:29.346Z"
    },
    {
      "type": "draft",
      "user": "608adf6a375dfd83381ba163",
      "nota": "Guardado como borrador por desarrollador",
      "date": "2024-04-19T15:17:29.363Z"
    }
  ],
  "client": "662171740dbc2d448f653183",
  "charged": false,
  "waybills": [],
  "generateStock": "emision",
  "infoFactura": {
    "obligadoContabilidad": "NO",
    "totalDescuento": 2,
    "propina": 0,
    "moneda": "DOLAR",
    "totalConImpuestos": [
      {
        "codigo": "2",
        "codigoPorcentaje": "4",
        "baseImponible": 18,
        "valor": 2.7
      }
    ],
    "pagos": [
      {
        "formaPago": "01",
        "total": 20.7
      }
    ],
    "tipoIdentificacionComprador": "05",
    "razonSocialComprador": "Carlos",
    "identificacionComprador": "1752478450",
    "direccionComprador": "",
    "totalSinImpuestos": 18,
    "importeTotal": 20.7,
    "dirEstablecimiento": "TORRE BOREAL"
  },
  "detalles": [
    {
      "product": "662253f04939e1ab31a7477e",
      "cantidad": 2,
      "precioUnitario": 10,
      "descuentoInicial": 2,
      "descuento": 2,
      "_id": "66228b09d436ba5f5bab0c31",
      "impuestos": [
        {
          "codigo": "2",
          "codigoPorcentaje": "4",
          "tarifa": 15,
          "baseImponible": 18,
          "valor": 2.7
        }
      ],
      "codigoPrincipal": "COMP002",
      "descripcion": "Computadoras",
      "precioTotalSinImpuesto": 18
    }
  ],
  "notasCredito": [],
  "notasDebito": [],
  "issueDate": "2024-04-19T15:17:29.346Z",
  "infoAdicional": [],
  "attachments": [],
  "reembolsos": [],
  "porcentajeDescuentoGlobal": 0,
  "__v": 0
}

# Crear factura

POST https://api-test.upconta.com/v3/administrative/invoices

# Ejemplo de petición

{
  "client": "662171740dbc2d448f653183",
  "infoTributaria": {
    "estab": "001",
    "ptoEmi": "002"
  },
  "detalles": [
    {
      "product": "662253f04939e1ab31a7477e",
      "cantidad": 2,
      "precioUnitario": 10,
      "descuentoInicial": 2
    }
  ]
}

# Ejemplo de respuesta

{
  "_id": "66228844d436ba5f5bab0478",
  "status": "sent",
  "infoTributaria": {
    "ambiente": "1",
    "estab": "001",
    "ptoEmi": "002",
    "tipoEmision": "1",
    "codDoc": "01",
    "esRegimenGeneral": false,
    "razonSocial": "desarrollo",
    "ruc": "1725843695001",
    "dirMatriz": "TORRE BOREAL",
    "secuencial": "000004110",
    "claveAcceso": "1904202401725843695100110010020000041103854243814"
  },
  "_movements": [
    {
      "type": "created",
      "user": "608adf6a375dfd83381ba163",
      "nota": "Creado por desarrollador",
      "date": "2024-04-19T15:05:40.366Z"
    },
    {
      "type": "sent",
      "user": "608adf6a375dfd83381ba163",
      "nota": "Enviada al SRI por desarrollador",
      "date": "2024-04-19T15:05:42.795Z"
    }
  ],
  "client": "662171740dbc2d448f653183",
  "charged": false,
  "generateStock": "emision",
  "infoFactura": {
    "obligadoContabilidad": "NO",
    "totalDescuento": 2,
    "propina": 0,
    "moneda": "DOLAR",
    "totalConImpuestos": [
      {
        "codigo": "2",
        "codigoPorcentaje": "4",
        "baseImponible": 18,
        "valor": 2.7
      }
    ],
    "pagos": [
      {
        "formaPago": "01",
        "total": 20.7
      }
    ],
    "tipoIdentificacionComprador": "05",
    "razonSocialComprador": "Carlos",
    "identificacionComprador": "1752478450",
    "direccionComprador": "",
    "totalSinImpuestos": 18,
    "importeTotal": 20.7,
    "dirEstablecimiento": "TORRE BOREAL"
  },
  "detalles": [
    {
      "product": "662253f04939e1ab31a7477e",
      "cantidad": 2,
      "precioUnitario": 10,
      "descuentoInicial": 2,
      "descuento": 2,
      "_id": "66228844d436ba5f5bab0479",
      "impuestos": [
        {
          "codigo": "2",
          "codigoPorcentaje": "4",
          "tarifa": 15,
          "baseImponible": 18,
          "valor": 2.7
        }
      ],
      "codigoPrincipal": "COMP002",
      "descripcion": "Computadoras",
      "precioTotalSinImpuesto": 18,
      "stock": "66228844d436ba5f5bab05ed"
    }
  ],
  "notasCredito": [],
  "notasDebito": [],
  "issueDate": "2024-04-19T15:05:40.367Z",
  "infoAdicional": [],
  "attachments": [],
  "reembolsos": [],
  "porcentajeDescuentoGlobal": 0,
  "__v": 1
}

# Guardar factura como borrador

POST https://api-test.upconta.com/v3/administrative/invoices?guardarComoBorrador=true

# Ejemplo de respuesta

{
  "_id": "66228b09d436ba5f5bab0c30",
  "status": "draft",
  "infoTributaria": {
    "ambiente": "1",
    "estab": "001",
    "ptoEmi": "002",
    "tipoEmision": "1",
    "codDoc": "01",
    "esRegimenGeneral": false,
    "razonSocial": "desarrollo",
    "ruc": "1725843695001",
    "dirMatriz": "TORRE BOREAL",
    "secuencial": "BORRADOR-47"
  },
  "_movements": [
    {
      "type": "created",
      "user": "608adf6a375dfd83381ba163",
      "nota": "Creado por desarrollador",
      "date": "2024-04-19T15:17:29.346Z"
    },
    {
      "type": "draft",
      "user": "608adf6a375dfd83381ba163",
      "nota": "Guardado como borrador por desarrollador",
      "date": "2024-04-19T15:17:29.363Z"
    }
  ],
  "client": "662171740dbc2d448f653183",
  "charged": false,
  "waybills": [],
  "generateStock": "emision",
  "infoFactura": {
    "obligadoContabilidad": "NO",
    "totalDescuento": 2,
    "propina": 0,
    "moneda": "DOLAR",
    "totalConImpuestos": [
      {
        "codigo": "2",
        "codigoPorcentaje": "4",
        "baseImponible": 18,
        "valor": 2.7
      }
    ],
    "pagos": [
      {
        "formaPago": "01",
        "total": 20.7
      }
    ],
    "tipoIdentificacionComprador": "05",
    "razonSocialComprador": "Carlos",
    "identificacionComprador": "1752478450",
    "direccionComprador": "",
    "totalSinImpuestos": 18,
    "importeTotal": 20.7,
    "dirEstablecimiento": "TORRE BOREAL"
  },
  "detalles": [
    {
      "product": "662253f04939e1ab31a7477e",
      "cantidad": 2,
      "precioUnitario": 10,
      "descuentoInicial": 2,
      "descuento": 2,
      "_id": "66228b09d436ba5f5bab0c31",
      "impuestos": [
        {
          "codigo": "2",
          "codigoPorcentaje": "4",
          "tarifa": 15,
          "baseImponible": 18,
          "valor": 2.7
        }
      ],
      "codigoPrincipal": "COMP002",
      "descripcion": "Computadoras",
      "precioTotalSinImpuesto": 18
    }
  ],
  "notasCredito": [],
  "notasDebito": [],
  "issueDate": "2024-04-19T15:17:29.346Z",
  "infoAdicional": [],
  "attachments": [],
  "reembolsos": [],
  "porcentajeDescuentoGlobal": 0,
  "__v": 0
}

# Enviar factura por correo

Se puede volver a enviar el PDF y XML de la factura al cliente. Si es a consumidor final no se envía el correo.

GET https://api-test.upconta.com/v3/administrative/invoices/:id/send-email

# Ejemplo de respuesta

{
  "message": "success"
}

# Obtener factura en PDF

GET https://api-test.upconta.com/v3/administrative/invoices/:id/pdf

# Eliminar factura

Solo se pueden eliminar comprobantes fallidos.

DELETE https://api-test.upconta.com/v3/administrative/invoices/:id

# Ejemplo de respuesta

{
  "message": "success"
}

# Anular factura

Solo se pueden anular las facturas que hayan sido emitidas.

DELETE https://api-test.upconta.com/v3/administrative/invoices/:id/cancel

# Ejemplo de respuesta

{
  "message": "anulado"
}

←