Examples by country🇨🇴 Colombia

➕ Create new documents

Postman collection

To help you with your integration, download our Postman Collection here: https://github.com/koyweforest/api-billing-postman

Invoice (Factura)

In order to create a new colombian invoice, you need to use the /documents endpoint with the proper parameters.

1{
2  "header": {
3    "account_id": 14540,
4    "document_type_id": "82",
5    "received_issued_flag": 0,
6    "issue_date": "2025-01-14",
7    "issuer_tax_id_code": "860517022-2",
8    "issuer_tax_id_type": "CO-NIT",
9    "issuer_legal_name": "<string>",
10    "issuer_address": "<string>",
11    "issuer_district": "<string>",
12    "issuer_city": "<string>",
13    "issuer_country_id": "66",
14    "issuer_phone": "<string>",
15    "issuer_activity": "<string>",
16    "receiver_tax_id_code": "860517022-2",
17    "receiver_tax_id_type": "CO-NIT",
18    "receiver_legal_name": "ESCUELA KEMPER URGATE",
19    "receiver_address": "<string>",
20    "receiver_county_id": "496",
21    "receiver_country_id": "66",
22    "receiver_phone": "<string>",
23    "receiver_activity": "<string>",
24    "payment_conditions": "0",
25    "currency_id": 28
26  },
27  "details": [
28    {
29      "quantity": 1,
30      "line_description": "Prueba Koywe",
31      "unit_measure": "UN",
32      "unit_price": 1500,
33      "long_description": "Esta es una linea de prueba",
34      "modifier_amount": -100,
35      "total_taxes": 266,
36      "modifier_percentage": 0,
37      "total_amount_line": 1666,
38      "taxes": [
39        {
40          "tax_type_id": "388",
41          "tax_percentage": 19,
42          "tax_amount": 266
43        }
44      ]
45    }
46  ],
47  "totals": {
48    "net_amount": 1400,
49    "taxes_amount": 266,
50    "total_amount": 1666
51  }
52}

Invoice with reported payment code (Factura con código de pago)

Specifies the payment code reported for the invoice, according to the DIAN payment codes of Colombia. This field identifies how the invoice payment was made or recorded.

If this field is not sent, its default value will be “cash”.

If you have doubts about which reported payment code to use, check the reported_payment_code table of codes.

1{
2  "header": {
3    "account_id": 14540,
4    "document_type_id": "82",
5    "received_issued_flag": 0,
6    "issue_date": "2025-01-14",
7    "issuer_tax_id_code": "860517022-2",
8    "issuer_tax_id_type": "CO-NIT",
9    "issuer_legal_name": "<string>",
10    "issuer_address": "<string>",
11    "issuer_district": "<string>",
12    "issuer_city": "<string>",
13    "issuer_country_id": "66",
14    "issuer_phone": "<string>",
15    "issuer_activity": "<string>",
16    "receiver_tax_id_code": "860517022-2",
17    "receiver_tax_id_type": "CO-NIT",
18    "receiver_legal_name": "ESCUELA KEMPER URGATE",
19    "receiver_address": "<string>",
20    "receiver_county_id": "496",
21    "receiver_country_id": "66",
22    "receiver_phone": "<string>",
23    "receiver_activity": "<string>",
24    "payment_conditions": "0",
25    "currency_id": 28,
26    "additional":{
27             "co_header":{
28                "reported_payment_code": 10
29             }
30          }
31  },
32  "details": [
33    {
34      "quantity": 1,
35      "line_description": "Prueba Koywe",
36      "unit_measure": "UN",
37      "unit_price": 1500,
38      "long_description": "Esta es una linea de prueba",
39      "modifier_amount": -100,
40      "total_taxes": 266,
41      "modifier_percentage": 0,
42      "total_amount_line": 1666,
43      "taxes": [
44        {
45          "tax_type_id": "388",
46          "tax_percentage": 19,
47          "tax_amount": 266
48        }
49      ]
50    }
51  ],
52  "totals": {
53    "net_amount": 1400,
54    "taxes_amount": 266,
55    "total_amount": 1666
56  }
57}

