Ejemplos por país

➕ Crear documentos

Colección de Postman

Para ayudarle con su integración, descargue nuestra colección de Postman aquí: https://github.com/koyweforest/api-billing-postman

Para facilitar las pruebas, puede usar la siguiente información al emitir documentos

account_id	RUC	legal_name	activity	postalcode
16268	20610383727

Factura (Factura electrónica)

Para crear una nueva factura peruana, debe usar el endpoint /documents con los parámetros adecuados.

• Endpoint: https://api-billing.koywe.com/V1/documents
• Método: POST
• Cabeceras requeridas:
  • Content-Type: application/json
  • Authorization: Bearer \<token>
  • Accept: */*

{
   "header":{
      "account_id":16268,
      "document_type_id":"96",
      "document_sequence_code":"F001",
      "received_issued_flag":0,
      "issue_date":"2025-02-03",
      "issuer_tax_id_code":"20610383727",
      "issuer_tax_id_type":"PE-RUC",
      "issuer_legal_name":"<string>",
      "issuer_address":"<string>",
      "issuer_district":"<string>",
      "issuer_city":"<string>",
      "issuer_department":"<string>",
      "issuer_country_id":"83",
      "issuer_phone":"<string>",
      "issuer_activity":"<string>",
      "issuer_postalcode":"12345456",
      "receiver_tax_id_code":"20473731828",
      "receiver_tax_id_type":"PE-RUC",
      "receiver_legal_name":"ESCUELA KEMPER URGATES",
      "receiver_address":"<string>",
      "receiver_district":"<string>",
      "receiver_city":"<string>",
      "receiver_department":"<string>",
      "receiver_country_id":"83",
      "receiver_phone":"<string>",
      "receiver_activity":"<string>",
      "receiver_postalcode":"12343456",
      "payment_conditions":"0",
      "currency_id":7,
      "additional":{
         "pe_header":{
            "signature_id":"ASDFG",
            "operation_type":"0101"
         }
      }
   },
   "details":[
      {
         "quantity":1,
         "line_description":"Prueba Koywe",
         "unit_measure":"NIU",
         "unit_price":1000,
         "long_description":"Test descripcion",
         "modifier_amount":0,
         "total_taxes":180,
         "modifier_percentage":0,
         "total_amount_line":1180,
         "sku":"3245",
         "taxes":[
            {
               "tax_type_id":"413",
               "tax_percentage":18,
               "tax_amount":180
            }
         ]
      }
   ],
   "totals":{
      "net_amount":1000,
      "taxes_amount":180,
      "total_amount":1180
   }
}

Factura con PDF térmico 80mm (Factura electrónica con pdf térmico 80mm)

Para crear una nueva factura peruana, debe usar el endpoint /documents con los parámetros adecuados.

Soporte para térmico 80mm en document_type_id 96, 97 y 100; consulte la tabla de códigos.

• Endpoint: https://api-billing.koywe.com/V1/documents
• Método: POST
• Cabeceras requeridas:
  • Content-Type: application/json
  • Authorization: Bearer \<token>
  • Accept: */*

{
  "options": {
    "template_id": 5000
  },
   "header":{
      "account_id":16268,
      "document_type_id":"96",
      "received_issued_flag":0,
      "issue_date":"2025-02-03",
      "issuer_tax_id_code":"20610383727",
      "issuer_tax_id_type":"PE-RUC",
      "issuer_legal_name":"<string>",
      "issuer_address":"<string>",
      "issuer_district":"<string>",
      "issuer_city":"<string>",
      "issuer_department":"<string>",
      "issuer_country_id":"83",
      "issuer_phone":"<string>",
      "issuer_activity":"<string>",
      "issuer_postalcode":"12345456",
      "receiver_tax_id_code":"20473731828",
      "receiver_tax_id_type":"PE-RUC",
      "receiver_legal_name":"ESCUELA KEMPER URGATES",
      "receiver_address":"<string>",
      "receiver_district":"<string>",
      "receiver_city":"<string>",
      "receiver_department":"<string>",
      "receiver_country_id":"83",
      "receiver_phone":"<string>",
      "receiver_activity":"<string>",
      "receiver_postalcode":"12343456",
      "payment_conditions":"0",
      "currency_id":7,
      "additional":{
         "pe_header":{
            "signature_id":"ASDFG",
            "operation_type":"0101"
         }
      }
   },
   "details":[
      {
         "quantity":1,
         "line_description":"Prueba Koywe",
         "unit_measure":"NIU",
         "unit_price":1000,
         "long_description":"Test descripcion",
         "modifier_amount":0,
         "total_taxes":180,
         "modifier_percentage":0,
         "total_amount_line":1180,
         "sku":"3245",
         "taxes":[
            {
               "tax_type_id":"413",
               "tax_percentage":18,
               "tax_amount":180
            }
         ]
      }
   ],
   "totals":{
      "net_amount":1000,
      "taxes_amount":180,
      "total_amount":1180
   }
}

Factura de exportación (Factura electrónica para casos de exportación)

Para crear una nueva factura de exportación peruana, debe usar el endpoint /documents con los parámetros adecuados. Tenga en cuenta que, a diferencia de otros países, el tipo de documento es el mismo que las facturas regulares, ya que es solo un caso especial de la factura electrónica estándar.

