Cambios de V1 a V2

Este documento proporciona una guía detallada para los desarrolladores que están migrando de la versión 1 a la versión 2 o estén integrando la versión 2 de nuestra API Factus. A continuación, se destacan los cambios clave tanto en campos como en endpoints y nuevas tablas de referencia.

Métodos de pago:

payment_details Hemos actualizado el campo de métodos de pago, pasamos de manejar un id indicando un solo metodo de pago payment_method_code, a manejar un array de objetos con los detalles de cada método de pago payment_details, permitiendo así múltiples métodos de pago en una sola factura. Ver todos los métodos de pago disponibles: Métodos de pago disponibles.

{
    "payment_method_code" : "10",
    "payment_details": [
        {
        "payment_form": "2",
        "payment_method_code": "10",
        "reference_code": "pago-001",
        "amount": "50000",
        "due_date": "2026-03-25"
        }
  ]
}

Redondeo de valores para medio de pago:

cash_rounding_amount Agregamos un nuevo campo para el ajuste opcional que reconcilia la diferencia entre la suma de los montos en ⁠payment_details y el total de la factura, causada por las limitaciones de denominación de la moneda local. Acepta valores negativos (redondeo hacia abajo) o positivos (redondeo hacia arriba). El valor máximo permitido es ±500.00.

{
    "cash_rounding_amount" : "0.00",
}

Anticipos:

prepayment_details Agregamos este nuevo campo para manejar los anticipos de manera estructurada, permitiendo múltiples anticipos en una sola factura.

{
    "prepayment_details": [
        {
        "prepayment_form": "2",
        "prepayment_method_code": "10",
        "reference_code": "anticipo-001",
        "amount": "50000",
        "due_date": "2026-03-25"
        }
  ]
}

Clientes:

customer.identification_document_code En el objeto de clientes hemos modificado el nombre del campo de tipo de identificación, en la v1 se manejaba con el nombre identification_document_id y ahora en la v2 se maneja con el nombre identification_document_code, el valor se ha modificado de id por código, que representa el tipo de identificación del cliente. Puede ver los tipos de identificación en Tipos de documentos disponibles.

{
    "customer": {
        "identification_document_id": 3,
        "identification_document_code": "13",
    }
}

customer.legal_organization_code En el objeto de clientes hemos modificado el nombre del campo de tipo de organización del cliente, en la v1 se manejaba con el nombre legal_organization_id y ahora en la v2 se maneja con el nombre legal_organization_code, el valor se ha modificado de id por código, que representa el tipo de organización del cliente. Puede ver los tipos de organización en Tipos de organizaciones disponibles.

{
    "customer": {
        "legal_organization_id": "01",
        "legal_organization_code": "1",
    }
}

customer.tribute_code En el objeto de clientes hemos modificado el nombre del campo de tipo de tributo para clientes, en la v1 se manejaba con el nombre tribute_id y ahora en la v2 se maneja con el nombre tribute_code. Puede ver los tipos de tributos en Tipos de tributos disponibles.

{
   "customer": {
       "tribute_id": 3,
       "tribute_code": "01",
   }
}

customer.municipality_code En el objeto de clientes hemos modificado el nombre del campo de código de municipio del cliente, pasamos de usar el nombre municipality_id a municipality_code, el valor se ha modificado de id por código, que representa el municipio del cliente.

Novedad Anteriormente en la v1 se consumía un endpoint para obtener el id del municipio, ahora en la v2 damos acceso al json con el listado completo de municipios para que el integrador pueda hacer la relación directamente entre el código del municipio y su nombre, sin necesidad de consumir un endpoint adicional. Municipios disponibles.

{
    "customer": {
        "municipality_id": "980",
        "municipality_code": "1",
    }
}

Productos (items):

Uno de los cambios más significativos en la v2, tenemos modificaciones en varios campos como lo son el precio, unidad de medida, standar code, impuestos y autoretenciones.

items.price En la v2 el campo de precio se maneja como un valor neto, es decir, sin impuestos incluidos. En la v1 se manejaba como un valor bruto con impuestos incluidos.

{
    "items": [
        {
            "price": 100000,// V2: precio neto sin impuestos incluidos
        }
    ]
}

items.unit_of_measure_code En el objeto de items hemos modificado el nombre del campo de unidad de medida, en la v1 se manejaba con el nombre unit_measure_id y ahora en la v2 se maneja con el nombre unit_measure_code.

Novedad Anteriormente en la v1 se consumía un endpoint para obtener el id de la unidad de medida, ahora en la v2 damos acceso al json con el listado completo de unidades de medida para que el integrador pueda hacer la relación directamente entre el código de la unidad de medida y su descripción, sin necesidad de consumir un endpoint adicional. Unidades de medida disponibles

{
    "items": [
        {
            "unit_measure_id": "01",
            "unit_measure_code": "1",
        }
    ]
}

items.standard_code En el objeto de items hemos modificado el nombre del campo de código estándar, en la v1 se manejaba con el nombre standard_id y ahora en la v2 se maneja con el nombre standard_code, puede ver los códigos estándar en Códigos de estándar disponibles.

{
    "items": [
        {
            "standard_id": "01",
            "standard_code": "999",
        }
    ]
}

items.taxes En el objeto de items hemos modificado el campo tax_rate, en la v1 se manejaba como un valor numérico representando el porcentaje del impuesto, ahora en la v2 se maneja como un array de objetos para el manejo de múltiples impuestos por item, cada objeto contiene el código del impuesto y su respectiva tarifa.

Novedad Anteriormente en la v1 se consumía un endpoint para obtener el id del tributo, ahora en la v2 damos acceso a una tabla con el listado completo de tributos para que el integrador pueda hacer la relación directamente entre el código del tributo y su descripción, sin necesidad de consumir un endpoint adicional. Puede ver los tipos de impuestos en Códigos de impuestos disponibles.

{
    "items": [
        {
            "tax_rate": 19,
            "taxes": [
                {
                    "tax_code": "01",
                    "tax_rate": 19
                }
            ]
        }
    ]
}

items.withholding_taxes En el objeto de items hemos modificado la forma de consumir las autoretenciones, en la v1 se manejaba consumiendo un endpoint para obtener el código correspondiente a la autoretención, ahora en la v2 damos acceso a una tabla con el listado completo de autoretenciones para que el integrador pueda hacer la relación directamente entre el código de la autoretención y su descripción, sin necesidad de consumir un endpoint adicional.

Novedad Puede ver los tipos de autoretenciones en Códigos de retenciones disponibles.