Colombia: fields and invoice flow

Use this guide when the issuing business is configured for Colombian invoicing. The customer and invoice routes are shared with Mexico. The Colombian provider maps the data to DIAN documents through Factus. Start with the shared customer fields. For a domestic recipient, add address.country: "COL" and the identification details below. Changing the customer’s country does not configure the issuing business.

Before you start

Complete Colombia issuer setup. Confirm the selected team, provider credentials, numbering configuration, and test environment with the owner. The public team API does not expose the provider selection. A saved Colombian customer does not configure the issuer.

Customer identification

These fields are accepted on a saved customer and on an embedded invoice customer. They are optional in the shared input schema; supplying a contact does not guarantee that its information is sufficient for DIAN issuance.

Field	Meaning and current behavior
`tax_id`	Identification number. For a national NIT, send the number without its verification digit. The mapper also removes a digit separated by a hyphen.
`document_type`	DIAN document code. Examples: `"31"` for national NIT, `"13"` for cédula de ciudadanía, `"41"` for passport, `"50"` for foreign NIT.
`organization_type`	`1` for legal entity, `2` for natural person. Honored for national NIT; foreign NIT maps to legal entity, other document types to natural person.
`tribute_code`	`"01"` for IVA responsibility or `"ZZ"` for not applicable. Only national NIT can retain `"01"`; other identification types map to `"ZZ"`.
`fiscal_responsibilities`	Array of supported codes: `O-13`, `O-15`, `O-23`, `O-47`, `R-99-PN`. If omitted, the provider applies its `R-99-PN` default.
`dv`	One-digit verification value accepted on the customer. It is not sent to Factus; the provider derives the NIT verification digit.
`municipality_code`	Five-digit DANE municipality code for a domestic Colombian recipient. Omitted from the provider request for foreign recipients and anonymous final consumers.
`address.country`	Recipient country, such as `"COL"`. Supply the actual country explicitly.
`address.city`, `address.state`	City and department, also used to resolve a domestic municipality when its code is absent.
`name`, `legal_name`, `company`	Recipient names. For a legal entity, the provider mapping chooses `company`, then `legal_name`, then `name` as its company name.

Supply the recipient’s actual classification instead of relying on fallbacks. The mapper removes R-99-PN when it is combined with an O-* responsibility. See the customer API reference for the full accepted document-code list.

Fiscal responsibility codes

These are the five values accepted by the API. Use the recipient’s actual registered responsibilities; a default is not a determination of their tax status.

Code	Meaning
`O-13`	Large taxpayer (Gran contribuyente)
`O-15`	Self-withholding taxpayer (Autorretenedor)
`O-23`	IVA withholding agent (Agente de retención IVA)
`O-47`	Simple taxation regime (Régimen simple de tributación)
`R-99-PN`	None of those listed responsibilities (No responsable)

DIAN’s validation FAQ, question 1 explains this five-code list. Consult its current technical documentation and regulations for the applicable requirements. fiscal_responsibilities and tribute_code are separate fields: do not infer IVA responsibility solely from R-99-PN.

Invoice compatibility fields

The public POST /invoices/income validator still requires these fields for Colombia:

Public API field	What to send	Colombian mapping
`use`	A string is required by the shared schema	Not mapped to a DIAN Uso CFDI field; do not treat it as Colombian fiscal classification
`payment_form`	A code accepted by the API reference, such as `"03"` for a transfer	`"03"` becomes DIAN payment method `"47"`
`payment_method`	`"PUE"` or `"PPD"`	`PUE` maps to immediate payment; `PPD` maps to credit
`currency`	`"COP"` for an invoice in Colombian pesos	Local amounts sent to Factus in COP
`exchange_rate`	For foreign currency, COP per one unit of that currency	Provider conversion uses the rate rounded to two decimals

Send the public API code "03" for a bank transfer. Although the Colombian provider uses "47", the current income and draft request validators do not accept "47" as payment_form. Provider payloads and public API requests have different schemas.

For foreign-currency invoices, supply an explicit valid rate in COP per one unit of the invoice currency. If omitted, the public issuance path attempts a rate lookup, which can fail. Invalid foreign-currency rates, including 1, can be rejected before the request reaches Factus. The provider adapter rounds an accepted rate to two decimals. Do not rely on omitted or invalid rates producing an invoice with unchanged amounts.

Credit invoices and item fields