Invoice with a foreign receiver (Factura con receptor extranjero)

In colombia the same invoice used for domestic sales, is also used for foreign customers, you need to use the /documents endpoint with the proper parameters.

1{
2  "header": {
3    "account_id": 14540,
4    "document_type_id": "82",
5    "received_issued_flag": 0,
6    "issue_date": "2025-01-14",
7    "issuer_tax_id_code": "860517022-2",
8    "issuer_tax_id_type": "CO-NIT",
9    "issuer_legal_name": "<string>",
10    "issuer_address": "<string>",
11    "issuer_district": "<string>",
12    "issuer_city": "<string>",
13    "issuer_country_id": "66",
14    "issuer_phone": "<string>",
15    "issuer_activity": "<string>",
16    "receiver_tax_id_code": "872055616",
17    "receiver_tax_id_type": "CO-NOP",
18    "receiver_legal_name": "ESCUELA KEMPER URGATE",
19    "receiver_address": "Street #4564, zip 94114, San Francisco,",
20    "receiver_country_id": "89",
21    "receiver_phone": "<string>",
22    "receiver_activity": "<string>",
23    "payment_conditions": "0",
24    "currency_id": 28
25
26  },
27  "details": [
28    {
29      "quantity": 1,
30      "line_description": "Prueba Koywe",
31      "unit_measure": "UN",
32      "unit_price": 1500,
33      "long_description": "Esta es una linea de prueba",
34      "modifier_amount": -100,
35      "total_taxes": 266,
36      "modifier_percentage": 0,
37      "total_amount_line": 1666,
38      "taxes": [
39        {
40          "tax_type_id": "388",
41          "tax_percentage": 19,
42          "tax_amount": 266
43        }
44      ]
45    }
46  ],
47  "totals": {
48    "net_amount": 1400,
49    "taxes_amount": 266,
50    "total_amount": 1666
51  }
52}

Invoice with taxes and withholdings (Factura con impuesto y retención)

Invoice that includes applicable taxes (such as VAT) and amounts withheld by the buyer (such as VAT withholding), which are not paid to the seller but instead reported to the tax authority.

1{
2  "header": {
3    "account_id": 14540,
4    "document_type_id": "82",
5    "received_issued_flag": 0,
6    "issue_date": "2025-01-14",
7    "issuer_tax_id_code": "860517022-2",
8    "issuer_tax_id_type": "CO-NIT",
9    "issuer_legal_name": "<string>",
10    "issuer_address": "<string>",
11    "issuer_district": "<string>",
12    "issuer_city": "<string>",
13    "issuer_country_id": "66",
14    "issuer_phone": "<string>",
15    "issuer_activity": "<string>",
16    "receiver_tax_id_code": "860517022-2",
17    "receiver_tax_id_type": "CO-NIT",
18    "receiver_legal_name": "ESCUELA KEMPER URGATE",
19    "receiver_address": "<string>",
20    "receiver_county_id": "496",
21    "receiver_country_id": "66",
22    "receiver_phone": "<string>",
23    "receiver_activity": "<string>",
24    "payment_conditions": "0",
25    "currency_id": 28
26  },
27  "details": [
28    {
29      "quantity": 1,
30      "line_description": "Prueba Koywe",
31      "unit_measure": "UN",
32      "unit_price": 1000000,
33      "long_description": "Esta es una linea de prueba",
34      "total_taxes": 161500,
35      "modifier_percentage": 0,
36      "total_amount_line": 1161500,
37      "taxes": [
38              {
39                "tax_type_id": 388,
40                "tax_percentage": 19,
41                "tax_amount": 190000
42              },
43              {
44                "tax_type_id": 397,
45                "tax_percentage": -2.85,
46                "tax_amount": -28500
47              }
48            ]
49    }
50  ],
51  "totals": {
52    "net_amount": 1000000,
53    "taxes_amount": 161500,
54    "total_amount": 1161500
55  }
56}

