ES | EN

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.

{
  "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.

{ "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.

{
  "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.

{
  "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.

{
  "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.

{
  "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.

{
  "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.

{
  "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.

{
  "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.

{
  "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.

{
  "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