POST /factura — Create and Validate a New Invoice

This endpoint submits a new electronic sales invoice to the Factus API, which in turn forwards it to the DIAN (Colombia’s tax authority) for real-time validation. Before forwarding the request, the backend validates the request body via validate_body() — checking that all required fields are present and have the correct types. It also auto-generates the reference_code (a 10-character alphanumeric key) and stamps numbering_range_id: 8; you must not include those fields in your request.

Endpoint

POST /factura

Request Body

The body must be a JSON object with the following top-level fields:

string

required

A free-text note to attach to the invoice. Maximum 249 characters. Longer strings are rejected with a 400 validation error.

number

required

Numeric ID of the payment method from the Factus payment_method catalogue (e.g., 10 for Efectivo).

object

required

Object describing the invoice recipient.

Show customer fields

string

required

Company name. Pass an empty string "" for natural persons.

string

required

Trade name. Pass an empty string if not applicable.

string

required

Customer full name.

string

required

Customer postal address.

string

required

Customer email address.

string

required

Customer phone number.

number

required

ID of the customer’s tax tribute regime (e.g., 21 for No aplica).

number

required

ID of the customer’s municipality from the Factus municipality catalogue (e.g., 1041 for Fresno).

string

required

Customer identification number (cédula, NIT, etc.).

number

required

ID of the identification document type from the Factus catalogue (e.g., 3 for Cédula de ciudadanía).

number

required

ID of the legal organisation type (e.g., 2 for Persona Natural, 1 for Persona Jurídica).

number

Check digit. Required only for legal entities (juridical persons) that have a NIT with a check digit.

array

required

Array of one or more product or service line items. Each element is an object with the following fields:

Show item fields

string

required

Product or service name (e.g., "Laptop HP").

number

required

Quantity of units invoiced.

number

required

Unit price in Colombian pesos (COP).

number

required

Discount percentage to apply to this line (e.g., 11 for 11%). Use 0 for no discount.

string

required

Tax rate as a decimal string (e.g., "19.00", "5.00", "0.0").

number

required

ID of the unit of measure from the Factus catalogue (e.g., 70 for unidad).

number

required

ID of the standard product code from the Factus catalogue (e.g., 1 for Estándar de adopción del contribuyente).

number

required

ID of the tax tribute that applies to this item (e.g., 1 for IVA).

number

required

0 if the item is taxable; 1 if the item is tax-excluded.

array

required

Array of withholding tax entries for this line. Pass an empty array [] if none apply. Each entry has:

code (string) — withholding tax code (e.g., "06" for ReteRenta, "07" for ReteICA).
withholding_tax_rate (string) — rate as a decimal string (e.g., "7.00").

Do not include reference_code or numbering_range_id in your request body. The backend’s validate_body() function auto-generates reference_code as a 10-character random key and hard-codes numbering_range_id to 8 before forwarding to Factus. Any values you send for those fields will be overwritten.

Response

200 — Success

Returns the full created invoice detail (identical shape to GET /factura/:number — see that page for the complete field reference).

{
  "status": 200,
  "message": "OK",
  "data": {
    "company": { ... },
    "customer": { ... },
    "numbering_range": { ... },
    "billing_period": [],
    "bill": {
      "id": 9763,
      "number": "SETP990009126",
      "reference_code": "N4T4H1R2F5",
      "status": 1,
      "cufe": "e6f14a89...",
      "qr": "https://catalogo-vpfe-hab.dian.gov.co/...",
      "total": "1335000.00",
      ...
    },
    "items": [ ... ],
    "withholding_taxes": [ ... ]
  }
}

400 — Bad Request (Validation Failed)

Returned when validate_body() finds missing or incorrectly-typed fields. The conflict object details what went wrong:

{
  "status": 400,
  "messaje": "Hay un problema con el cuerpo de la solicitud",
  "conflict": {
    "ok": false,
    "message": "Hay errores",
    "missing_properties": ["items"],
    "require": [
      {
        "property": "observation",
        "type_require": "String, length <= 249",
        "type_received": "string, length = 300"
      }
    ]
  }
}

array

Names of required top-level fields that were absent from the request body.

array

Type mismatch errors. Each entry has property, type_require, and type_received.