Credit note with reference to reference_number (Nota de crédito con referencia de reference_number)

In order to create a new colombian credit note, you need to use the /documents endpoint with the proper parameters.

Use reference_number (document_number) to reference the document you are cancelling.

1{
2  "header": {
3    "account_id": 14540,
4    "document_type_id": "83",
5    "received_issued_flag": 0,
6    "issue_date": "2025-01-14",
7    "issuer_tax_id_code": "860517022-2",
8    "issuer_tax_id_type": "CO-NIT",
9    "issuer_legal_name": "<string>",
10    "issuer_address": "<string>",
11    "issuer_district": "<string>",
12    "issuer_city": "<string>",
13    "issuer_country_id": "66",
14    "issuer_phone": "<string>",
15    "issuer_activity": "<string>",
16    "receiver_tax_id_code": "860517022-2",
17    "receiver_tax_id_type": "CO-NIT",
18    "receiver_legal_name": "ESCUELA KEMPER URGATE",
19    "receiver_address": "<string>",
20    "receiver_county_id": "496",
21    "receiver_country_id": "66",
22    "receiver_phone": "<string>",
23    "receiver_activity": "<string>",
24    "payment_conditions": "0",
25    "currency_id": 28
26  },
27  "details": [
28    {
29      "quantity": 1,
30      "line_description": "Prueba Koywe",
31      "unit_measure": "UN",
32      "unit_price": 1500,
33      "long_description": "Esta es una linea de prueba",
34      "modifier_amount": -100,
35      "total_taxes": 266,
36      "modifier_percentage": 0,
37      "total_amount_line": 1666,
38      "taxes": [
39        {
40          "tax_type_id": "388",
41          "tax_percentage": 19,
42          "tax_amount": 266
43        }
44      ]
45    }
46  ],
47  "references": [
48    {
49        "document_type_id": "82",
50        "reference_number": "SETT1040108",
51        "reference_code": 1,
52        "description": "Anulacion solicitada por el emisor",
53        "reference_date": "2025-01-14"
54    }
55  ],
56  "totals": {
57    "net_amount": 1400,
58    "taxes_amount": 266,
59    "total_amount": 1666
60  }
61}

Credit note with reference to reference_document_id (Nota de crédito con referencia de reference_document_id)

In order to create a new colombian credit note, you need to use the /documents endpoint with the proper parameters.

Use reference_document_id (document_id) to reference the document you are cancelling.

1{
2  "header": {
3    "account_id": 14540,
4    "document_type_id": "83",
5    "received_issued_flag": 0,
6    "issue_date": "2025-01-14",
7    "issuer_tax_id_code": "860517022-2",
8    "issuer_tax_id_type": "CO-NIT",
9    "issuer_legal_name": "<string>",
10    "issuer_address": "<string>",
11    "issuer_district": "<string>",
12    "issuer_city": "<string>",
13    "issuer_country_id": "66",
14    "issuer_phone": "<string>",
15    "issuer_activity": "<string>",
16    "receiver_tax_id_code": "860517022-2",
17    "receiver_tax_id_type": "CO-NIT",
18    "receiver_legal_name": "ESCUELA KEMPER URGATE",
19    "receiver_address": "<string>",
20    "receiver_county_id": "496",
21    "receiver_country_id": "66",
22    "receiver_phone": "<string>",
23    "receiver_activity": "<string>",
24    "payment_conditions": "0",
25    "currency_id": 28
26  },
27  "details": [
28    {
29      "quantity": 1,
30      "line_description": "Prueba Koywe",
31      "unit_measure": "UN",
32      "unit_price": 1500,
33      "long_description": "Esta es una linea de prueba",
34      "modifier_amount": -100,
35      "total_taxes": 266,
36      "modifier_percentage": 0,
37      "total_amount_line": 1666,
38      "taxes": [
39        {
40          "tax_type_id": "388",
41          "tax_percentage": 19,
42          "tax_amount": 266
43        }
44      ]
45    }
46  ],
47  "references": [
48    {
49        "document_type_id": "82",
50        "reference_document_id": 1548,
51        "reference_code": 1,
52        "description": "Anulacion solicitada por el emisor",
53        "reference_date": "2025-01-14"
54    }
55  ],
56  "totals": {
57    "net_amount": 1400,
58    "taxes_amount": 266,
59    "total_amount": 1666
60  }
61}