• Endpoint: https://api-billing.koywe.com/V1/documents
• Método: POST
• Cabeceras requeridas:
  • Content-Type: application/json
  • Authorization: Bearer \<token>
  • Accept: */*

{
   "header":{
      "account_id":179,
      "document_type_id":"96",
      "document_sequence_code":"F001",
      "received_issued_flag":0,
      "issue_date":"2025-04-21",
      "issuer_tax_id_code":"20610383727",
      "issuer_tax_id_type":"PE-RUC",
      "issuer_legal_name":"<string>",
      "issuer_address":"<string>",
      "issuer_district":"<string>",
      "issuer_city":"<string>",
      "issuer_department":"<string>",
      "issuer_country_id":"83",
      "issuer_phone":"<string>",
      "issuer_activity":"<string>",
      "issuer_postalcode":"12345456",
      "receiver_tax_id_code":"851855616",
      "receiver_tax_id_type":"US-EIN",
      "receiver_legal_name":"ESCUELA KEMPER URGATES",
      "receiver_address":"<string>",
      "receiver_district":"<string>",
      "receiver_city":"<string>",
      "receiver_department":"<string>",
      "receiver_country_id":"83",
      "receiver_phone":"<string>",
      "receiver_activity":"<string>",
      "receiver_postalcode":"12343456",
      "payment_conditions":"0",
      "currency_id":7,
      "additional":{
         "pe_header":{
            "signature_id":"ASDFG",
            "operation_type":"0200"
         }
      }
   },
   "details":[
      {
         "quantity":1,
         "line_description":"Prueba ROW",
         "unit_measure":"NIU",
         "unit_price":1000,
         "long_description":"Test descripcion",
         "modifier_amount":0,
         "total_taxes":0,
         "modifier_percentage":0,
         "total_amount_line":1000,
         "sku":"3245",
         "taxes":[
            {
               "tax_type_id":"425",
               "tax_percentage":0,
               "tax_amount":0
            }
         ]
      }
   ],
   "totals":{
      "net_amount":1000,
      "taxes_amount":0,
      "total_amount":1000
   }
}

Boleta de venta (Boleta electrónica)

Para crear una nueva boleta peruana, debe usar el endpoint /documents con los parámetros adecuados. Puede emitir boletas a receptores identificados con DNI usando el campo "receiver_tax_id_type" con el valor "PE-DNI".

IMPORTANTE: Al emitir boletas, DEBE usar la fecha de hoy como issue_date. De lo contrario, recibirá el "Error 1079: Solo puede enviar el comprobante en un resumen diario", que indica que no está permitido emitir boletas individuales para fechas anteriores.

• Endpoint: https://api-billing.koywe.com/V1/documents
• Método: POST
• Cabeceras requeridas:
  • Content-Type: application/json
  • Authorization: Bearer \<token>
  • Accept: */*

{
   "header":{
      "account_id":16268,
      "document_type_id":"97",
      "document_sequence_code":"B001",
      "received_issued_flag":0,
      "issue_date":"2025-02-03",
      "issuer_tax_id_code":"20610383727",
      "issuer_tax_id_type":"PE-RUC",
      "issuer_legal_name":"<string>",
      "issuer_address":"<string>",
      "issuer_district":"<string>",
      "issuer_city":"<string>",
      "issuer_department":"<string>",
      "issuer_country_id":"80",
      "issuer_phone":"<string>",
      "issuer_activity":"<string>",
      "issuer_postalcode":"12345456",
      "receiver_tax_id_code":"20473731828",
      "receiver_tax_id_type":"PE-RUC",
      "receiver_legal_name":"ESCUELA KEMPER URGATES",
      "receiver_address":"<string>",
      "receiver_district":"<string>",
      "receiver_city":"<string>",
      "receiver_department":"<string>",
      "receiver_country_id":"80",
      "receiver_phone":"<string>",
      "receiver_activity":"<string>",
      "receiver_postalcode":"12343456",
      "payment_conditions":"0",
      "currency_id":7,
      "additional":{
         "pe_header":{
            "signature_id":"ASDFG",
            "operation_type":"0101"
         }
      }
   },
   "details":[
      {
         "quantity":1,
         "line_description":"Prueba Koywe",
         "unit_measure":"NIU",
         "unit_price":1000,
         "long_description":"Test descripcion",
         "modifier_amount":0,
         "total_taxes":180,
         "modifier_percentage":0,
         "total_amount_line":1180,
         "sku":"3245",
         "taxes":[
            {
               "tax_type_id":"413",
               "tax_percentage":18,
               "tax_amount":180
            }
         ]
      }
   ],
   "totals":{
      "net_amount":1000,
      "taxes_amount":180,
      "total_amount":1180
   }
}

Boleta menor a 700 soles (Boleta electrónica)

Si el monto total de la boleta es inferior a 700 soles, no es necesario incluir la información del cliente.

Para crear una nueva boleta peruana, debe usar el endpoint /documents con los parámetros adecuados. Puede emitir boletas a receptores identificados con DNI usando el campo "receiver_tax_id_type" con el valor "PE-DNI".

