Ejemplos por país
➕ Crear documentos
Colección de Postman
Para facilitar su integración, descargue nuestra Colección de Postman aquí: https://github.com/koyweforest/api-billing-postman
Para ayudar con las pruebas, puede usar la siguiente información al emitir documentos:
| account_id | NIT | legal_name | activity | postalcode |
|---|---|---|---|---|
| 14540 | 860517022-2 |
Factura (Factura)
Para crear una nueva factura colombiana, debe usar el endpoint /documents con los parámetros adecuados.
- Endpoint: https://api-billing.koywe.com/V1/documents
- Método: POST
- Encabezados requeridos:
- Content-Type: application/json
- Authorization: Bearer \<token>
- Accept: */*
{
"header": {
"account_id": 14540,
"document_type_id": "82",
"received_issued_flag": 0,
"issue_date": "2025-01-14",
"issuer_tax_id_code": "860517022-2",
"issuer_tax_id_type": "CO-NIT",
"issuer_legal_name": "<string>",
"issuer_address": "<string>",
"issuer_district": "<string>",
"issuer_city": "<string>",
"issuer_country_id": "66",
"issuer_phone": "<string>",
"issuer_activity": "<string>",
"receiver_tax_id_code": "860517022-2",
"receiver_tax_id_type": "CO-NIT",
"receiver_legal_name": "ESCUELA KEMPER URGATE",
"receiver_address": "<string>",
"receiver_county_id": "496",
"receiver_country_id": "66",
"receiver_phone": "<string>",
"receiver_activity": "<string>",
"payment_conditions": "0",
"currency_id": 28
},
"details": [
{
"quantity": 1,
"line_description": "Prueba Koywe",
"unit_measure": "UN",
"unit_price": 1500,
"long_description": "Esta es una linea de prueba",
"modifier_amount": -100,
"total_taxes": 266,
"modifier_percentage": 0,
"total_amount_line": 1666,
"taxes": [
{
"tax_type_id": "388",
"tax_percentage": 19,
"tax_amount": 266
}
]
}
],
"totals": {
"net_amount": 1400,
"taxes_amount": 266,
"total_amount": 1666
}
}
Factura sin envío automático de correo electrónico al cliente final
Este parámetro indica que la factura generada no será enviada automáticamente a la dirección de correo electrónico registrada en receiver_email.
Se utiliza cuando se debe omitir el envío automático y gestionar la entrega del documento por otros medios.
- Endpoint: https://api-billing.koywe.com/V1/documents
- Método: POST
- Encabezados requeridos:
- Content-Type: application/json
- Authorization: Bearer \<token>
- Accept: */*
{ "options":{
"send_email": 0
},
"header": {
"account_id": 14540,
"document_type_id": "82",
"received_issued_flag": 0,
"issue_date": "2025-01-14",
"issuer_tax_id_code": "860517022-2",
"issuer_tax_id_type": "CO-NIT",
"issuer_legal_name": "<string>",
"issuer_address": "<string>",
"issuer_district": "<string>",
"issuer_city": "<string>",
"issuer_country_id": "66",
"issuer_phone": "<string>",
"issuer_activity": "<string>",
"receiver_tax_id_code": "860517022-2",
"receiver_tax_id_type": "CO-NIT",
"receiver_legal_name": "ESCUELA KEMPER URGATE",
"receiver_email": "[email protected]",
"receiver_address": "<string>",
"receiver_county_id": "496",
"receiver_country_id": "66",
"receiver_phone": "<string>",
"receiver_activity": "<string>",
"payment_conditions": "0",
"currency_id": 28
},
"details": [
{
"quantity": 1,
"line_description": "Prueba Koywe",
"unit_measure": "UN",
"unit_price": 1500,
"long_description": "Esta es una linea de prueba",
"modifier_amount": -100,
"total_taxes": 266,
"modifier_percentage": 0,
"total_amount_line": 1666,
"taxes": [
{
"tax_type_id": "388",
"tax_percentage": 19,
"tax_amount": 266
}
]
}
],
"totals": {
"net_amount": 1400,
"taxes_amount": 266,
"total_amount": 1666
}
}
Factura con código de pago reportado
Especifica el código de pago reportado para la factura, según los códigos de pago de la DIAN de Colombia. Este campo identifica cómo se realizó o registró el pago de la factura.
Si no se envía este campo, su valor predeterminado será "efectivo".
Si tiene dudas sobre qué código de pago reportado usar, consulte la tabla de códigos reported_payment_code.
- Endpoint: https://api-billing.koywe.com/V1/documents
- Método: POST
- Encabezados requeridos:
- Content-Type: application/json
- Authorization: Bearer \<token>
- Accept: */*
{
"header": {
"account_id": 14540,
"document_type_id": "82",
"received_issued_flag": 0,
"issue_date": "2025-01-14",
"issuer_tax_id_code": "860517022-2",
"issuer_tax_id_type": "CO-NIT",
"issuer_legal_name": "<string>",
"issuer_address": "<string>",
"issuer_district": "<string>",
"issuer_city": "<string>",
"issuer_country_id": "66",
"issuer_phone": "<string>",
"issuer_activity": "<string>",
"receiver_tax_id_code": "860517022-2",
"receiver_tax_id_type": "CO-NIT",
"receiver_legal_name": "ESCUELA KEMPER URGATE",
"receiver_address": "<string>",
"receiver_county_id": "496",
"receiver_country_id": "66",
"receiver_phone": "<string>",
"receiver_activity": "<string>",
"payment_conditions": "0",
"currency_id": 28,
"additional":{
"co_header":{
"reported_payment_code": 10
}
}
},
"details": [
{
"quantity": 1,
"line_description": "Prueba Koywe",
"unit_measure": "UN",
"unit_price": 1500,
"long_description": "Esta es una linea de prueba",
"modifier_amount": -100,
"total_taxes": 266,
"modifier_percentage": 0,
"total_amount_line": 1666,
"taxes": [
{
"tax_type_id": "388",
"tax_percentage": 19,
"tax_amount": 266
}
]
}
],
"totals": {
"net_amount": 1400,
"taxes_amount": 266,
"total_amount": 1666
}
}
Factura con receptor extranjero
En Colombia, la misma factura utilizada para ventas nacionales también se usa para clientes extranjeros; debe usar el endpoint /documents con los parámetros adecuados.
- Endpoint: https://api-billing.koywe.com/V1/documents
- Método: POST
- Encabezados requeridos:
- Content-Type: application/json
- Authorization: Bearer \<token>
- Accept: */*
{
"header": {
"account_id": 14540,
"document_type_id": "82",
"received_issued_flag": 0,
"issue_date": "2025-01-14",
"issuer_tax_id_code": "860517022-2",
"issuer_tax_id_type": "CO-NIT",
"issuer_legal_name": "<string>",
"issuer_address": "<string>",
"issuer_district": "<string>",
"issuer_city": "<string>",
"issuer_country_id": "66",
"issuer_phone": "<string>",
"issuer_activity": "<string>",
"receiver_tax_id_code": "872055616",
"receiver_tax_id_type": "CO-NOP",
"receiver_legal_name": "ESCUELA KEMPER URGATE",
"receiver_address": "Street #4564, zip 94114, San Francisco,",
"receiver_country_id": "89",
"receiver_phone": "<string>",
"receiver_activity": "<string>",
"payment_conditions": "0",
"currency_id": 28
},
"details": [
{
"quantity": 1,
"line_description": "Prueba Koywe",
"unit_measure": "UN",
"unit_price": 1500,
"long_description": "Esta es una linea de prueba",
"modifier_amount": -100,
"total_taxes": 266,
"modifier_percentage": 0,
"total_amount_line": 1666,
"taxes": [
{
"tax_type_id": "388",
"tax_percentage": 19,
"tax_amount": 266
}
]
}
],
"totals": {
"net_amount": 1400,
"taxes_amount": 266,
"total_amount": 1666
}
}
Factura con impuestos y retenciones
Factura que incluye los impuestos aplicables (como el IVA) y los montos retenidos por el comprador (como la retención de IVA), que no se pagan al vendedor sino que se reportan a la autoridad tributaria.
- Endpoint: https://api-billing.koywe.com/V1/documents
- Método: POST
- Encabezados requeridos:
- Content-Type: application/json
- Authorization: Bearer \<token>
- Accept: */*
{
"header": {
"account_id": 14540,
"document_type_id": "82",
"received_issued_flag": 0,
"issue_date": "2025-01-14",
"issuer_tax_id_code": "860517022-2",
"issuer_tax_id_type": "CO-NIT",
"issuer_legal_name": "<string>",
"issuer_address": "<string>",
"issuer_district": "<string>",
"issuer_city": "<string>",
"issuer_country_id": "66",
"issuer_phone": "<string>",
"issuer_activity": "<string>",
"receiver_tax_id_code": "860517022-2",
"receiver_tax_id_type": "CO-NIT",
"receiver_legal_name": "ESCUELA KEMPER URGATE",
"receiver_address": "<string>",
"receiver_county_id": "496",
"receiver_country_id": "66",
"receiver_phone": "<string>",
"receiver_activity": "<string>",
"payment_conditions": "0",
"currency_id": 28
},
"details": [
{
"quantity": 1,
"line_description": "Prueba Koywe",
"unit_measure": "UN",
"unit_price": 1000000,
"long_description": "Esta es una linea de prueba",
"total_taxes": 161500,
"modifier_percentage": 0,
"total_amount_line": 1161500,
"taxes": [
{
"tax_type_id": 388,
"tax_percentage": 19,
"tax_amount": 190000
},
{
"tax_type_id": 397,
"tax_percentage": -2.85,
"tax_amount": -28500
}
]
}
],
"totals": {
"net_amount": 1000000,
"taxes_amount": 161500,
"total_amount": 1161500
}
}
Nota de crédito con referencia a reference_number
Para crear una nueva nota de crédito colombiana, debe usar el endpoint /documents con los parámetros adecuados.
Use reference_number (document_number) para referenciar el documento que está anulando.
- Endpoint: https://api-billing.koywe.com/V1/documents
- Método: POST
- Encabezados requeridos:
- Content-Type: application/json
- Authorization: Bearer \<token>
- Accept: */*
{
"header": {
"account_id": 14540,
"document_type_id": "83",
"received_issued_flag": 0,
"issue_date": "2025-01-14",
"issuer_tax_id_code": "860517022-2",
"issuer_tax_id_type": "CO-NIT",
"issuer_legal_name": "<string>",
"issuer_address": "<string>",
"issuer_district": "<string>",
"issuer_city": "<string>",
"issuer_country_id": "66",
"issuer_phone": "<string>",
"issuer_activity": "<string>",
"receiver_tax_id_code": "860517022-2",
"receiver_tax_id_type": "CO-NIT",
"receiver_legal_name": "ESCUELA KEMPER URGATE",
"receiver_address": "<string>",
"receiver_county_id": "496",
"receiver_country_id": "66",
"receiver_phone": "<string>",
"receiver_activity": "<string>",
"payment_conditions": "0",
"currency_id": 28
},
"details": [
{
"quantity": 1,
"line_description": "Prueba Koywe",
"unit_measure": "UN",
"unit_price": 1500,
"long_description": "Esta es una linea de prueba",
"modifier_amount": -100,
"total_taxes": 266,
"modifier_percentage": 0,
"total_amount_line": 1666,
"taxes": [
{
"tax_type_id": "388",
"tax_percentage": 19,
"tax_amount": 266
}
]
}
],
"references": [
{
"document_type_id": "82",
"reference_number": "SETT1040108",
"reference_code": 1,
"description": "Anulacion solicitada por el emisor",
"reference_date": "2025-01-14"
}
],
"totals": {
"net_amount": 1400,
"taxes_amount": 266,
"total_amount": 1666
}
}
Nota de crédito con referencia a reference_document_id
Para crear una nueva nota de crédito colombiana, debe usar el endpoint /documents con los parámetros adecuados.
Use reference_document_id (document_id) para referenciar el documento que está anulando.
- Endpoint: https://api-billing.koywe.com/V1/documents
- Método: POST
- Encabezados requeridos:
- Content-Type: application/json
- Authorization: Bearer \<token>
- Accept: */*
{
"header": {
"account_id": 14540,
"document_type_id": "83",
"received_issued_flag": 0,
"issue_date": "2025-01-14",
"issuer_tax_id_code": "860517022-2",
"issuer_tax_id_type": "CO-NIT",
"issuer_legal_name": "<string>",
"issuer_address": "<string>",
"issuer_district": "<string>",
"issuer_city": "<string>",
"issuer_country_id": "66",
"issuer_phone": "<string>",
"issuer_activity": "<string>",
"receiver_tax_id_code": "860517022-2",
"receiver_tax_id_type": "CO-NIT",
"receiver_legal_name": "ESCUELA KEMPER URGATE",
"receiver_address": "<string>",
"receiver_county_id": "496",
"receiver_country_id": "66",
"receiver_phone": "<string>",
"receiver_activity": "<string>",
"payment_conditions": "0",
"currency_id": 28
},
"details": [
{
"quantity": 1,
"line_description": "Prueba Koywe",
"unit_measure": "UN",
"unit_price": 1500,
"long_description": "Esta es una linea de prueba",
"modifier_amount": -100,
"total_taxes": 266,
"modifier_percentage": 0,
"total_amount_line": 1666,
"taxes": [
{
"tax_type_id": "388",
"tax_percentage": 19,
"tax_amount": 266
}
]
}
],
"references": [
{
"document_type_id": "82",
"reference_document_id": 1548,
"reference_code": 1,
"description": "Anulacion solicitada por el emisor",
"reference_date": "2025-01-14"
}
],
"totals": {
"net_amount": 1400,
"taxes_amount": 266,
"total_amount": 1666
}
}
Nota de débito con referencia a reference_number
Para crear una nueva nota de débito colombiana, debe usar el endpoint /documents con los parámetros adecuados.
Use reference_number (document_number) para referenciar el documento que está modificando.
- Endpoint: https://api-billing.koywe.com/V1/documents
- Método: POST
- Encabezados requeridos:
- Content-Type: application/json
- Authorization: Bearer \<token>
- Accept: */*
{
"header": {
"account_id": 14540,
"document_type_id": "84",
"received_issued_flag": 0,
"issue_date": "2025-01-14",
"issuer_tax_id_code": "860517022-2",
"issuer_tax_id_type": "CO-NIT",
"issuer_legal_name": "<string>",
"issuer_address": "<string>",
"issuer_district": "<string>",
"issuer_city": "<string>",
"issuer_country_id": "66",
"issuer_phone": "<string>",
"issuer_activity": "<string>",
"receiver_tax_id_code": "860517022-2",
"receiver_tax_id_type": "CO-NIT",
"receiver_legal_name": "ESCUELA KEMPER URGATE",
"receiver_address": "<string>",
"receiver_county_id": "496",
"receiver_country_id": "66",
"receiver_phone": "<string>",
"receiver_activity": "<string>",
"payment_conditions": "0",
"currency_id": 28
},
"details": [
{
"quantity": 1,
"line_description": "Prueba Koywe",
"unit_measure": "UN",
"unit_price": 1500,
"long_description": "Esta es una linea de prueba",
"modifier_amount": -100,
"total_taxes": 266,
"modifier_percentage": 0,
"total_amount_line": 1666,
"taxes": [
{
"tax_type_id": "388",
"tax_percentage": 19,
"tax_amount": 266
}
]
}
],
"references": [
{
"document_type_id": "82",
"reference_number": "SETT1040108",
"reference_code": 3,
"description": "Cambio de valor",
"reference_date": "2025-01-14"
}
],
"totals": {
"net_amount": 1400,
"taxes_amount": 266,
"total_amount": 1666
}
}
Nota de débito con referencia a reference_document_id
Para crear una nueva nota de débito colombiana, debe usar el endpoint /documents con los parámetros adecuados.
Use reference_document_id (document_id) para referenciar el documento que está modificando.
- Endpoint: https://api-billing.koywe.com/V1/documents
- Método: POST
- Encabezados requeridos:
- Content-Type: application/json
- Authorization: Bearer \<token>
- Accept: */*
{
"header": {
"account_id": 14540,
"document_type_id": "84",
"received_issued_flag": 0,
"issue_date": "2025-01-14",
"issuer_tax_id_code": "860517022-2",
"issuer_tax_id_type": "CO-NIT",
"issuer_legal_name": "<string>",
"issuer_address": "<string>",
"issuer_district": "<string>",
"issuer_city": "<string>",
"issuer_country_id": "66",
"issuer_phone": "<string>",
"issuer_activity": "<string>",
"receiver_tax_id_code": "860517022-2",
"receiver_tax_id_type": "CO-NIT",
"receiver_legal_name": "ESCUELA KEMPER URGATE",
"receiver_address": "<string>",
"receiver_county_id": "496",
"receiver_country_id": "66",
"receiver_phone": "<string>",
"receiver_activity": "<string>",
"payment_conditions": "0",
"currency_id": 28
},
"details": [
{
"quantity": 1,
"line_description": "Prueba Koywe",
"unit_measure": "UN",
"unit_price": 1500,
"long_description": "Esta es una linea de prueba",
"modifier_amount": -100,
"total_taxes": 266,
"modifier_percentage": 0,
"total_amount_line": 1666,
"taxes": [
{
"tax_type_id": "388",
"tax_percentage": 19,
"tax_amount": 266
}
]
}
],
"references": [
{
"document_type_id": "82",
"reference_document_id": 1548,
"reference_code": 3,
"description": "Cambio de valor",
"reference_date": "2025-01-14"
}
],
"totals": {
"net_amount": 1400,
"taxes_amount": 266,
"total_amount": 1666
}
}
Documento equivalente POS
Nota: POS solo generará XML; no se generará PDF en el entorno de prueba ni en producción. Puede usar los datos para generar su propio formato de documento.
- Endpoint: https://api-billing.koywe.com/V1/documents
- Método: POST
- Encabezados requeridos:
- Content-Type: application/json
- Authorization: Bearer \<token>
- Accept: */*
{
"header": {
"account_id": 14540,
"document_type_id": "87",
"received_issued_flag": 0,
"issue_date": "2025-01-31",
"issuer_tax_id_code": "860517022-2",
"issuer_tax_id_type": "CO-NIT",
"issuer_legal_name": "<string>",
"issuer_address": "<string>",
"issuer_district": "<string>",
"issuer_city": "<string>",
"issuer_country_id": "66",
"issuer_phone": "<string>",
"issuer_activity": "<string>",
"receiver_tax_id_code": "860517022-2",
"receiver_tax_id_type": "CO-NIT",
"receiver_legal_name": "ESCUELA KEMPER URGATE",
"receiver_address": "<string>",
"receiver_county_id": "496",
"receiver_country_id": "66",
"receiver_phone": "<string>",
"receiver_activity": "<string>",
"payment_conditions": "0",
"currency_id": 28,
"postal_code": "11001",
"receiver_email": "[email protected]"
},
"details": [
{
"quantity": 1,
"line_description": "Prueba Koywe",
"unit_measure": "UN",
"unit_price": 1500,
"long_description": "Esta es una linea de prueba",
"modifier_amount": -100,
"total_taxes": 266,
"modifier_percentage": 0,
"total_amount_line": 1666,
"taxes": [
{
"tax_type_id": "388",
"tax_percentage": 19,
"tax_amount": 266
}
]
}
],
"totals": {
"net_amount": 1400,
"taxes_amount": 266,
"total_amount": 1666
}
}
Nota de crédito para documento equivalente POS
Nota: POS solo generará XML; no se generará PDF en el entorno de prueba ni en producción. Puede usar los datos para generar su propio formato de documento.
- Endpoint: https://api-billing.koywe.com/V1/documents
- Método: POST
- Encabezados requeridos:
- Content-Type: application/json
- Authorization: Bearer \<token>
- Accept: */*
{
"header": {
"account_id": 14540,
"document_type_id": "88",
"received_issued_flag": 0,
"issue_date": "2025-01-31",
"issuer_tax_id_code": "860517022-2",
"issuer_tax_id_type": "CO-NIT",
"issuer_legal_name": "<string>",
"issuer_address": "<string>",
"issuer_district": "<string>",
"issuer_city": "<string>",
"issuer_country_id": "66",
"issuer_phone": "<string>",
"issuer_activity": "<string>",
"receiver_tax_id_code": "860517022-2",
"receiver_tax_id_type": "CO-NIT",
"receiver_legal_name": "ESCUELA KEMPER URGATE",
"receiver_address": "<string>",
"receiver_county_id": "496",
"receiver_country_id": "66",
"receiver_phone": "<string>",
"receiver_activity": "<string>",
"payment_conditions": "0",
"currency_id": 28,
"postal_code": "11001",
"receiver_email": "[email protected]"
},
"details": [
{
"quantity": 1,
"line_description": "Prueba Koywe",
"unit_measure": "UN",
"unit_price": 1500,
"long_description": "Esta es una linea de prueba",
"modifier_amount": -100,
"total_taxes": 266,
"modifier_percentage": 0,
"total_amount_line": 1666,
"taxes": [
{
"tax_type_id": "388",
"tax_percentage": 19,
"tax_amount": 266
}
]
}
],
"references": [
{
"document_type_id": 87,
"reference_number": "EPOS217",
"reference_code": 1,
"description": "Anulacion solicitada por el emisor",
"reference_date": "2025-01-31"
}
],
"totals": {
"net_amount": 1400,
"taxes_amount": 266,
"total_amount": 1666
}
}
Documento soporte
Nota: La DIAN no permite emitir documentos soporte en su entorno de pruebas, por lo que al emitir con credenciales de sandbox no se devolverá XML ni PDF.
Nota de crédito a documento soporte
Nota: La DIAN no permite emitir documentos soporte en su entorno de pruebas, por lo que al emitir con credenciales de sandbox no se devolverá XML ni PDF.
Estado de respuesta en el resultado de la API REST
| status | description |
|---|---|
| 0 | El borrador fue creado exitosamente, firmado y enviado al SII exitosamente. |
| 1 | Hay errores en la entrada, por lo que el borrador no fue generado ni enviado al SII. Los detalles del error estarán en error_message. |
| 2 | El borrador fue creado exitosamente; sin embargo, hay otros problemas (por ejemplo, falta de folios) que impidieron que se enviara al SII. Los detalles del error estarán en error_message. |
{
"document_id": 377,
"header": {
"account_id": 14540,
"document_type_id": 82,
"document_type_taxbureau": "01",
"document_number": 1040447,
"received_issued_flag": 1,
"taxbureau_validation_status": null,
"issue_date": "2025-04-15",
"issuer_tax_id_code": "860517022-2",
"issuer_tax_id_type": "CO-NIT",
"issuer_legal_name": "Demo Colombia",
"issuer_address": "",
"issuer_district": "",
"issuer_city": "",
"issuer_country_id": 253,
"issuer_phone": "442020550",
"issuer_activity": "",
"receiver_tax_id_code": "1097491385-1",
"receiver_tax_id_type": "CO-NIT",
"receiver_legal_name": "ESCUELAa KEMPER URGATE",
"receiver_address": "",
"receiver_district": "",
"receiver_city": "",
"receiver_country_id": 66,
"receiver_phone": "<string>",
"receiver_activity": "<string>",
"document_status": 1,
"payment_conditions": "0",
"currency_id": 28
},
"details": [ {
"quantity": "1.000000",
"line_description": "Prueba Koywe",
"long_description": "Esta es una linea de prueba",
"unit_measure": "UN",
"unit_price": "3660.000000",
"vat_status": "0"
}],
"references": null,
"global_modifiers": null,
"totals": {
"net_amount": 3660,
"taxes_amount": 695.4,
"total_amount": "4355.40"
},
"electronic_document": {
"document_xml": "PD94bWwgdmVyc2lvbj0iMS4wIiB...",
"document_pdf": "JVBERi0xLjMKMyAwIG9iago8PC8..."
},
"payment_link": null,
"result": {
"status": 0,
"error_message": ""
},
"_links": {"self": {"href": "https://api-billing.koywe.com/V1/documents"}}
}
Referencia de API POST /documents
Documentación detallada del endpoint: /english/billing/api-reference/billing-api/📝-documents/create-a-new-document