➕ Create new documents

Invoice (Factura electrónica)

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

Endpoint: https://api-billing.koywe.com/V1/documents
Method: POST
Required headers:
- Content-Type: application/json
- Authorization: Bearer <token>
- Accept: */*

1 {
2    "header":{
3       "account_id":16268,
4       "document_type_id":"96",
5       "received_issued_flag":0,
6       "issue_date":"2025-02-03",
7       "issuer_tax_id_code":"20610383727",
8       "issuer_tax_id_type":"PE-RUC",
9       "issuer_legal_name":"<string>",
10       "issuer_address":"<string>",
11       "issuer_district":"<string>",
12       "issuer_city":"<string>",
13       "issuer_department":"<string>",
14       "issuer_country_id":"83",
15       "issuer_phone":"<string>",
16       "issuer_activity":"<string>",
17 	  "issuer_postalcode":"12345456",
18       "receiver_tax_id_code":"20473731828",
19       "receiver_tax_id_type":"PE-RUC",
20       "receiver_legal_name":"ESCUELA KEMPER URGATES",
21       "receiver_address":"<string>",
22       "receiver_district":"<string>",
23       "receiver_city":"<string>",
24       "receiver_department":"<string>",
25       "receiver_country_id":"83",
26       "receiver_phone":"<string>",
27       "receiver_activity":"<string>",
28 	  "receiver_postalcode":"12343456",
29       "payment_conditions":"0",
30       "currency_id":7,
31       "additional":{
32          "pe_header":{
33             "signature_id":"ASDFG",
34             "operation_type":"0101"
35          }
36       }
37    },
38    "details":[
39       {
40          "quantity":1,
41          "line_description":"Prueba Koywe",
42          "unit_measure":"NIU",
43          "unit_price":1000,
44          "long_description":"Test descripcion",
45          "modifier_amount":0,
46          "total_taxes":180,
47          "modifier_percentage":0,
48          "total_amount_line":1180,
49          "sku":"3245",
50          "taxes":[
51             {
52                "tax_type_id":"413",
53                "tax_percentage":18,
54                "tax_amount":180
55             }
56          ]
57       }
58    ],
59    "totals":{
60       "net_amount":1000,
61       "taxes_amount":180,
62       "total_amount":1180
63    }
64 }

Receipt (Boleta electrónica)

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

Endpoint: https://api-billing.koywe.com/V1/documents
Method: POST
Required headers:
- Content-Type: application/json
- Authorization: Bearer <token>
- Accept: */*

1 {
2    "header":{
3       "account_id":16268,
4       "document_type_id":"97",
5       "received_issued_flag":0,
6       "issue_date":"2025-02-03",
7       "issuer_tax_id_code":"20610383727",
8       "issuer_tax_id_type":"PE-RUC",
9       "issuer_legal_name":"<string>",
10       "issuer_address":"<string>",
11       "issuer_district":"<string>",
12       "issuer_city":"<string>",
13       "issuer_department":"<string>",
14       "issuer_country_id":"80",
15       "issuer_phone":"<string>",
16       "issuer_activity":"<string>",
17 	  "issuer_postalcode":"12345456",
18       "receiver_tax_id_code":"20473731828",
19       "receiver_tax_id_type":"PE-RUC",
20       "receiver_legal_name":"ESCUELA KEMPER URGATES",
21       "receiver_address":"<string>",
22       "receiver_district":"<string>",
23       "receiver_city":"<string>",
24       "receiver_department":"<string>",
25       "receiver_country_id":"80",
26       "receiver_phone":"<string>",
27       "receiver_activity":"<string>",
28 	  "receiver_postalcode":"12343456",
29       "payment_conditions":"0",
30       "currency_id":7,
31       "additional":{
32          "pe_header":{
33             "signature_id":"ASDFG",
34             "operation_type":"0101"
35          }
36       }
37    },
38    "details":[
39       {
40          "quantity":1,
41          "line_description":"Prueba Koywe",
42          "unit_measure":"NIU",
43          "unit_price":1000,
44          "long_description":"Test descripcion",
45          "modifier_amount":0,
46          "total_taxes":180,
47          "modifier_percentage":0,
48          "total_amount_line":1180,
49          "sku":"3245",
50          "taxes":[
51             {
52                "tax_type_id":"413",
53                "tax_percentage":18,
54                "tax_amount":180
55             }
56          ]
57       }
58    ],
59    "totals":{
60       "net_amount":1000,
61       "taxes_amount":180,
62       "total_amount":1180
63    }
64 }