IMPORTANTE: Al emitir boletas, DEBE usar la fecha de hoy como issue_date. De lo contrario, recibirá el "Error 1079: Solo puede enviar el comprobante en un resumen diario", que indica que no está permitido emitir boletas individuales para fechas anteriores.

• Endpoint: https://api-billing.koywe.com/V1/documents
• Método: POST
• Cabeceras requeridas:
  • Content-Type: application/json
  • Authorization: Bearer \<token>
  • Accept: */*

{
   "header":{
      "account_id":16268,
      "document_type_id":"97",
      "document_sequence_code":"B001",
      "received_issued_flag":0,
      "issue_date":"2025-07-21",
      "issuer_tax_id_code":"20610383727",
      "issuer_tax_id_type":"PE-RUC",
      "issuer_legal_name":"<string>",
      "issuer_address":"<string>",
      "issuer_district":"<string>",
      "issuer_city":"<string>",
      "issuer_department":"<string>",
      "issuer_country_id":"80",
      "issuer_phone":"<string>",
      "issuer_activity":"<string>",
      "issuer_postalcode":"12345456",
      "payment_conditions":"0",
      "currency_id":7,
      "additional":{
         "pe_header":{
            "signature_id":"ASDFG",
            "operation_type":"0101"
         }
      }
   },
   "details":[
      {
         "quantity":1,
         "line_description":"Prueba ROW",
         "unit_measure":"NIU",
         "unit_price":500,
         "long_description":"Test descripcion",
         "modifier_amount":0,
         "total_taxes":90,
         "modifier_percentage":0,
         "total_amount_line":590,
         "sku":"3245",
         "taxes":[
            {
               "tax_type_id":"412",
               "tax_percentage":18,
               "tax_amount":90
            }
         ]
      }
   ],
   "totals":{
      "net_amount":500,
      "taxes_amount":90,
      "total_amount":590
   }
}

Boleta emitida a cliente extranjero (Boleta electrónica nominativa con receptor extranjero)

Para crear una nueva boleta peruana, debe usar el endpoint /documents con los parámetros adecuados. Puede emitir boletas tanto a receptores locales como extranjeros configurando el campo receiver_tax_id_type según corresponda. Por ejemplo, use "PE-DNI" para cédulas de identidad peruanas, o "US-EIN" para receptores identificados con un EIN de EE.UU.

IMPORTANTE: Al emitir boletas, DEBE usar la fecha de hoy como issue_date. De lo contrario, recibirá el "Error 1079: Solo puede enviar el comprobante en un resumen diario", que indica que no está permitido emitir boletas individuales para fechas anteriores.

• Endpoint: https://api-billing.koywe.com/V1/documents
• Método: POST
• Cabeceras requeridas:
  • Content-Type: application/json
  • Authorization: Bearer \<token>
  • Accept: */*

{
    "header": {
        "account_id": 16268,
        "document_type_id": "97",
        "document_sequence_code":"B001",
        "received_issued_flag": 1,
        "issue_date": "2025-07-23",
        "issuer_tax_id_code": "20610383727",
        "issuer_tax_id_type": "PE-RUC",
        "issuer_legal_name": "KOYWE PERU SAC",
        "issuer_address": "AV. REPUBLICA DE PANAMA NRO. 3535 INT. 403",
        "issuer_district": "SAN ISIDRO",
        "issuer_department": "LIMA",
        "issuer_city": "LIMA",
        "issuer_phone": "+51949944464",
        "issuer_activity": "OTROS TIPOS DE INTERMEDIACIoN MONETARIA",
        "issuer_postalcode": "15036",
        "issuer_country_id": "83",
        "receiver_tax_id_type": "US-EIN",
        "receiver_tax_id_code": "10752012",
        "receiver_legal_name": "Hapi Corp",
        "receiver_email": "[email protected]",
        "receiver_address": "2261 Market Street #4257",
        "receiver_district": "San Francisco ",
        "receiver_city": "San Francisco ",
        "receiver_activity": "Brokers de acciones",
        "receiver_country_id": "83",
        "receiver_department": "",
        "payment_conditions": "0",
        "currency_id": 7,
        "additional": {
            "pe_header": {
                "signature_id": "ASDFG",
                "operation_type": "0101"
            }
        }
    },
    "details": [
        {
            "quantity": 1,
            "unit_price": 400,
            "unit_measure": "NIU",
            "line_description": "Servicio de obtencion de bienes digitales por su cuenta y orden. Orden ID c4250e3d-95db-4da3-a01f-14e6b3b0b239. Monto Total: 18.00 PEN",
            "long_description": "Servicio de obtencion de bienes digitales por su cuenta y orden. Orden ID c4250e3d-95db-4da3-a01f-14e6b3b0b239. Monto Total: 18.00 PEN",
            "taxes": [
                {
                    "tax_type_id": "413",
                    "tax_percentage": 18,
                    "tax_amount": 72
                }
            ]
        }
    ],
    "totals": {
        "net_amount": 400,
        "taxes_amount": 72,
        "total_amount": 472
    }
}

Nota de crédito para Factura con reference_number (Nota de crédito electrónica para Factura)

Para crear una nueva nota de crédito peruana, debe usar el endpoint /documents con los parámetros adecuados y agregar el campo reference_number que indica el número del documento original (como una factura) al que se refiere la nota de crédito.

