Examples by country🇵🇪 Perú

➕ Create new documents

Postman collection

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

Invoice (Factura electrónica)

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

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}

Invoice on exports use case (Factura electrónica para casos de exportación)

In order to create a new peruvian export invoice, you need to use the /documents endpoint with the proper parameters. Please note that unlike other countries, the document type remains the same as regular invoices, as this is just a special use case of the regular e-invoice.

1{
2   "header":{
3      "account_id":179,
4      "document_type_id":"96",
5      "received_issued_flag":0,
6      "issue_date":"2025-04-21",
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":"851855616",
19      "receiver_tax_id_type":"US-EIN",
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":"0200"
35         }
36      }
37   },
38   "details":[
39      {
40         "quantity":1,
41         "line_description":"Prueba ROW",
42         "unit_measure":"NIU",
43         "unit_price":1000,
44         "long_description":"Test descripcion",
45         "modifier_amount":0,
46         "total_taxes":0,
47         "modifier_percentage":0,
48         "total_amount_line":1000,
49         "sku":"3245",
50         "taxes":[
51            {
52               "tax_type_id":"425",
53               "tax_percentage":0,
54               "tax_amount":0
55            }
56         ]
57      }
58   ],
59   "totals":{
60      "net_amount":1000,
61      "taxes_amount":0,
62      "total_amount":1000
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. You can issue receipts to recipients identified with a DNI by using the field “receiver_tax_id_type” with the value “PE-DNI”.

IMPORTANT: When issuing receipts, you MUST use TODAY issue_date. Otherwise you will receive a “Error 1079: Solo puede enviar el comprobante en un resumen diario” which means that you are not allowed to issue individuals receipts for previous dates.

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

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

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

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

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

statusdescription
0The draft was created successfully, signed, and sent to the SII successfully.
1There are errors in the input, so the draft was not generated nor sent to the SII. The error details will be in error_message.
2The draft was created successfully; however, there are other issues (e.g., lack of folios) that prevented it from being sent to the SII. The error details will be in error_message.
1{
2   "document_id": 377,
3   "header":    {
4      "account_id": 14540,
5      "document_type_id": 82,
6      "document_type_taxbureau": "01",
7      "document_number": 1040447,
8      "received_issued_flag": 1,
9      "taxbureau_validation_status": null,
10      "issue_date": "2025-04-15",
11      "issuer_tax_id_code": "860517022-2",
12      "issuer_tax_id_type": "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