Credit note (Nota de crédito electrónica)

In order to create a new peruvian credit note, you need to use the /documents endpoint with the proper parameters and add a reference field

Endpoint: https://api-billing.koywe.com/V1/documents
Method: POST
Required headers:
Content-Type: application/json
Authorization: Bearer <token>
Accept: */*

1 {
2    "header": {
3       "account_id": 16268,
4       "document_type_id": "98",
5       "received_issued_flag": 0,
6       "issue_date": "2025-01-27",
7       "issuer_tax_id_code": "20610383727",
8       "issuer_tax_id_type": "PE-RUC",
9       "issuer_legal_name": "<string>",
10       "issuer_address": "<string>",
11       "issuer_district": "<string>",
12       "issuer_city": "<string>",
13 	  "issuer_department":"<string>",
14       "issuer_country_id": "80",
15       "issuer_phone": "<string>",
16       "issuer_activity": "<string>",
17 	  "issuer_postalcode":"12345456",
18       "receiver_tax_id_code": "20473731828",
19       "receiver_tax_id_type": "PE-RUC",
20       "receiver_legal_name": "ESCUELA KEMPER URGATES",
21       "receiver_address": "<string>",
22       "receiver_district": "<string>",
23       "receiver_city": "<string>",
24 	  "receiver_department":"<string>",
25       "receiver_country_id": "80",
26       "receiver_phone": "<string>",
27       "receiver_activity": "<string>",
28 	  "receiver_postalcode":"12343456",
29       "payment_conditions": "0",
30       "currency_id": 7,
31 	  "additional":{
32          "pe_header":{
33             "signature_id":"ASDFG",
34             "operation_type":"0101"
35          }
36       }
37    },
38    "details": [
39       {
40          "quantity": 1,
41          "line_description": "Prueba Koywe",
42          "unit_measure": "NIU",
43          "unit_price": 1000,
44          "long_description": "Test descripcion",
45          "modifier_amount": 0,
46          "total_taxes": 180,
47          "modifier_percentage": 0,
48          "total_amount_line": 1180,
49          "sku": "3245",
50          "taxes": [
51             {
52                "tax_type_id": "413",
53                "tax_percentage": 18,
54                "tax_amount": 180
55             }
56          ]
57       }
58    ],
59    "references": [
60 	   {
61 		  "document_type_id": "96",
62 		  "reference_number": "F001-00000087",
63 		  "reference_code": "01",
64 		  "description": "Anulacion solicitada por el emisor",
65 		  "reference_date": "2025-01-27"
66 	   }
67    ],
68    "totals": {
69       "net_amount": 1000,
70       "taxes_amount": 180,
71       "total_amount": 1180
72    }
73 }

Debit note (Nota de débito electrónica)

In order to create a new peruvian debit note, you need to use the /documents endpoint with the proper parameters and add a reference field

Endpoint: https://api-billing.koywe.com/V1/documents
Method: POST
Required headers:
Content-Type: application/json
Authorization: Bearer <token>
Accept: */*

1 {
2    "header":{
3       "account_id":16268,
4       "document_type_id":"99",
5       "received_issued_flag":0,
6       "issue_date":"2025-01-23",
7       "issuer_tax_id_code":"20610383727",
8       "issuer_tax_id_type":"PE-RUC",
9       "issuer_legal_name":"<string>",
10       "issuer_address":"<string>",
11       "issuer_district":"<string>",
12       "issuer_city":"<string>",
13 	  "issuer_department":"<string>",
14       "issuer_country_id":"80",
15       "issuer_phone":"<string>",
16       "issuer_activity":"<string>",
17 	  "issuer_postalcode":"12345456",
18       "receiver_tax_id_code":"20473731828",
19       "receiver_tax_id_type":"PE-RUC",
20       "receiver_legal_name":"ESCUELA KEMPER URGATES",
21       "receiver_address":"<string>",
22       "receiver_district":"<string>",
23       "receiver_city":"<string>",
24 	  "receiver_department":"<string>",
25       "receiver_country_id":"80",
26       "receiver_phone":"<string>",
27       "receiver_activity":"<string>",
28 	  "receiver_postalcode":"12343456",
29       "payment_conditions":"0",
30       "currency_id":7,
31       "additional":{
32          "pe_header":{
33             "signature_id":"ASDFG",
34             "operation_type":"0101"
35          }
36       }
37    },
38    "details":[
39       {
40          "quantity":1,
41          "line_description":"Prueba Koywe",
42          "unit_measure":"NIU",
43          "unit_price":1000,
44          "long_description":"Test descripcion",
45          "modifier_amount":0,
46          "total_taxes":180,
47          "modifier_percentage":0,
48          "total_amount_line":1180,
49          "sku":"3245",
50          "taxes":[
51             {
52                "tax_type_id":"413",
53                "tax_percentage":18,
54                "tax_amount":180
55             }
56          ]
57       }
58    ],
59    "references": [
60 	 {
61 		"document_type_id":"96",
62 		"reference_number":"F001-00000080",
63 		"reference_code":"03",
64 		"description":"Penalidad/otros conceptos",
65 		"reference_date":"2025-01-23"
66 	 }
67    ],
68    "totals":{
69       "net_amount":1000,
70       "taxes_amount":180,
71       "total_amount":1180
72    }
73 }

