Saltearse al contenido
Factus API

SS Recaudo

Esta sección describe los campos que podría contener la factura electrónica del sector salud con tipo de operación SS-Recaudo. Aplica para el recaudo de cuotas moderadoras o copagos, con dos variantes según el destinatario del ingreso.

Método: POST

Endpoint 

https://api-sandbox.factus.com.co/v2/bills/validate

Encabezados de la Solicitud

Para realizar la solicitud es necesario incluir los siguientes encabezados:

Content-Type : application/json
Indica que los datos se envían en formato JSON.
Authorization Bearer token_de_acceso
Token de autenticación necesario para acceder al recurso. Ver Cómo generar token
Accept : application/json
Indica que la respuesta debe estar en formato JSON.
Nota: Reemplaza token_de_acceso con el token proporcionado tras autenticarte.

Ver aquí la descripción de los campos.

Parámetros Factura SS Recaudo
reference_code string
Código único que sirve para identificar cada factura de manera unívoca en el sistema y garantizar que no haya duplicados. Esto nos ayuda a prevenir que se genere más de una factura con la misma información.
document string default:01 opcional
Código del tipo de documento. Tipos de documentos disponibles.
numbering_range_id integer opcional
ID del rango de numeración. Es obligatorio solo si tienes múltiples rangos activos. Si se omite, el sistema utilizará el único rango disponible por defecto. Rangos de numeración.
operation_type string default:10 opcional
Código del tipo de operación. Si el tipo de operación no se agrega, por defecto el API agrega el código 10 (estándar). Tipos de operación disponibles.
send_email boolean default:true opcional
Indica si el sistema debe enviar el correo electrónico al cliente. Útil cuando el envío del correo se gestiona de forma externa o personalizada por el integrador. Por defecto, este campo tiene un valor de true, lo que implica que el correo electrónico será enviado al cliente. Si se establece en false, el correo no será enviado.
observation string opcional
Agrega una observación a la factura. No debe tener más de 250 caracteres.
prepayment_details array opcional
Este es un array de objetos para los detalles de anticipos. Se debe enviar un objeto por cada anticipo realizado.
prepayment_details.*.reference_code string
Código de referencia del anticipo.
prepayment_details.*.received_date string
Fecha en que se recibió el anticipo en formato YYYY-MM-DD.
prepayment_details.*.amount string
Monto del anticipo.
prepayment_details.*.note string opcional
Nota adicional sobre el anticipo. No debe exceder los 5000 caracteres.
payment_details array
Este es un array de objetos para los medios de pago. Se debe enviar un objeto por cada medio de pago utilizado para pagar la factura.
payment_details.*.payment_form string
Código de la forma de pago. Formas de pago disponibles
payment_details.*.payment_method_code string
Código del método de pago. Métodos de pago disponibles.
payment_details.*.reference_code string opcional
Código de referencia del pago.
payment_details.*.amount string
Monto pagado por ese medio y método de pago.
payment_details.*.due_date string opcional
Fecha de vencimiento de la factura en formato YYYY-MM-DD. Requerido solo cuando la forma de pago (payment_form) contiene el valor de 2 (pago a crédito).
cash_rounding_amount string opcional
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.
beneficiary object opcional
Objeto con los datos del beneficiario del servicio de salud (paciente). Obligatorio para SS-Recaudo. Si se envía, los campos marcados como requeridos son obligatorios.
beneficiary.identification_document_code string
Código del tipo de documento del paciente. Utiliza los códigos propios del sector salud. Documentos de identificación para sector salud.
beneficiary.identification_number string opcional
Número de identificación del paciente. Obligatorio salvo que identification_document_code sea SI, MS o AS.
beneficiary.names string opcional
Nombres del paciente.
beneficiary.surnames string opcional
Apellidos del paciente.
health object opcional
Objeto con los datos del sector salud. Obligatorio para SS-CUFE, SS-Reporte y SS-SinAporte. Si se envía, todos sus campos internos son obligatorios.
health.provider_code string
Código del prestador de servicios de salud (IPS/EPS).
health.payment_method_code string
Código del método de pago en salud. Métodos de pago en salud disponibles.
health.coverage_code string
Código del plan de cobertura en salud. Planes de cobertura disponibles.
health.contract_number string
Número del contrato con la entidad pagadora.
health.policy_number string opcional
Número de póliza. Requerido cuando el plan de cobertura corresponde a una póliza (SOAT, ARL, etc.).
prepayment_details.*.concept_code string opcional
Código del concepto del anticipo o recaudo previo. Requerido para SS-CUFE, SS-Reporte y SS-SinAporte.
establishment object opcional
Este es un objeto que contendrá la información sobre el establecimiento. Úsalo cuando manejes más de un establecimiento y necesites que los datos correspondientes se reflejen en la factura. Si envías el campo establishment los campos internos son obligatorios.
establishment.name string
Nombre del establecimiento.
establishment.address string
Dirección del establecimiento.
establishment.phone_number string
Número telefónico del establecimiento.
establishment.email string
Correo electrónico del establecimiento.
establishment.municipality_code string
Código que corresponda al municipio donde se encuentra el establecimiento. Municipios disponibles.
billing_period object opcional
Este es un objeto que contendrá la información del periodo de facturación. Para utilizar en los servicios públicos, contratos de arrendamiento, matrículas en educación, etc. Si envías el campo billing_period los campos internos son obligatorios.
billing_period.start_date string
Fecha de inicio del periodo de facturación en formato YYYY-MM-DD.
billing_period.start_time string opcional
Hora de inicio del periodo de facturación en formato HH:mm:ss.
billing_period.end_date string
Fecha de fin del periodo de facturación en formato YYYY-MM-DD.
billing_period.end_time string opcional
Hora de fin del periodo de facturación en formato HH:mm:ss.
order_reference object opcional
Este es un objeto que contendrá la información que describe una orden de pedido. Si envías el campo order_reference los campos internos son obligatorios.
order_reference.reference_code string
Número del documento de la orden.
order_reference.issue_date string opcional
Fecha de emisión de la orden.
related_documents.* array opcional
Este es un array de objetos (documentos), debe haber un objeto por cada documento. Obligatorio cuando el campo document contenga el valor 03. Si envías el campo related_documents los campos internos son obligatorios.
related_documents.*.code string
Identificador del tipo de documento de referencia (corresponde a una codificación propia de la empresa).
related_documents.*.issue_date string
Fecha de emisión del documento referenciado en formato YYYY-MM-DD.
related_documents.*.number string
Prefijo y número del documento referenciado.
customer object
Este es un objeto que contendrá la información del cliente de la factura.
customer.identification_document_code string
Código que corresponda al tipo de identificación. Tipos de documentos disponibles.
customer.identification string
Número de identificación del cliente. Si el numero de identificación corresponde a un NIT no se debe enviar el dígito de verificación ni el guion que lo separa, el dígito de verificación tiene un campo exclusivo para él, aquí se debe enviar únicamente el numero de identificación.
customer.dv string opcional
Dígito de verificación correspondiente al NIT del cliente.
El dígito de verificación se envía únicamente para clientes que se identifican con NIT.
Si el cliente se identifica con NIT y no se envía el dígito de verificación, el API lo calculará automáticamente.
customer.legal_organization_code string
Código que corresponda al tipo de organización. Tipos de organizaciones disponibles.
customer.tribute_code string default:ZZ opcional
Código del tributo. Tipos de tributos disponibles.
customer.company string opcional
Razón social. Es obligatorio cuando el campo customer.legal_organization_code es 1 (persona jurídica).
customer.trade_name string opcional
Nombre comercial.
customer.names string opcional
Nombre del cliente. Es obligatorio cuando el campo customer.legal_organization_code es 2 (persona natural).
customer.address string opcional
Dirección del cliente.
customer.email string opcional
Correo electrónico del cliente.
customer.phone string opcional
Número de teléfono del cliente.
customer.municipality_code string opcional
Código que corresponda al municipio donde vive el cliente. Se debe enviar el código del municipio únicamente si el municipio es de Colombia; si es extranjero, el valor del campo no aplica. Municipios disponibles.
items array
Este es un array de objetos (items) que corresponde a los productos o servicios de la factura, se debe enviar un objeto por cada producto o servicio.
items.*.scheme_id string
Este campo es requerido si el campo operation_type contiene el valor de 11 (mandatos) o 12 (transporte) o SS-Recaudo (Salud). Agregue el valor de 0 cuando sea ingreso propio y 1 para ingresos recibidos para terceros.
items.*.note string opcional
Añade información adicional del producto o servicio.
items.*.collection_concept_code string opcional
Código del concepto de recaudo. Requerido para SS-Recaudo. Valores: COP (Copago), CUO (Cuota Moderadora), PAC (Pagos compartidos en planes voluntarios de salud).
items.*.code_reference string
Código de referencia del producto o servicio.
created_time string opcional
Fecha y hora de creación del documento soporte en formato `HH:mm:ss`.
items.*.name string
Nombre del producto o servicio.
items.*.quantity string
Cantidad del producto o servicio (máximo dos decimales).
items.*.discount_rate string
Porcentaje del descuento del producto o servicio (máximo dos decimales).
items.*.price string
Precio por unidad del producto o servicio sin impuestos incluidos ni descuentos, valor neto (máximo dos decimales).
items.*.unit_measure_code string
Código que corresponda a la unidad de medida del item. Unidades de medida disponibles
items.*.standard_code string
Código que corresponde al estándar que se adopta para los productos o servicios. Códigos de estándar disponibles.
items.*.taxes array
Este es un array de objetos para los impuestos.
items.*.taxes.*.code string
Código del impuesto aplicado al producto o servicio. Códigos de impuestos disponibles.
items.*.taxes.*.rate string
Porcentaje del impuesto aplicado al producto o servicio (máximo dos decimales).
items.*.withholding_taxes array opcional
Este es un array de objetos (autorretenciones) para informar las retenciones que se aplican al producto o servicio. No son retenciones que otra persona o empresa te hace a ti, sino retenciones que tú mismo te aplicas como contribuyente. Por cada retención que te apliques a ti mismo, debes enviar un objeto.
items.*.withholding_taxes.*.code string
Código de la retención aplicada al producto o servicio. Códigos retenciones disponibles.
items.*.withholding_taxes.*.rate string
Porcentaje de la retención aplicada al producto o servicio (máximo dos decimales).
items.*.mandate object opcional
Este es un objeto que contendrá la información del mandante. Este campo es requerido si items.*.scheme_id = 1 (ingresos recibidos para terceros) y operation_type = 11 (mandatos) o operation_type = SS-Recaudo (Salud).
items.*.mandate.identification_document_code string
Código que corresponda al tipo de identificación del mandante. Tipos de documentos disponibles
items.*.mandate.identification string
Número de identificación del mandante.
allowance_charges array opcional
Este es un array de objetos que corresponden a los descuentos o recargos que se aplican a la factura; se debe enviar un objeto por cada descuento o recargo.
allowance_charges.*.concept_type string
Código del tipo de descuento o recargo. Para saber el código que corresponde, consulte la tabla. Códigos de conceptos disponibles.
allowance_charges.*.is_surcharge boolean
Indica si es un descuento o un recargo. El valor true corresponde a un recargo y false a un descuento.
allowance_charges.*.reason string
Razón por la cual se está haciendo el descuento o recargo.
allowance_charges.*.base_amount string
Base sobre la cual se calcula el descuento o recargo (máximo dos decimales).
allowance_charges.*.amount string
Valor del descuento o recargo aplicado (máximo dos decimales).