Debit note with reference to reference_number (Nota de débito con referencia de reference_number)

In order to create a new colombian debit note, you need to use the /documents endpoint with the proper parameters.

Use reference_number (document_number) to reference the document you are cancelling.

1{
2  "header": {
3    "account_id": 14540,
4    "document_type_id": "84",
5    "received_issued_flag": 0,
6    "issue_date": "2025-01-14",
7    "issuer_tax_id_code": "860517022-2",
8    "issuer_tax_id_type": "CO-NIT",
9    "issuer_legal_name": "<string>",
10    "issuer_address": "<string>",
11    "issuer_district": "<string>",
12    "issuer_city": "<string>",
13    "issuer_country_id": "66",
14    "issuer_phone": "<string>",
15    "issuer_activity": "<string>",
16    "receiver_tax_id_code": "860517022-2",
17    "receiver_tax_id_type": "CO-NIT",
18    "receiver_legal_name": "ESCUELA KEMPER URGATE",
19    "receiver_address": "<string>",
20    "receiver_county_id": "496",
21    "receiver_country_id": "66",
22    "receiver_phone": "<string>",
23    "receiver_activity": "<string>",
24    "payment_conditions": "0",
25    "currency_id": 28
26  },
27  "details": [
28    {
29      "quantity": 1,
30      "line_description": "Prueba Koywe",
31      "unit_measure": "UN",
32      "unit_price": 1500,
33      "long_description": "Esta es una linea de prueba",
34      "modifier_amount": -100,
35      "total_taxes": 266,
36      "modifier_percentage": 0,
37      "total_amount_line": 1666,
38      "taxes": [
39        {
40          "tax_type_id": "388",
41          "tax_percentage": 19,
42          "tax_amount": 266
43        }
44      ]
45    }
46  ],
47  "references": [
48    {
49        "document_type_id": "82",
50        "reference_number": "SETT1040108",
51        "reference_code": 3,
52        "description": "Cambio de valor",
53        "reference_date": "2025-01-14"
54    }
55  ],
56  "totals": {
57    "net_amount": 1400,
58    "taxes_amount": 266,
59    "total_amount": 1666
60  }
61}

Debit note with reference to reference_document_id (Nota de débito con referencia de reference_document_id)

In order to create a new colombian debit note, you need to use the /documents endpoint with the proper parameters.

Use reference_document_id (document_id) to reference the document you are cancelling.

1{
2  "header": {
3    "account_id": 14540,
4    "document_type_id": "84",
5    "received_issued_flag": 0,
6    "issue_date": "2025-01-14",
7    "issuer_tax_id_code": "860517022-2",
8    "issuer_tax_id_type": "CO-NIT",
9    "issuer_legal_name": "<string>",
10    "issuer_address": "<string>",
11    "issuer_district": "<string>",
12    "issuer_city": "<string>",
13    "issuer_country_id": "66",
14    "issuer_phone": "<string>",
15    "issuer_activity": "<string>",
16    "receiver_tax_id_code": "860517022-2",
17    "receiver_tax_id_type": "CO-NIT",
18    "receiver_legal_name": "ESCUELA KEMPER URGATE",
19    "receiver_address": "<string>",
20    "receiver_county_id": "496",
21    "receiver_country_id": "66",
22    "receiver_phone": "<string>",
23    "receiver_activity": "<string>",
24    "payment_conditions": "0",
25    "currency_id": 28
26  },
27  "details": [
28    {
29      "quantity": 1,
30      "line_description": "Prueba Koywe",
31      "unit_measure": "UN",
32      "unit_price": 1500,
33      "long_description": "Esta es una linea de prueba",
34      "modifier_amount": -100,
35      "total_taxes": 266,
36      "modifier_percentage": 0,
37      "total_amount_line": 1666,
38      "taxes": [
39        {
40          "tax_type_id": "388",
41          "tax_percentage": 19,
42          "tax_amount": 266
43        }
44      ]
45    }
46  ],
47  "references": [
48    {
49        "document_type_id": "82",
50        "reference_document_id": 1548,
51        "reference_code": 3,
52        "description": "Cambio de valor",
53        "reference_date": "2025-01-14"
54    }
55  ],
56  "totals": {
57    "net_amount": 1400,
58    "taxes_amount": 266,
59    "total_amount": 1666
60  }
61}