409 — Conflict

Returned when the Factus API responds but with an unexpected status value (e.g., upstream validation failure).

{
  "status": 409,
  "message": "CONFLICT",
  "data": {}
}

500 — Internal Server Error

Two distinct shapes are possible: Shape A — upstream call failure (from request_fact internal catch):

{
  "status": 500,
  "error": "ERROR INTERNO",
  "data": {}
}

Optional extra fields: message (Axios error message), code (Axios error code), error_name (error class name). Shape B — controller-level exception:

{
  "status": 500,
  "messaje": "Hubo un error al intentar realizar la solicitud",
  "error": {}
}

The messaje key (with a j) in Shape B is a known typo in the backend source. Shape A uses error as a plain string ("ERROR INTERNO").

Example Request Body

{
  "observation": "tengo un error 409, aún no lo encuentro...",
  "payment_method_code": 10,
  "customer": {
    "company": "SRM-TRG S.A.S",
    "trade_name": "SRM-TRG",
    "names": "Santiago Rivera Marin",
    "address": "Cll. 22 #45C-45",
    "email": "[email protected]",
    "phone": "3103362199",
    "tribute_id": 21,
    "municipality_id": 1041,
    "identification": "1109780065",
    "identification_document_id": 3,
    "legal_organization_id": 2
  },
  "items": [
    {
      "name": "Laptop HP",
      "quantity": 1,
      "discount_rate": 11,
      "price": 1500000,
      "tax_rate": "19.00",
      "unit_measure_id": 70,
      "standard_code_id": 1,
      "is_excluded": 0,
      "tribute_id": 1,
      "withholding_taxes": [
        {
          "code": "06",
          "withholding_tax_rate": "7.00"
        }
      ]
    }
  ]
}

The example above omits reference_code and numbering_range_id intentionally — these are injected by the backend. If the Factus API returns a 409 despite a valid-looking request body, double-check that the payment_method_code, tribute_id, municipality_id, identification_document_id, and standard_code_id values exist in the Factus sandbox catalogues.

Example Response (200)

{
  "status": 200,
  "message": "OK",
  "data": {
    "company": {
      "nit": "901724254",
      "company": "FACTUS S.A.S.",
      "municipality": "San Gil"
    },
    "customer": {
      "identification": "1109780065",
      "dv": null,
      "graphic_representation_name": "Santiago Rivera Marin",
      "names": "Santiago Rivera Marin",
      "legal_organization": { "id": 2, "code": "2", "name": "Persona Natural" },
      "tribute": { "id": 21, "code": "ZZ", "name": "No aplica" },
      "municipality": { "id": 1041, "code": "73283", "name": "Fresno" }
    },
    "numbering_range": {
      "prefix": "SETP",
      "from": 990000000,
      "to": 995000000,
      "resolution_number": "18760000001",
      "start_date": "19-01-2019",
      "end_date": "19-01-2030",
      "months": 132
    },
    "billing_period": [],
    "bill": {
      "id": 9763,
      "document": { "code": "01", "name": "Factura electrónica de Venta" },
      "number": "SETP990009126",
      "reference_code": "N4T4H1R2F5",
      "status": 1,
      "send_email": 0,
      "qr": "https://catalogo-vpfe-hab.dian.gov.co/document/searchqr?documentkey=e6f14a89...",
      "cufe": "e6f14a894017c1c129354e902bb0803f3b1ff8cd179f34c286ae039fba6144d1256374bf567617e8589793a827b13bac",
      "validated": "28-01-2025 02:55:13 PM",
      "discount_rate": "0.00",
      "discount": "0.00",
      "gross_value": "1121848.74",
      "taxable_amount": "1121848.74",
      "tax_amount": "213151.26",
      "total": "1335000.00",
      "observation": null,
      "errors": [],
      "created_at": "28-01-2025 02:55:09 PM",
      "payment_due_date": null,
      "payment_form": { "code": "1", "name": "Pago de contado" },
      "payment_method": { "code": "10", "name": "Efectivo" },
      "public_url": "http://app-sandbox.factus.com.co/bills/show/43f4bc96..."
    },
    "related_documents": [],
    "items": [
      {
        "code_reference": "I5K7T",
        "name": "Laptop HP",
        "quantity": 1,
        "discount_rate": "11.00",
        "discount": "138655.46",
        "gross_value": "1121848.74",
        "tax_rate": "19.00",
        "taxable_amount": "1121848.74",
        "tax_amount": "213151.26",
        "price": "1500000.00",
        "is_excluded": 0,
        "unit_measure": { "id": 70, "code": "94", "name": "unidad" },
        "standard_code": { "id": 1, "code": "999", "name": "Estándar de adopción del contribuyente" },
        "tribute": { "id": 1, "code": "01", "name": "IVA" },
        "total": 1335000,
        "withholding_taxes": [
          {
            "tribute_code": "06",
            "name": "ReteRenta",
            "value": "78529.41",
            "rates": [{ "code": "06", "name": "ReteRenta", "rate": "7.00" }]
          }
        ]
      }
    ],
    "withholding_taxes": [
      { "tribute_code": "06", "name": "ReteRenta", "value": "78529.41" }
    ],
    "credit_notes": [],
    "debit_notes": []
  }
}