The provider requires a due date for a credit invoice. Its adapter reads payment_due_date, but that field is not exposed by the current public income or draft request schema. The Mexico PPD and payment-complement recipe is therefore not a verified Colombian credit-invoice workflow. The public item schema exposes description, quantity, unit_price, product_key, unit_key, and taxes. The Colombian adapter uses the product key as an item reference fallback; it does not use the Mexican unit_key as its DIAN unit code. Provider-only fields such as unit_measure_code are not exposed by this public item schema. Do not copy a direct Factus item payload into a gigstack request. tax_system and Mexican SAT catalogs do not replace Colombian identification, responsibility, or municipality codes.

Issuer setup and verification

The issuing team needs its Colombian provider credentials and numbering configuration for the selected environment. Its test and live configurations are separate. This page was checked against the public request schemas and Colombian provider mappings on October 8, 2026. It has not been exercised end to end with a Colombian test issuer. The existing staging verification covers the Mexican examples; it does not prove Colombian issuance, credit notes, or cancellation behavior.

First immediate-payment invoice

Case: a Colombian test issuer invoices one service for COP 100,000 plus illustrative 19% IVA, paid immediately by bank transfer. The intended total is COP 119,000. Use the classification and taxes appropriate to your actual transaction.

The requests below were reviewed against the public validators and Colombian provider mapping. They have not been executed with a Colombian test issuer. The expected response fields are source-reviewed, not captured test results. Test recipient data must come from your approved provider test setup; no universal Colombian fixture is assumed.

1. Create the Colombian test recipient

Use Bash with curl and jq. Set GIGSTACK_BASE_URL and GIGSTACK_API_KEY with the quickstart environment commands, then check the environment and key distinction. Supply CO_TEST_NIT without the verification digit, CO_TEST_LEGAL_NAME, and a unique CO_CUSTOMER_REFERENCE locally from your approved test setup. The example models a domestic legal entity, IVA responsible, with no listed special fiscal responsibility, located in Bogotá (11001). Adjust those classifications and location to the recipient before submitting.

set -euo pipefail
: "${GIGSTACK_BASE_URL:?Set the correct API base URL}"
: "${GIGSTACK_API_KEY:?Set a test key locally}"
: "${CO_TEST_NIT:?Set the approved test recipient NIT}"
: "${CO_TEST_LEGAL_NAME:?Set the approved test recipient legal name}"
: "${CO_CUSTOMER_REFERENCE:?Set a stable test customer reference}"

jq -n --arg nit "$CO_TEST_NIT" --arg name "$CO_TEST_LEGAL_NAME" \
  --arg reference "$CO_CUSTOMER_REFERENCE" '{
  name: $name,
  legal_name: $name,
  company: $name,
  email: "customer@example.com",
  tax_id: $nit,
  document_type: "31",
  organization_type: 1,
  tribute_code: "01",
  fiscal_responsibilities: ["R-99-PN"],
  municipality_code: "11001",
  address: {country: "COL", city: "Bogotá", state: "Bogotá D.C."},
  metadata: {external_id: $reference},
  search: {on_key: "metadata.external_id", on_value: $reference, update: false}
}' > co-customer-body.json

curl --fail-with-body "$GIGSTACK_BASE_URL/clients" \
  -H "Authorization: Bearer $GIGSTACK_API_KEY" \
  -H 'Content-Type: application/json' \
  --data @co-customer-body.json > co-customer.json

jq -e '.data.id and (.data.livemode == false)' co-customer.json
CLIENT_ID=$(jq -er '.data.id' co-customer.json)
export CLIENT_ID

Expect 201 for a new customer or 200 when the search reuses one. Inspect the returned recipient details before continuing: search.update: false does not refresh an existing record. Mexico SAT validation fields do not establish DIAN validity.

2. Prepare and review the invoice

Set CO_ORDER_REFERENCE to the stable reference for this one invoice. use: "G03" below is only a compatibility string accepted by the shared API; the Colombia adapter does not transmit it as a DIAN fiscal classification. Likewise, product_key provides an item reference fallback; its Mexican classification meaning does not apply here.

: "${CO_ORDER_REFERENCE:?Set a stable reference for this test invoice}"

