GET /factura/:number — Retrieve a Single Invoice

This endpoint retrieves the complete detail record for a single electronic invoice identified by its invoice number. The response includes the issuing company’s information, the full customer profile, the numbering range used, the bill object (containing the CUFE hash, QR code URL, and a base64-encoded QR image), the line items with calculated taxes, and any associated withholding taxes, credit notes, or debit notes.

Endpoint

GET /factura/:number

Path Parameter

string

required

The full invoice number as assigned by the Factus API (e.g., SETP990000009). This is the number field returned in the list response or in the response body after creating an invoice.

Request

No request body is required. The backend internally forwards the number path segment to GET /v1/bills/show/{number} on the Factus API, attaching the Bearer token from the server environment.

Response

200 — Success

Returns a JSON object whose data property contains the full invoice detail.

number

Always 200 on success.

string

Always "OK" on success.

object

Full invoice detail object.

Show data fields

object

Information about the issuing company (the Factus-registered entity).

Show company fields

string

URL of the company logo image.

string

Company tax identification number (NIT).

string

Check digit for the NIT.

string

Legal company name.

string

Display name.

string

Name shown on the invoice graphic representation.

string

Merchant registration code.

string

CIIU economic activity code.

string

Company phone number.

string

Company email address.

string

Company address.

string

City or municipality name.

object

Information about the invoice recipient.

Show customer fields

string

Customer identification number.

string | null

Check digit (applicable for legal entities; null for natural persons).

string

Customer display name on the invoice.

string

Customer trade name.

string

Customer company name.

string

Customer full name.

string

Customer address.

string

Customer email address.

string

Customer phone number.

object

Legal organization type.

Show legal_organization fields

number

Internal ID.

string

Code (e.g., "2").

string

Name (e.g., "Persona Natural").

object

Customer tribute/tax responsibility.

Show tribute fields

number

Internal ID.

string

Tribute code (e.g., "ZZ").

string

Tribute name (e.g., "No aplica").

object

Customer municipality.

Show municipality fields

number

Internal ID.

string

DANE municipality code (e.g., "73283").

string

Municipality name (e.g., "Fresno").

object

The DIAN-authorised numbering range used for this invoice.

Show numbering_range fields

string

Invoice number prefix (e.g., "SETP").

number

First number in the authorised range.

number

Last number in the authorised range.

string

DIAN resolution number.

string

Range validity start date ("DD-MM-YYYY").

string

Range validity end date ("DD-MM-YYYY").

number

Total duration of the range in months.

array

Billing period entries. Empty array for standard sales invoices.

object

Core bill record.

Show bill fields

number

Internal Factus bill ID.

object

Document type (code and name).

string

Full invoice number (e.g., "SETP990009126").

string

Auto-generated reference code.

number

0 = unvalidated; 1 = validated and sent to DIAN.

number

Email dispatch flag. 0 = not sent.

string

DIAN QR verification URL.

string

CUFE — Código Único de Factura Electrónica. The DIAN-assigned unique hash for this invoice.

string

Validation timestamp ("DD-MM-YYYY hh:mm:ss AM/PM").

string

Global discount rate applied to the invoice.

string

Absolute discount amount.

string

Pre-tax subtotal.

string

Taxable base amount.

string

Total tax amount.

string

Grand total including taxes.

string | null

Free-text observation attached to the invoice.

array

DIAN validation warnings/errors.

string

Creation timestamp.

string | null

Payment due date, or null for cash payment.

string

Base64-encoded PNG of the QR code (prefixed with data:image/png;base64,).

number

Claim flag.

number

Negotiable instrument flag.

object

Payment form descriptor (code, name).

object

Payment method descriptor (code, name).

string

Publicly accessible URL for viewing the invoice in the Factus web app.

Related document references. Empty array if none.

array

Line items on the invoice.

Show item fields

string

Auto-generated item code reference.

string

Product or service name.

number

Quantity invoiced.

string

Discount rate applied to this line (e.g., "11.00").

string

Absolute discount amount for this line.

string

Subtotal before tax for this line.

string

Tax rate percentage (e.g., "19.00").

string

Taxable amount for this line.

string

Tax amount for this line.

string

Unit price.

number

0 = taxable; 1 = tax-excluded item.

object

Unit of measure descriptor (id, code, name).

object

Standard product code descriptor (id, code, name).

object

Tax tribute descriptor (id, code, name).

number

Line total including tax.

array

Withholding tax entries for this line, each with tribute_code, name, value, and a rates array.

array

Aggregated withholding taxes across all line items. Each entry contains tribute_code, name, and value.

array

Associated credit notes. Empty if none.

array

Associated debit notes. Empty if none.

404 — Not Found

When the invoice number does not exist on the Factus side, the upstream API returns an error response that the backend will surface as a 409 CONFLICT (see below) or a 500, depending on the error type. Factus itself does not return a distinct 404 HTTP status — the backend maps all non-"OK" upstream responses to 409.

409 — Conflict

Returned when the Factus API responds with an unexpected status value.

{
  "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 Response (200)

{
  "status": 200,
  "message": "OK",
  "data": {
    "company": {
      "url_logo": "http://api-sandbox.factus.com.co/storage/images/logos/lC5CLGXHgwlv8slaoiKC6dHkVLIXQVaDkL9C1Yqc.png",
      "nit": "901724254",
      "dv": "1",
      "company": "FACTUS S.A.S.",
      "name": "FACTUS S.A.S.",
      "graphic_representation_name": "FACTUS S.A.S.",
      "registration_code": "bnnmbvncv",
      "economic_activity": "6201",
      "phone": "3133045345",
      "email": "[email protected]",
      "direction": "CARRERA 10 # 9 - 04",
      "municipality": "San Gil"
    },
    "customer": {
      "identification": "1109780065",
      "dv": null,
      "graphic_representation_name": "Santiago Rivera Marin",
      "trade_name": "",
      "company": "",
      "names": "Santiago Rivera Marin",
      "address": "Cll. 22 #45C-45",
      "email": "[email protected]",
      "phone": "3103362199",
      "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,
      "qr_image": "data:image/png;base64, iVBORw0KGgo...",
      "has_claim": 0,
      "is_negotiable_instrument": 0,
      "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 GET http://localhost:3000/factura/SETP990009126 \
  -H "Accept: application/json"

const number = "SETP990009126";

const response = await fetch(`http://localhost:3000/factura/${number}`, {
  method: "GET",
  headers: {
    "Accept": "application/json"
  }
});

const result = await response.json();

if (result.status === 200) {
  const { bill, customer, items } = result.data;
  console.log(`Invoice: ${bill.number}`);
  console.log(`Customer: ${customer.names}`);
  console.log(`Total: ${bill.total}`);
  console.log(`CUFE: ${bill.cufe}`);
} else {
  console.error("Error fetching invoice:", result);
}

Invoice Endpoints

Database Endpoints

GET /factura/:number — Retrieve a Single Invoice

Endpoint

Path Parameter

Request

Response

200 — Success

404 — Not Found

409 — Conflict

500 — Internal Server Error

Example Response (200)

Code Examples

​Endpoint

​Path Parameter

​Request

​Response

​200 — Success

​404 — Not Found

​409 — Conflict

​500 — Internal Server Error

​Example Response (200)

​Code Examples

Endpoint

Path Parameter

Request

Response

200 — Success

404 — Not Found

409 — Conflict

500 — Internal Server Error

Example Response (200)

Code Examples