Bill of lading (Guía de remisión electrónica)

In order to create a new peruvian bill of lading, you need to use the /documents endpoint with the proper parameters and add the additional shipping fields

Endpoint: https://api-billing.koywe.com/V1/documents
Method: POST
Required headers:
Content-Type: application/json
Authorization: Bearer <token>
Accept: */*

1 {
2    "header":{
3       "account_id":16268,
4       "document_type_id":"100",
5       "received_issued_flag":0,
6       "issue_date":"2025-01-31",
7       "issuer_tax_id_code":"20610383727",
8       "issuer_tax_id_type":"PE-RUC",
9       "issuer_legal_name":"<string>",
10       "issuer_address":"<string>",
11       "issuer_district":"<string>",
12       "issuer_city":"<string>",
13 	  "issuer_department":"<string>",
14       "issuer_country_id":"83",
15       "issuer_phone":"<string>",
16       "issuer_activity":"<string>",
17 	  "issuer_postalcode":"12345456",
18       "receiver_tax_id_code":"20473731828",
19       "receiver_tax_id_type":"PE-RUC",
20       "receiver_legal_name":"ESCUELA KEMPER URGATES",
21       "receiver_address":"<string>",
22       "receiver_district":"<string>",
23 	  "receiver_department":"<string>",
24       "receiver_city":"<string>",
25       "receiver_country_id":"80",
26       "receiver_phone":"<string>",
27       "receiver_activity":"<string>",
28 	  "receiver_postalcode":"12343456",
29       "payment_conditions":"0",
30       "currency_id":7,
31       "additional":{
32          "pe_header":{
33             "signature_id":"ASDFG",
34             "operation_type":"0101"
35          },
36          "pe_shipping":{
37             "handling_code":"01",
38             "special_instructions":"SUNAT_Envio_IndicadorTrasladoVehiculoM1L",
39             "handling_instructions":"DESCRIPCION DEL MOTIVO DE TRASLADO",
40             "gross_weight_measure":"500",
41             "gross_weight_measure_id":"KGM",
42             "shipment_stage":{
43                "transport_mode_code":"01",
44                "transit_period":"2025-01-31",
45                "driver_person":{
46                   "driver_id":"72257341",
47                   "first_name":"NOMBRE CONDUCTOR",
48                   "family_name":"APELLIDOS CONDUCTOR",
49                   "job_title":"Principal",
50                   "identity_document_reference":"LICENC1234"
51                },
52                "carrier_party":{
53           	   "party_identification": "20104498044",
54           	   "party_legal_entity_name": "EMPRESA TRANSPORTISTA",
55           	   "party_legal_entity_id": "NUMREGISTRANS",
56           	   "agent_party_id": "NUMAUTRANS"
57           	}
58             },
59             "delivery":{
60                "delivery_address":{
61                   "id":"150110",
62                   "city_subdivision_name":"URBANIZACION",
63                   "city_name":"PROVINCIA",
64                   "country_subentity":"DEPARTAMENTO",
65                   "district":"DISTRITO",
66                   "address_line":"DIRECCION PUNTO LLEGADA",
67                   "country_id":"83"
68                },
69                "dispatch":{
70                   "id":"150112",
71                   "city_subdivision_name":"URBANIZACION",
72                   "city_name":"PROVINCIA",
73                   "country_subentity":"DEPARTAMENTO",
74                   "district":"DISTRITO",
75                   "address_line":"DIRECCION PUNTO LLEGADA",
76                   "country_id":"83",
77                   "dispatch_party_company_id": "NUMAUTORIREMIT123"
78                }
79             },
80             "transport_handling_unit":{
81                "transport_equipment_id":"PLACA1"
82             }
83          }
84       }
85    },
86    "details":[
87       {
88          "quantity":1,
89          "line_description":"Prueba Koywe",
90          "unit_measure":"NIU",
91          "unit_price":1000,
92          "long_description":"Test descripcion",
93          "modifier_amount":0,
94          "total_taxes":180,
95          "modifier_percentage":0,
96          "total_amount_line":1180,
97          "sku":"3245",
98          "taxes":[
99             {
100                "tax_type_id":"413",
101                "tax_percentage":18,
102                "tax_amount":180
103             }
104          ]
105       }
106    ],
107    "references": [
108 	 {
109 		"document_type_id": "96",
110 		"reference_number": "F001-00000099",
111 		"reference_code": 1,
112 		"description": "Traslado",
113 		"reference_date": "2025-01-31"
114 	 }
115    ],
116    "totals":{
117       "net_amount":1000,
118       "taxes_amount":180,
119       "total_amount":1180
120    }
121 }

Retention receipt (Comprobante de retención)

In order to create a new peruvian retention receipt, you need to use the /documents endpoint with the proper parameters and add the retention fields

Endpoint: https://api-billing.koywe.com/V1/documents
Method: POST
Required headers:
Content-Type: application/json
Authorization: Bearer <token>
Accept: */*