• Endpoint: https://api-billing.koywe.com/V1/documents
• Método: POST
• Cabeceras requeridas:
• Content-Type: application/json
• Authorization: Bearer \<token>
• Accept: */*

{
   "header": {
      "account_id": 16268,
      "document_type_id": "98",
      "document_sequence_code":"FC01",
      "received_issued_flag": 0,
      "issue_date": "2025-01-27",
      "issuer_tax_id_code": "20610383727",
      "issuer_tax_id_type": "PE-RUC",
      "issuer_legal_name": "<string>",
      "issuer_address": "<string>",
      "issuer_district": "<string>",
      "issuer_city": "<string>",
      "issuer_department":"<string>",
      "issuer_country_id": "80",
      "issuer_phone": "<string>",
      "issuer_activity": "<string>",
      "issuer_postalcode":"12345456",
      "receiver_tax_id_code": "20473731828",
      "receiver_tax_id_type": "PE-RUC",
      "receiver_legal_name": "ESCUELA KEMPER URGATES",
      "receiver_address": "<string>",
      "receiver_district": "<string>",
      "receiver_city": "<string>",
      "receiver_department":"<string>",
      "receiver_country_id": "80",
      "receiver_phone": "<string>",
      "receiver_activity": "<string>",
      "receiver_postalcode":"12343456",
      "payment_conditions": "0",
      "currency_id": 7,
      "additional":{
         "pe_header":{
            "signature_id":"ASDFG",
            "operation_type":"0101"
         }
      }
   },
   "details": [
      {
         "quantity": 1,
         "line_description": "Prueba Koywe",
         "unit_measure": "NIU",
         "unit_price": 1000,
         "long_description": "Test descripcion",
         "modifier_amount": 0,
         "total_taxes": 180,
         "modifier_percentage": 0,
         "total_amount_line": 1180,
         "sku": "3245",
         "taxes": [
            {
               "tax_type_id": "413",
               "tax_percentage": 18,
               "tax_amount": 180
            }
         ]
      }
   ],
   "references": [
      {
         "document_type_id": "96",
         "reference_number": "F001-00000087",
         "reference_code": "01",
         "description": "Anulacion solicitada por el emisor",
         "reference_date": "2025-01-27"
      }
   ],
   "totals": {
      "net_amount": 1000,
      "taxes_amount": 180,
      "total_amount": 1180
   }
}

Nota de crédito para Factura con reference_document_id (Nota de crédito electrónica para Factura)

Para crear una nueva nota de crédito peruana, debe usar el endpoint /documents con los parámetros adecuados y agregar el campo reference_document_id que indica el ID del documento original (como una factura) al que se refiere la nota de crédito.

• Endpoint: https://api-billing.koywe.com/V1/documents
• Método: POST
• Cabeceras requeridas:
• Content-Type: application/json
• Authorization: Bearer \<token>
• Accept: */*

{
   "header": {
      "account_id": 16268,
      "document_type_id": "98",
      "received_issued_flag": 0,
      "document_sequence_code":"FC01",
      "issue_date": "2025-11-11",
      "issuer_tax_id_code": "20610383727",
      "issuer_tax_id_type": "PE-RUC",
      "issuer_legal_name": "<string>",
      "issuer_address": "<string>",
      "issuer_district": "<string>",
      "issuer_city": "<string>",
      "issuer_department":"<string>",
      "issuer_country_id": "80",
      "issuer_phone": "<string>",
      "issuer_activity": "<string>",
      "issuer_postalcode":"12345456",
      "receiver_tax_id_code": "20473731828",
      "receiver_tax_id_type": "PE-RUC",
      "receiver_legal_name": "ESCUELA KEMPER URGATES",
      "receiver_address": "<string>",
      "receiver_district": "<string>",
      "receiver_city": "<string>",
      "receiver_department":"<string>",
      "receiver_country_id": "80",
      "receiver_phone": "<string>",
      "receiver_activity": "<string>",
      "receiver_postalcode":"12343456",
      "payment_conditions": "0",
      "currency_id": 7,
      "additional":{
         "pe_header":{
            "signature_id":"ASDFG",
            "operation_type":"0101"
         }
      }
   },
   "details": [
      {
         "quantity": 1,
         "line_description": "Prueba Koywe",
         "unit_measure": "NIU",
         "unit_price": 1000,
         "long_description": "Test descripcion",
         "modifier_amount": 0,
         "total_taxes": 180,
         "modifier_percentage": 0,
         "total_amount_line": 1180,
         "sku": "3245",
         "taxes": [
            {
               "tax_type_id": "413",
               "tax_percentage": 18,
               "tax_amount": 180
            }
         ]
      }
   ],
   "references": [
      {
         "document_type_id": "96",
         "reference_document_id": "1587",
         "reference_code": "01",
         "description": "Anulacion solicitada por el emisor",
         "reference_date": "2025-11-11"
      }
   ],
   "totals": {
      "net_amount": 1000,
      "taxes_amount": 180,
      "total_amount": 1180
   }
}

Nota de crédito para Boleta con reference_number (Nota de crédito electrónica para Boleta)

Para crear una nueva nota de crédito peruana para una boleta, debe usar el endpoint /documents con los parámetros adecuados y agregar el campo reference_number que indica el número de la boleta original a la que se refiere la nota de crédito.