POS equivalent document (Documento equivalente POS)

POS will only generate XML, no PDF will be generated on test or production environment. You can use the data to generate your own document format

1{
2  "header": {
3    "account_id": 14540,
4    "document_type_id": "87",
5    "received_issued_flag": 0,
6    "issue_date": "2025-01-31",
7    "issuer_tax_id_code": "860517022-2",
8    "issuer_tax_id_type": "CO-NIT",
9    "issuer_legal_name": "<string>",
10    "issuer_address": "<string>",
11    "issuer_district": "<string>",
12    "issuer_city": "<string>",
13    "issuer_country_id": "66",
14    "issuer_phone": "<string>",
15    "issuer_activity": "<string>",
16    "receiver_tax_id_code": "860517022-2",
17    "receiver_tax_id_type": "CO-NIT",
18    "receiver_legal_name": "ESCUELA KEMPER URGATE",
19    "receiver_address": "<string>",
20    "receiver_county_id": "496",
21    "receiver_country_id": "66",
22    "receiver_phone": "<string>",
23    "receiver_activity": "<string>",
24    "payment_conditions": "0",
25    "currency_id": 28,
26    "postal_code": "11001",
27    "receiver_email": "miemail@email.com"
28  },
29  "details": [
30    {
31      "quantity": 1,
32      "line_description": "Prueba Koywe",
33      "unit_measure": "UN",
34      "unit_price": 1500,
35      "long_description": "Esta es una linea de prueba",
36      "modifier_amount": -100,
37      "total_taxes": 266,
38      "modifier_percentage": 0,
39      "total_amount_line": 1666,
40      "taxes": [
41        {
42          "tax_type_id": "388",
43          "tax_percentage": 19,
44          "tax_amount": 266
45        }
46      ]
47    }
48  ],
49  "totals": {
50    "net_amount": 1400,
51    "taxes_amount": 266,
52    "total_amount": 1666
53  }
54}

POS equivalent credit note (Nota de crédito para documento equivalente POS)

POS will only generate XML, no PDF will be generated on test or production environment. You can use the data to generate your own document format