1 {
2    "header":{
3       "account_id":16268,
4       "document_type_id":"109",
5       "received_issued_flag":0,
6       "issue_date":"2025-01-24",
7       "issuer_tax_id_code":"20610383727",
8       "issuer_tax_id_type":"PE-RUC",
9       "issuer_legal_name":"<string>",
10       "issuer_address":"<string>",
11       "issuer_district":"<string>",
12       "issuer_city":"<string>",
13 	  "issuer_department":"<string>",
14       "issuer_country_id":"80",
15       "issuer_phone":"<string>",
16       "issuer_activity":"<string>",
17 	  "issuer_postalcode":"12345456",
18       "receiver_tax_id_code":"20473731828",
19       "receiver_tax_id_type":"PE-RUC",
20       "receiver_legal_name":"ESCUELA KEMPER URGATES",
21       "receiver_address":"<string>",
22       "receiver_district":"<string>",
23       "receiver_city":"<string>",
24 	  "receiver_department":"<string>",
25       "receiver_country_id":"80",
26       "receiver_phone":"<string>",
27       "receiver_activity":"<string>",
28       "receiver_email":"rockman-jjlb@hotmail.com",
29 	  "receiver_postalcode":"12343456",
30       "payment_conditions":"0",
31       "currency_id":7,
32       "additional":{
33          "pe_header":{
34             "signature_id":"ASDFG",
35             "operation_type":"0101"
36          },
37 		 "pe_retention_header":{
38 			 "pe_sunat_retention_system_code":"01",
39 			 "pe_sunat_retention_percent":"3.00",
40 			 "pe_sunat_total_paid":"1144.60"
41 		 }
42       }
43    },
44    "details":[
45       {
46          "quantity":1,
47          "line_description":"Prueba Koywe",
48          "unit_measure":"NIU",
49          "unit_price":1000,
50          "long_description":"Test descripcion",
51          "modifier_amount":0,
52          "total_taxes":180,
53          "modifier_percentage":0,
54          "total_amount_line":1180,
55          "sku":"3245",
56          "taxes":[
57             {
58                "tax_type_id":"413",
59                "tax_percentage":18,
60                "tax_amount":180
61             }
62          ]
63       }
64    ],
65    "references":[
66 		 {
67 			"document_type_id":"96",
68 			"reference_number":"F001-00000080",
69 			"reference_code":1,
70 			"description":"Pago",
71 			"reference_date":"2025-01-24",
72 			"additional":{
73 				"pe_retention_details":{
74 					"reference_paid_amount":"1144.60",
75 					"reference_total_invoice_amount": "1180",
76 					"reference_paid_date":"2025-01-24",
77 					"reference_payment_id":"1",
78 					"pe_reference_sunat_retention_amount":"34.34",
79 					"pe_reference_sunat_retention_date":"2025-01-23",
80 					"calculation_rate":"1",
81 					"currency_id":"7"
82 				}
83 			}
84 		 }
85     ],
86    "totals":{
87       "net_amount":1000,
88       "taxes_amount":180,
89       "total_amount":1180
90    }
91 }

Response status in result the API Rest

status	description
0	The draft was created successfully, signed, and sent to the SII successfully.
1	There are errors in the input, so the draft was not generated nor sent to the SII. The error details will be in error_message.
2	The 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": "PE-RUC",
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": "PE-RUC",
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": "70",
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