Ejemplo de Solicitud

Sección titulada «Ejemplo de Solicitud»
{
  "reference_code": "FACT-2026-0125",
  "document": "01",
  "numbering_range_id": 4,
  "operation_type": "SS-Recaudo",
  "send_email": false,
  "payment_details": [
    {
      "payment_form": 1,
      "payment_method_code": "10",
      "amount": "10000"
    }
  ],
  "cash_rounding_amount": "0.00",
  "beneficiary": {
    "identification_document_code": "CC",
    "identification_number": "12345678",
    "names": "",
    "surnames": ""
  },
  "customer": {
    "identification_document_code": "13",
    "identification": "123456789",
    "names": "Alan Turing",
    "address": "calle 1 # 1-1",
    "email": "alan.company@email.com",
    "phone": "1234567890",
    "legal_organization_code": "2",
    "tribute_code": "ZZ",
    "municipality_code": "68679"
  },
  "items": [
    {
      "scheme_id": 0,
      "collection_concept_code": "PAC",
      "code_reference": "PROD-000A",
      "name": "Servicio de salud",
      "quantity": "1.00",
      "discount_rate": "0.00",
      "price": "10000.00",
      "unit_measure_code": "94",
      "standard_code": "999",
      "taxes": [
        {
          "is_excluded": true
        }
      ]
    }
  ]
}