1{
2  "header": {
3    "account_id": 14540,
4    "document_type_id": "88",
5    "received_issued_flag": 0,
6    "issue_date": "2025-01-31",
7    "issuer_tax_id_code": "860517022-2",
8    "issuer_tax_id_type": "CO-NIT",
9    "issuer_legal_name": "<string>",
10    "issuer_address": "<string>",
11    "issuer_district": "<string>",
12    "issuer_city": "<string>",
13    "issuer_country_id": "66",
14    "issuer_phone": "<string>",
15    "issuer_activity": "<string>",
16    "receiver_tax_id_code": "860517022-2",
17    "receiver_tax_id_type": "CO-NIT",
18    "receiver_legal_name": "ESCUELA KEMPER URGATE",
19    "receiver_address": "<string>",
20    "receiver_county_id": "496",
21    "receiver_country_id": "66",
22    "receiver_phone": "<string>",
23    "receiver_activity": "<string>",
24    "payment_conditions": "0",
25    "currency_id": 28,
26    "postal_code": "11001",
27    "receiver_email": "miemail@email.com"
28  },
29  "details": [
30    {
31      "quantity": 1,
32      "line_description": "Prueba Koywe",
33      "unit_measure": "UN",
34      "unit_price": 1500,
35      "long_description": "Esta es una linea de prueba",
36      "modifier_amount": -100,
37      "total_taxes": 266,
38      "modifier_percentage": 0,
39      "total_amount_line": 1666,
40      "taxes": [
41        {
42          "tax_type_id": "388",
43          "tax_percentage": 19,
44          "tax_amount": 266
45        }
46      ]
47    }
48  ],
49  "references": [
50    {
51        "document_type_id": 87,
52        "reference_number": "EPOS217",
53        "reference_code": 1,
54        "description": "Anulacion solicitada por el emisor",
55        "reference_date": "2025-01-31"
56    }
57  ],
58  "totals": {
59    "net_amount": 1400,
60    "taxes_amount": 266,
61    "total_amount": 1666
62  }
63}

support document (Documento soporte)

DIAN doesn’t allow issuing support documents on its testing environment, so when issuing this using sandbox credentials no XML or PDF will be returned.

support document credit note (Nota de crédito a documento soporte)

DIAN doesn’t allow issuing support documents on its testing environment, so when issuing this using sandbox credentials no XML or PDF will be returned.

Response status in result the API Rest

statusdescription
0The draft was created successfully, signed, and sent to the SII successfully.
1There are errors in the input, so the draft was not generated nor sent to the SII. The error details will be in error_message.
2The draft was created successfully; however, there are other issues (e.g., lack of folios) that prevented it from being sent to the SII. The error details will be in error_message.
1{
2   "document_id": 377,
3   "header":    {
4      "account_id": 14540,
5      "document_type_id": 82,
6      "document_type_taxbureau": "01",
7      "document_number": 1040447,
8      "received_issued_flag": 1,
9      "taxbureau_validation_status": null,
10      "issue_date": "2025-04-15",
11      "issuer_tax_id_code": "860517022-2",
12      "issuer_tax_id_type": "CO-NIT",
13      "issuer_legal_name": "Demo Colombia",
14      "issuer_address": "",
15      "issuer_district": "",
16      "issuer_city": "",
17      "issuer_country_id": 253,
18      "issuer_phone": "442020550",
19      "issuer_activity": "",
20      "receiver_tax_id_code": "1097491385-1",
21      "receiver_tax_id_type": "CO-NIT",
22      "receiver_legal_name": "ESCUELAa KEMPER URGATE",
23      "receiver_address": "",
24      "receiver_district": "",
25      "receiver_city": "",
26      "receiver_country_id": 66,
27      "receiver_phone": "<string>",
28      "receiver_activity": "<string>",
29      "document_status": 1,
30      "payment_conditions": "0",
31      "currency_id": 28
32   },
33   "details": [   {
34      "quantity": "1.000000",
35      "line_description": "Prueba Koywe",
36      "long_description": "Esta es una linea de prueba",
37      "unit_measure": "UN",
38      "unit_price": "3660.000000",
39      "vat_status": "0"
40   }],
41   "references": null,
42   "global_modifiers": null,
43   "totals":    {
44      "net_amount": 3660,
45      "taxes_amount": 695.4,
46      "total_amount": "4355.40"
47   },
48   "electronic_document":    {
49      "document_xml": "PD94bWwgdmVyc2lvbj0iMS4wIiB...",
50      "document_pdf": "JVBERi0xLjMKMyAwIG9iago8PC9..."
51   },
52   "payment_link": null,
53   "result":    {
54      "status": 0,
55      "error_message": ""
56   },
57   "_links": {"self": {"href": "https://api-billing.koywe.com/V1/documents"}}
58}
API Reference POST /documents

Detailed endpoint documentation