• Endpoint: https://api-billing.koywe.com/V1/documents
• Método: POST
• Cabeceras requeridas:
• Content-Type: application/json
• Authorization: Bearer \<token>
• Accept: */*

{
   "header": {
      "account_id": 16268,
      "document_type_id": "155",
      "document_sequence_code":"BC01",
      "received_issued_flag": 1,
      "issue_date": "2025-01-27",
      "issuer_tax_id_code": "20610383727",
      "issuer_tax_id_type": "PE-RUC",
      "issuer_legal_name": "<string>",
      "issuer_address": "<string>",
      "issuer_district": "<string>",
      "issuer_city": "<string>",
      "issuer_department":"<string>",
      "issuer_country_id": "83",
      "issuer_phone": "<string>",
      "issuer_activity": "<string>",
      "issuer_postalcode":"12345456",
      "receiver_tax_id_code": "20473731828",
      "receiver_tax_id_type": "PE-RUC",
      "receiver_legal_name": "ESCUELA KEMPER URGATES",
      "receiver_address": "<string>",
      "receiver_district": "<string>",
      "receiver_city": "<string>",
      "receiver_department":"<string>",
      "receiver_country_id": "83",
      "receiver_phone": "<string>",
      "receiver_activity": "<string>",
      "receiver_postalcode":"12343456",
      "payment_conditions": "0",
      "currency_id": 7,
      "additional":{
         "pe_header":{
            "signature_id":"ASDFG",
            "operation_type":"0101"
         }
      }
   },
   "details": [
      {
         "quantity": 1,
         "line_description": "Prueba Koywe",
         "unit_measure": "NIU",
         "unit_price": 1000,
         "long_description": "Test descripcion",
         "modifier_amount": 0,
         "total_taxes": 180,
         "modifier_percentage": 0,
         "total_amount_line": 1180,
         "sku": "3245",
         "taxes": [
            {
               "tax_type_id": "413",
               "tax_percentage": 18,
               "tax_amount": 180
            }
         ]
      }
   ],
   "references": [
      {
         "document_type_id": "97",
         "reference_number": "B001-00000087",
         "reference_code": "01",
         "description": "Anulacion solicitada por el emisor",
         "reference_date": "2025-01-27"
      }
   ],
   "totals": {
      "net_amount": 1000,
      "taxes_amount": 180,
      "total_amount": 1180
   }
}

Nota de crédito para Boleta con reference_document_id (Nota de crédito electrónica para Boleta)

Para crear una nueva nota de crédito peruana para una boleta, debe usar el endpoint /documents con los parámetros adecuados y agregar el campo reference_document_id que indica el ID de la boleta original a la que se refiere la nota de crédito.

• Endpoint: https://api-billing.koywe.com/V1/documents
• Método: POST
• Cabeceras requeridas:
• Content-Type: application/json
• Authorization: Bearer \<token>
• Accept: */*

{
   "header": {
      "account_id": 16268,
      "document_type_id": "155",
      "document_sequence_code":"BC01",
      "received_issued_flag": 1,
      "issue_date": "2025-01-27",
      "issuer_tax_id_code": "20610383727",
      "issuer_tax_id_type": "PE-RUC",
      "issuer_legal_name": "<string>",
      "issuer_address": "<string>",
      "issuer_district": "<string>",
      "issuer_city": "<string>",
      "issuer_department":"<string>",
      "issuer_country_id": "83",
      "issuer_phone": "<string>",
      "issuer_activity": "<string>",
      "issuer_postalcode":"12345456",
      "receiver_tax_id_code": "20473731828",
      "receiver_tax_id_type": "PE-RUC",
      "receiver_legal_name": "ESCUELA KEMPER URGATES",
      "receiver_address": "<string>",
      "receiver_district": "<string>",
      "receiver_city": "<string>",
      "receiver_department":"<string>",
      "receiver_country_id": "83",
      "receiver_phone": "<string>",
      "receiver_activity": "<string>",
      "receiver_postalcode":"12343456",
      "payment_conditions": "0",
      "currency_id": 7,
      "additional":{
         "pe_header":{
            "signature_id":"ASDFG",
            "operation_type":"0101"
         }
      }
   },
   "details": [
      {
         "quantity": 1,
         "line_description": "Prueba Koywe",
         "unit_measure": "NIU",
         "unit_price": 1000,
         "long_description": "Test descripcion",
         "modifier_amount": 0,
         "total_taxes": 180,
         "modifier_percentage": 0,
         "total_amount_line": 1180,
         "sku": "3245",
         "taxes": [
            {
               "tax_type_id": "413",
               "tax_percentage": 18,
               "tax_amount": 180
            }
         ]
      }
   ],
   "references": [
      {
         "document_type_id": "97",
         "reference_document_id": "190",
         "reference_code": "01",
         "description": "Anulacion solicitada por el emisor",
         "reference_date": "2025-01-27"
      }
   ],
   "totals": {
      "net_amount": 1000,
      "taxes_amount": 180,
      "total_amount": 1180
   }
}

Nota de débito con reference_number (Nota de débito electrónica)

