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

number

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.

status

number

Always 200 on success.

message

string

Always "OK" on success.

data

object

Full invoice detail object.

Show data fields

company

object

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

Show company fields

url_logo

string

URL of the company logo image.

nit

string

Company tax identification number (NIT).

string

Check digit for the NIT.

company

string

Legal company name.

name

string

Display name.

graphic_representation_name

string

Name shown on the invoice graphic representation.

registration_code

string

Merchant registration code.

economic_activity

string

CIIU economic activity code.

phone

string

Company phone number.

string

Company email address.

direction

string

Company address.

municipality

string

City or municipality name.

customer

object

Information about the invoice recipient.

Show customer fields

identification

string

Customer identification number.

string | null

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

graphic_representation_name

string

Customer display name on the invoice.

trade_name

string

Customer trade name.

company

string

Customer company name.

names

string

Customer full name.

address

string

Customer address.

string

Customer email address.

phone

string

Customer phone number.

legal_organization

object

Legal organization type.

Show legal_organization fields

number

Internal ID.

code

string

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

name

string

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

tribute

object

Customer tribute/tax responsibility.

Show tribute fields

number

Internal ID.

code

string

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

name

string

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

municipality

object

Customer municipality.

Show municipality fields

number

Internal ID.

code

string

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

name

string

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

numbering_range

object

The DIAN-authorised numbering range used for this invoice.

Show numbering_range fields

prefix

string

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

from

number

First number in the authorised range.

number

Last number in the authorised range.

resolution_number

string

DIAN resolution number.

start_date

string

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

end_date

string

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

months

number

Total duration of the range in months.

billing_period

array

Billing period entries. Empty array for standard sales invoices.

bill

object

Core bill record.

Show bill fields

number

Internal Factus bill ID.

document

object

Document type (code and name).

number

string

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

reference_code

string

Auto-generated reference code.

status

number

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

send_email

number

Email dispatch flag. 0 = not sent.

string

DIAN QR verification URL.

cufe

string

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

validated

string

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

discount_rate

string

Global discount rate applied to the invoice.

discount

string

Absolute discount amount.

gross_value

string

Pre-tax subtotal.

taxable_amount

string

Taxable base amount.

tax_amount

string

Total tax amount.

total

string

Grand total including taxes.

observation

string | null

Free-text observation attached to the invoice.

errors

array

DIAN validation warnings/errors.

created_at

string

Creation timestamp.

payment_due_date

string | null

Payment due date, or null for cash payment.

qr_image

string

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

has_claim

number

Claim flag.

is_negotiable_instrument

number

Negotiable instrument flag.

payment_form

object

Payment form descriptor (code, name).

payment_method

object

Payment method descriptor (code, name).

public_url

string

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

Related document references. Empty array if none.

items

array

Line items on the invoice.

Show item fields

code_reference

string

Auto-generated item code reference.

name

string

Product or service name.

quantity

number

Quantity invoiced.

discount_rate

string

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

discount

string

Absolute discount amount for this line.

gross_value

string

Subtotal before tax for this line.

tax_rate

string

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

taxable_amount

string

Taxable amount for this line.

tax_amount

string

Tax amount for this line.

price

string

Unit price.

is_excluded

number

0 = taxable; 1 = tax-excluded item.

unit_measure

object

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

standard_code

object

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

tribute

object

Tax tribute descriptor (id, code, name).

total

number

Line total including tax.

withholding_taxes

array

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

withholding_taxes

array

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

credit_notes

array

Associated credit notes. Empty if none.

debit_notes

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"

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

Build docs developers (and LLMs) love

Invoice Endpoints

Database Endpoints

Documentation Index

​Endpoint

​Path Parameter

​Request

​Response

​200 — Success

​404 — Not Found

​409 — Conflict

​500 — Internal Server Error

​Example Response (200)

​Code Examples

Build docs developers (and LLMs) love

Endpoint

Path Parameter

Request

Response

200 — Success

404 — Not Found

409 — Conflict

500 — Internal Server Error

Example Response (200)

Code Examples