> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gigstack.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Colombia: fields and invoice flow

> DIAN customer fields and the current public API's invoice compatibility rules.

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](/concepts/shared-fields#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](/concepts/issuer-setup#colombia). 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](/reference/createClients) 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](https://micrositios.dian.gov.co/sistema-de-facturacion-electronica/preguntas-frecuentes-reglas-de-validacion-que-se-activan-a-partir-del-01-de-agosto-2020/)
explains this five-code list. Consult its [current technical documentation](https://micrositios.dian.gov.co/sistema-de-facturacion-electronica/documentacion-tecnica/)
and [regulations](https://micrositios.dian.gov.co/sistema-de-facturacion-electronica/normatividad/)
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 |

<Note>
  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.
</Note>

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](/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.

<Note>
  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.
</Note>

### 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](/quickstart#1-set-your-environment), then check the
[environment and key distinction](/authentication#environments). 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.

```bash theme={null}
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.

```bash theme={null}
: "${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.

```bash theme={null}
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:

```bash theme={null}
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](mailto: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](/recipes/cancellation) to Colombia.
Colombian credit and annulment flows remain outside the end-to-end verification described here.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.