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:

observation

string

required

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

payment_method_code

number

required

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

customer

object

required

Object describing the invoice recipient.

Show customer fields

company

string

required

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

trade_name

string

required

Trade name. Pass an empty string if not applicable.

names

string

required

Customer full name.

address

string

required

Customer postal address.

string

required

Customer email address.

phone

string

required

Customer phone number.

tribute_id

number

required

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

municipality_id

number

required

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

identification

string

required

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

identification_document_id

number

required

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

legal_organization_id

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.

items

array

required

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

Show item fields

name

string

required

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

quantity

number

required

Quantity of units invoiced.

price

number

required

Unit price in Colombian pesos (COP).

discount_rate

number

required

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

tax_rate

string

required

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

unit_measure_id

number

required

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

standard_code_id

number

required

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

tribute_id

number

required

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

is_excluded

number

required

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

withholding_taxes

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"
      }
    ]
  }
}

conflict.missing_properties

array

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

conflict.require

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" }
        ]
      }
    ]
  }'

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

Build docs developers (and LLMs) love

Invoice Endpoints

Database Endpoints

Documentation Index

​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

Build docs developers (and LLMs) love

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