Para crear una nueva nota de débito peruana, debe usar el endpoint /documents con los parámetros adecuados y agregar el campo reference_number que indica el número del documento original (como una factura o boleta) al que se refiere la nota de débito.

• Endpoint: https://api-billing.koywe.com/V1/documents
• Método: POST
• Cabeceras requeridas:
• Content-Type: application/json
• Authorization: Bearer \<token>
• Accept: */*

{
   "header":{
      "account_id":16268,
      "document_type_id":"99",
      "document_sequence_code":"FD01",
      "received_issued_flag":0,
      "issue_date":"2025-01-23",
      "issuer_tax_id_code":"20610383727",
      "issuer_tax_id_type":"PE-RUC",
      "issuer_legal_name":"<string>",
      "issuer_address":"<string>",
      "issuer_district":"<string>",
      "issuer_city":"<string>",
      "issuer_department":"<string>",
      "issuer_country_id":"80",
      "issuer_phone":"<string>",
      "issuer_activity":"<string>",
      "issuer_postalcode":"12345456",
      "receiver_tax_id_code":"20473731828",
      "receiver_tax_id_type":"PE-RUC",
      "receiver_legal_name":"ESCUELA KEMPER URGATES",
      "receiver_address":"<string>",
      "receiver_district":"<string>",
      "receiver_city":"<string>",
      "receiver_department":"<string>",
      "receiver_country_id":"80",
      "receiver_phone":"<string>",
      "receiver_activity":"<string>",
      "receiver_postalcode":"12343456",
      "payment_conditions":"0",
      "currency_id":7,
      "additional":{
         "pe_header":{
            "signature_id":"ASDFG",
            "operation_type":"0101"
         }
      }
   },
   "details":[
      {
         "quantity":1,
         "line_description":"Prueba Koywe",
         "unit_measure":"NIU",
         "unit_price":1000,
         "long_description":"Test descripcion",
         "modifier_amount":0,
         "total_taxes":180,
         "modifier_percentage":0,
         "total_amount_line":1180,
         "sku":"3245",
         "taxes":[
            {
               "tax_type_id":"413",
               "tax_percentage":18,
               "tax_amount":180
            }
         ]
      }
   ],
   "references": [
      {
         "document_type_id":"96",
         "reference_number":"F001-00000080",
         "reference_code":"03",
         "description":"Penalidad/otros conceptos",
         "reference_date":"2025-01-23"
      }
   ],
   "totals":{
      "net_amount":1000,
      "taxes_amount":180,
      "total_amount":1180
   }
}

Nota de débito con reference_document_id (Nota de débito electrónica)

Para crear una nueva nota de débito peruana, debe usar el endpoint /documents con los parámetros adecuados y agregar el campo reference_document_id que indica el ID del documento original (como una factura o boleta) al que se refiere la nota de débito.

• Endpoint: https://api-billing.koywe.com/V1/documents
• Método: POST
• Cabeceras requeridas:
• Content-Type: application/json
• Authorization: Bearer \<token>
• Accept: */*

{
   "header":{
      "account_id":16268,
      "document_type_id":"99",
      "document_sequence_code":"FD01",
      "received_issued_flag":0,
      "issue_date":"2025-01-23",
      "issuer_tax_id_code":"20610383727",
      "issuer_tax_id_type":"PE-RUC",
      "issuer_legal_name":"<string>",
      "issuer_address":"<string>",
      "issuer_district":"<string>",
      "issuer_city":"<string>",
      "issuer_department":"<string>",
      "issuer_country_id":"80",
      "issuer_phone":"<string>",
      "issuer_activity":"<string>",
      "issuer_postalcode":"12345456",
      "receiver_tax_id_code":"20473731828",
      "receiver_tax_id_type":"PE-RUC",
      "receiver_legal_name":"ESCUELA KEMPER URGATES",
      "receiver_address":"<string>",
      "receiver_district":"<string>",
      "receiver_city":"<string>",
      "receiver_department":"<string>",
      "receiver_country_id":"80",
      "receiver_phone":"<string>",
      "receiver_activity":"<string>",
      "receiver_postalcode":"12343456",
      "payment_conditions":"0",
      "currency_id":7,
      "additional":{
         "pe_header":{
            "signature_id":"ASDFG",
            "operation_type":"0101"
         }
      }
   },
   "details":[
      {
         "quantity":1,
         "line_description":"Prueba Koywe",
         "unit_measure":"NIU",
         "unit_price":1000,
         "long_description":"Test descripcion",
         "modifier_amount":0,
         "total_taxes":180,
         "modifier_percentage":0,
         "total_amount_line":1180,
         "sku":"3245",
         "taxes":[
            {
               "tax_type_id":"413",
               "tax_percentage":18,
               "tax_amount":180
            }
         ]
      }
   ],
   "references": [
      {
         "document_type_id":"96",
         "reference_document_id": "1587",
         "reference_code":"03",
         "description":"Penalidad/otros conceptos",
         "reference_date":"2025-01-23"
      }
   ],
   "totals":{
      "net_amount":1000,
      "taxes_amount":180,
      "total_amount":1180
   }
}

Guía de remisión electrónica (Guía de remisión electrónica)

Para crear una nueva guía de remisión peruana, debe usar el endpoint /documents con los parámetros adecuados y agregar los campos adicionales de envío.