jq -n --arg client "$CLIENT_ID" --arg reference "$CO_ORDER_REFERENCE" '{
  client: {id: $client},
  currency: "COP",
  exchange_rate: 1,
  use: "G03",
  payment_form: "03",
  payment_method: "PUE",
  items: [{
    description: "One service for the Colombian test invoice",
    product_key: "80101500",
    unit_key: "E48",
    quantity: 1,
    unit_price: 100000,
    taxes: [{type: "IVA", rate: 0.19, inclusive: false, withholding: false, factor: "Tasa"}]
  }],
  automation_type: "none",
  send_email: false,
  ignore_emails: true,
  idempotency_key: $reference,
  metadata: {external_id: $reference}
}' > co-invoice-body.json

jq . co-invoice-body.json

Review the customer, amount, currency, tax treatment, team, and test mode. PUE selects immediate payment in the adapter. This request records an invoice; it does not collect the bank transfer or register a payment record.

3. Issue only after review and authorization

POST /invoices/income issues immediately through the configured provider.

curl --fail-with-body "$GIGSTACK_BASE_URL/invoices/income" \
  -H "Authorization: Bearer $GIGSTACK_API_KEY" \
  -H 'Content-Type: application/json' \
  --data @co-invoice-body.json > co-invoice.json

jq -e '.data.uuid and (.data.status == "valid") and (.data.livemode == false)' co-invoice.json
INVOICE_ID=$(jq -er '.data.uuid' co-invoice.json)
export INVOICE_ID

curl --fail-with-body "$GIGSTACK_BASE_URL/invoices/income/$INVOICE_ID" \
  -H "Authorization: Bearer $GIGSTACK_API_KEY" > co-issued-invoice.json

jq '{id: .data.uuid, status: .data.status, livemode: .data.livemode,
     currency: .data.currency, subtotal: .data.subtotal,
     taxes: .data.taxes, total: .data.total}' co-issued-invoice.json

The source-defined success response is HTTP 200 with data.uuid. Preserve that value as an opaque identifier: the Colombian adapter derives it from the provider’s CUFE, CUDE, or document number; do not require a Mexican UUID format. Verify the stored recipient, COP currency, intended totals, and status: "valid". If any check fails, retain the response and investigate before another issuance attempt.

Recover after a timeout

Keep the same business reference. Look up the original invoice by the exact idempotency_key filter; do not add metadata filters to this lookup:

curl --fail-with-body --get "$GIGSTACK_BASE_URL/invoices/income" \
  -H "Authorization: Bearer $GIGSTACK_API_KEY" \
  --data-urlencode "idempotency_key=$CO_ORDER_REFERENCE" > co-reconcile.json

jq '.data[] | {id: .uuid, client: .client.id, status, livemode,
              currency, subtotal, taxes, total}' co-reconcile.json

For a matching result, compare the intended CLIENT_ID, test mode, COP currency and COP 119,000 total before treating it as your completed invoice. Save its uuid and read that invoice again. A different customer or amount is a reference conflict to investigate. Zero matches does not prove issuance failed. The provider may have issued a document before gigstack persisted it. Do not assume the Mexican PAC retry guarantees establish identical Colombian provider behavior. For an ambiguous result, ask support@gigstack.io to reconcile the provider document, providing the team, environment/mode, business reference, request time and redacted error. Never include the API key or provider credentials. Colombian annulment produces a credit note and can leave the original invoice valid. Do not apply the Mexican cancellation completion check to Colombia. Colombian credit and annulment flows remain outside the end-to-end verification described here.

Start here

Fields by country

Shared examples

Mexico · CFDI examples

Build and troubleshoot

Invoicing

Customers and payments

Mexico · SAT

Accounts

Mexico · SAT catalogs

Colombia: fields and invoice flow

Before you start

Customer identification

Fiscal responsibility codes

Invoice compatibility fields

Credit invoices and item fields

Issuer setup and verification

First immediate-payment invoice

1. Create the Colombian test recipient

2. Prepare and review the invoice

3. Issue only after review and authorization

Recover after a timeout

​Before you start

​Customer identification

​Fiscal responsibility codes

​Invoice compatibility fields

​Credit invoices and item fields

​Issuer setup and verification

​First immediate-payment invoice

​1. Create the Colombian test recipient

​2. Prepare and review the invoice

​3. Issue only after review and authorization

​Recover after a timeout

Before you start

Customer identification

Fiscal responsibility codes

Invoice compatibility fields

Credit invoices and item fields

Issuer setup and verification

First immediate-payment invoice

1. Create the Colombian test recipient

2. Prepare and review the invoice

3. Issue only after review and authorization

Recover after a timeout