Code Examples

curl -X POST http://localhost:3000/factura \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "observation": "Venta de equipos de cómputo",
    "payment_method_code": 10,
    "customer": {
      "company": "SRM-TRG S.A.S",
      "trade_name": "SRM-TRG",
      "names": "Santiago Rivera Marin",
      "address": "Cll. 22 #45C-45",
      "email": "[email protected]",
      "phone": "3103362199",
      "tribute_id": 21,
      "municipality_id": 1041,
      "identification": "1109780065",
      "identification_document_id": 3,
      "legal_organization_id": 2
    },
    "items": [
      {
        "name": "Laptop HP",
        "quantity": 1,
        "discount_rate": 11,
        "price": 1500000,
        "tax_rate": "19.00",
        "unit_measure_id": 70,
        "standard_code_id": 1,
        "is_excluded": 0,
        "tribute_id": 1,
        "withholding_taxes": [
          { "code": "06", "withholding_tax_rate": "7.00" }
        ]
      }
    ]
  }'

const payload = {
  observation: "Venta de equipos de cómputo",
  payment_method_code: 10,
  customer: {
    company: "SRM-TRG S.A.S",
    trade_name: "SRM-TRG",
    names: "Santiago Rivera Marin",
    address: "Cll. 22 #45C-45",
    email: "[email protected]",
    phone: "3103362199",
    tribute_id: 21,
    municipality_id: 1041,
    identification: "1109780065",
    identification_document_id: 3,
    legal_organization_id: 2,
  },
  items: [
    {
      name: "Laptop HP",
      quantity: 1,
      discount_rate: 11,
      price: 1500000,
      tax_rate: "19.00",
      unit_measure_id: 70,
      standard_code_id: 1,
      is_excluded: 0,
      tribute_id: 1,
      withholding_taxes: [{ code: "06", withholding_tax_rate: "7.00" }],
    },
  ],
};

const response = await fetch("http://localhost:3000/factura", {
  method: "POST",
  headers: {
    "Accept": "application/json",
    "Content-Type": "application/json",
  },
  body: JSON.stringify(payload),
});

const result = await response.json();

if (result.status === 200) {
  const { bill } = result.data;
  console.log(`Created invoice: ${bill.number}`);
  console.log(`Reference code: ${bill.reference_code}`);
  console.log(`CUFE: ${bill.cufe}`);
} else if (result.status === 400) {
  console.error("Validation failed:", result.conflict);
} else {
  console.error("Error:", result);
}

Invoice Endpoints

Database Endpoints

POST /factura — Create and Validate a New Invoice

Endpoint

Request Body

Response

200 — Success

400 — Bad Request (Validation Failed)

409 — Conflict

500 — Internal Server Error

Example Request Body

Example Response (200)

Code Examples

​Endpoint

​Request Body

​Response

​200 — Success

​400 — Bad Request (Validation Failed)

​409 — Conflict

​500 — Internal Server Error

​Example Request Body

​Example Response (200)

​Code Examples

Endpoint

Request Body

Response

200 — Success

400 — Bad Request (Validation Failed)

409 — Conflict

500 — Internal Server Error

Example Request Body

Example Response (200)

Code Examples