• Endpoint: https://api-billing.koywe.com/V1/documents
• Método: POST
• Cabeceras requeridas:
• Content-Type: application/json
• Authorization: Bearer \<token>
• Accept: */*

{
   "header":{
      "account_id":16268,
      "document_type_id":"100",
      "document_sequence_code":"T002",
      "received_issued_flag":0,
      "issue_date":"2026-02-17",
      "issuer_tax_id_code":"20610383727",
      "issuer_tax_id_type":"PE-RUC",
      "issuer_legal_name":"<string>",
      "issuer_address":"<string>",
      "issuer_district":"<string>",
      "issuer_city":"<string>",
      "issuer_department":"<string>",
      "issuer_country_id":"83",
      "issuer_phone":"<string>",
      "issuer_activity":"<string>",
      "issuer_postalcode":"12345456",
      "receiver_tax_id_code":"20610383727",
      "receiver_tax_id_type":"PE-RUC",
      "receiver_legal_name":"ESCUELA KEMPER URGATES",
      "receiver_address":"<string>",
      "receiver_district":"<string>",
      "receiver_department":"<string>",
      "receiver_city":"<string>",
      "receiver_country_id":"83",
      "receiver_phone":"<string>",
      "receiver_activity":"<string>",
      "receiver_postalcode":"12343456",
      "payment_conditions":"0",
      "currency_id":7,
      "additional":{
         "pe_header":{
            "operation_type":"0101"
         },
         "pe_shipping":{
            "handling_code":"13",
            "special_instructions":6,
            "handling_instructions":"DESCRIPCION DEL MOTIVO DE TRASLADO",
            "gross_weight_measure":"500",
            "gross_weight_measure_id":"KGM",
            "shipment_stage":{
               "transport_mode_code":"01",
               "transit_period":"2026-02-17",
               "driver_person":{
                  "driver_id":"72257341",
                  "first_name":"NOMBRE CONDUCTOR",
                  "family_name":"APELLIDOS CONDUCTOR",
                  "identity_document_reference":"LICENC1234"
               },
               "carrier_party":{
                  "party_identification": "20104498044",
                  "party_legal_entity_name": "EMPRESA TRANSPORTISTA",
                  "party_legal_entity_id": "NUMREGISTRANS",
                  "agent_party_id": "NUMAUTRANS"
               }
            },
            "delivery":{
               "delivery_address":{
                  "id":"150110",
                  "city_subdivision_name":"URBANIZACION",
                  "city_name":"PROVINCIA",
                  "country_subentity":"DEPARTAMENTO",
                  "district":"DISTRITO",
                  "address_line":"DIRECCION PUNTO LLEGADA",
                  "country_id":"83"
               },
               "dispatch":{
                  "id":"150112",
                  "city_subdivision_name":"URBANIZACION",
                  "city_name":"PROVINCIA",
                  "country_subentity":"DEPARTAMENTO",
                  "district":"DISTRITO",
                  "address_line":"DIRECCION PUNTO LLEGADA",
                  "country_id":"83"
               }
            },
            "transport_handling_unit":{
               "transport_equipment_id":"PLACA1"
            }
         }
      }
   },
   "details":[
      {
         "quantity":1,
         "line_description":"Prueba Koywe",
         "unit_measure":"NIU",
         "long_description":"Test descripcion",
         "sku":"3245"
      }
   ]
}

Comprobante de retención con reference_number (Comprobante de retención)

Para crear un nuevo comprobante de retención peruano, debe usar el endpoint /documents con los parámetros adecuados y agregar el campo reference_number que indica el número del documento original (como una factura) al que se refiere el comprobante de retención, junto con los campos de retención requeridos.

• Endpoint: https://api-billing.koywe.com/V1/documents
• Método: POST
• Cabeceras requeridas:
• Content-Type: application/json
• Authorization: Bearer \<token>
• Accept: */*

{
   "header":{
      "account_id":16268,
      "document_type_id":"109",
      "document_sequence_code":"R001",
      "received_issued_flag":0,
      "issue_date":"2025-01-24",
      "issuer_tax_id_code":"20610383727",
      "issuer_tax_id_type":"PE-RUC",
      "issuer_legal_name":"<string>",
      "issuer_address":"<string>",
      "issuer_district":"<string>",
      "issuer_city":"<string>",
      "issuer_department":"<string>",
      "issuer_country_id":"80",
      "issuer_phone":"<string>",
      "issuer_activity":"<string>",
      "issuer_postalcode":"12345456",
      "receiver_tax_id_code":"20473731828",
      "receiver_tax_id_type":"PE-RUC",
      "receiver_legal_name":"ESCUELA KEMPER URGATES",
      "receiver_address":"<string>",
      "receiver_district":"<string>",
      "receiver_city":"<string>",
      "receiver_department":"<string>",
      "receiver_country_id":"80",
      "receiver_phone":"<string>",
      "receiver_activity":"<string>",
      "receiver_email":"[email protected]",
      "receiver_postalcode":"12343456",
      "payment_conditions":"0",
      "currency_id":7,
      "additional":{
         "pe_header":{
            "operation_type":"0101"
         },
         "pe_retention_header":{
            "pe_sunat_retention_system_code":"01",
            "pe_sunat_retention_percent":"3.00",
            "pe_sunat_total_paid":"1144.60"
         }
      }
   },
   "details":[
      {
         "quantity":1,
         "line_description":"Prueba Koywe",
         "unit_measure":"NIU",
         "unit_price":1000,
         "long_description":"Test descripcion",
         "modifier_amount":0,
         "total_taxes":180,
         "modifier_percentage":0,
         "total_amount_line":1180,
         "sku":"3245",
         "taxes":[
            {
               "tax_type_id":"413",
               "tax_percentage":18,
               "tax_amount":180
            }
         ]
      }
   ],
   "references":[
      {
         "document_type_id":"96",
         "reference_number":"F001-00000080",
         "reference_code":1,
         "description":"Pago",
         "reference_date":"2025-01-24",
         "additional":{
            "pe_retention_details":{
               "reference_paid_amount":"1144.60",
               "reference_total_invoice_amount": "1180",
               "reference_paid_date":"2025-01-24",
               "reference_payment_id":"1",
               "pe_reference_sunat_retention_amount":"34.34",
               "pe_reference_sunat_retention_date":"2025-01-23",
               "calculation_rate":"1",
               "currency_id":"7"
            }
         }
      }
   ],
   "totals":{
      "net_amount":1000,
      "taxes_amount":180,
      "total_amount":1180
   }
}

Comprobante de retención con reference_document_id (Comprobante de retención)

Para crear un nuevo comprobante de retención peruano, debe usar el endpoint /documents con los parámetros adecuados y agregar el campo reference_document_id que indica el ID del documento original (como una factura) al que se refiere el comprobante de retención, junto con los campos de retención requeridos.

• Endpoint: https://api-billing.koywe.com/V1/documents
• Método: POST
• Cabeceras requeridas:
• Content-Type: application/json
• Authorization: Bearer \<token>
• Accept: */*

{
   "header":{
      "account_id":16268,
      "document_type_id":"109",
      "document_sequence_code":"R001",
      "received_issued_flag":0,
      "issue_date":"2025-01-24",
      "issuer_tax_id_code":"20610383727",
      "issuer_tax_id_type":"PE-RUC",
      "issuer_legal_name":"<string>",
      "issuer_address":"<string>",
      "issuer_district":"<string>",
      "issuer_city":"<string>",
      "issuer_department":"<string>",
      "issuer_country_id":"80",
      "issuer_phone":"<string>",
      "issuer_activity":"<string>",
      "issuer_postalcode":"12345456",
      "receiver_tax_id_code":"20473731828",
      "receiver_tax_id_type":"PE-RUC",
      "receiver_legal_name":"ESCUELA KEMPER URGATES",
      "receiver_address":"<string>",
      "receiver_district":"<string>",
      "receiver_city":"<string>",
      "receiver_department":"<string>",
      "receiver_country_id":"80",
      "receiver_phone":"<string>",
      "receiver_activity":"<string>",
      "receiver_email":"[email protected]",
      "receiver_postalcode":"12343456",
      "payment_conditions":"0",
      "currency_id":7,
      "additional":{
         "pe_header":{
            "operation_type":"0101"
         },
         "pe_retention_header":{
            "pe_sunat_retention_system_code":"01",
            "pe_sunat_retention_percent":"3.00",
            "pe_sunat_total_paid":"1144.60"
         }
      }
   },
   "details":[
      {
         "quantity":1,
         "line_description":"Prueba Koywe",
         "unit_measure":"NIU",
         "unit_price":1000,
         "long_description":"Test descripcion",
         "modifier_amount":0,
         "total_taxes":180,
         "modifier_percentage":0,
         "total_amount_line":1180,
         "sku":"3245",
         "taxes":[
            {
               "tax_type_id":"413",
               "tax_percentage":18,
               "tax_amount":180
            }
         ]
      }
   ],
   "references":[
      {
         "document_type_id":"96",
         "reference_document_id": "511",
         "reference_code":1,
         "description":"Pago",
         "reference_date":"2025-01-24",
         "additional":{
            "pe_retention_details":{
               "reference_paid_amount":"1144.60",
               "reference_total_invoice_amount": "1180",
               "reference_paid_date":"2025-01-24",
               "reference_payment_id":"1",
               "pe_reference_sunat_retention_amount":"34.34",
               "pe_reference_sunat_retention_date":"2025-01-23",
               "calculation_rate":"1",
               "currency_id":"7"
            }
         }
      }
   ],
   "totals":{
      "net_amount":1000,
      "taxes_amount":180,
      "total_amount":1180
   }
}

Estado de respuesta en el resultado de la API REST

status	description
0	El borrador fue creado exitosamente, firmado y enviado al SII correctamente.
1	Hay errores en los datos de 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 (ej., falta de folios) que impidieron su envío 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": "PE-RUC",
      "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": "PE-RUC",
      "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": "70",
      "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": "JVBERi0xLjMKMyAwIG9iago8PC9..."
   },
   "payment_link": null,
   "result":    {
      "status": 0,
      "error_message": ""
   },
   "_links": {"self": {"href": "https://api-billing.koywe.com/V1/documents"}}
}

API Reference POST /documents

Documentación detallada del endpoint