Emite una boleta o una factura
curl https://api.boletura.com/v1/documents \ --request POST \ --header 'Authorization: Bearer bol_test_TU_CLAVE' \ --header 'Idempotency-Key: 2de20fe7-c22e-4c38-a6c1-c2945cb6db01' \ --header 'Content-Type: application/json' \ --data '{ "type": "boleta", "external_id": "venta-98231", "customer": { "document_type": "dni", "document_number": "45678912", "name": "Juan Pérez" }, "items": [ { "description": "Estacionamiento 2 horas", "quantity": 1, "unit": "ZZ", "unit_price": 12 } ], "metadata": { "placa": "ABC-123" }}'$ch = curl_init("https://api.boletura.com/v1/documents");
curl_setopt($ch, CURLOPT_POST, true);curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: Bearer bol_test_TU_CLAVE', 'Idempotency-Key: 2de20fe7-c22e-4c38-a6c1-c2945cb6db01', 'Content-Type: application/json']);curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([ 'type' => 'boleta', 'external_id' => 'venta-98231', 'customer' => [ 'document_type' => 'dni', 'document_number' => '45678912', 'name' => 'Juan Pérez' ], 'items' => [ [ 'description' => 'Estacionamiento 2 horas', 'quantity' => 1, 'unit' => 'ZZ', 'unit_price' => 12 ] ], 'metadata' => [ 'placa' => 'ABC-123' ]]));
curl_exec($ch);
curl_close($ch);import http.clientimport json
conn = http.client.HTTPSConnection("api.boletura.com")
payload = json.dumps({ "type": "boleta", "external_id": "venta-98231", "customer": { "document_type": "dni", "document_number": "45678912", "name": "Juan Pérez" }, "items": [ { "description": "Estacionamiento 2 horas", "quantity": 1, "unit": "ZZ", "unit_price": 12 } ], "metadata": { "placa": "ABC-123" }})headers = { "Authorization": "Bearer bol_test_TU_CLAVE", "Idempotency-Key": "2de20fe7-c22e-4c38-a6c1-c2945cb6db01", "Content-Type": "application/json"}
conn.request( "POST", "/v1/documents", body=payload, headers=headers,)
response = conn.getresponse()print(response.read().decode())
conn.close()using var client = new HttpClient();
var request = new HttpRequestMessage(HttpMethod.Post, "https://api.boletura.com/v1/documents");request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", "bol_test_TU_CLAVE");request.Headers.TryAddWithoutValidation("Idempotency-Key", "2de20fe7-c22e-4c38-a6c1-c2945cb6db01");request.Content = new StringContent("""{ "type": "boleta", "external_id": "venta-98231", "customer": { "document_type": "dni", "document_number": "45678912", "name": "Juan Pérez" }, "items": [ { "description": "Estacionamiento 2 horas", "quantity": 1, "unit": "ZZ", "unit_price": 12 } ], "metadata": { "placa": "ABC-123" }}""",System.Text.Encoding.UTF8, "application/json");
using var response = await client.SendAsync(request);java.io.ByteArrayOutputStream body = new java.io.ByteArrayOutputStream();body.write("{\n \"type\": \"boleta\",\n \"external_id\": \"venta-98231\",\n \"customer\": {\n \"document_type\": \"dni\",\n \"document_number\": \"45678912\",\n \"name\": \"Juan Pérez\"\n },\n \"items\": [\n {\n \"description\": \"Estacionamiento 2 horas\",\n \"quantity\": 1,\n \"unit\": \"ZZ\",\n \"unit_price\": 12\n }\n ],\n \"metadata\": {\n \"placa\": \"ABC-123\"\n }\n}".getBytes(java.nio.charset.StandardCharsets.UTF_8));
HttpClient client = HttpClient.newHttpClient();HttpRequest request = HttpRequest.newBuilder() .uri(java.net.URI.create("https://api.boletura.com/v1/documents")) .header("Authorization", "Bearer bol_test_TU_CLAVE") .header("Idempotency-Key", "2de20fe7-c22e-4c38-a6c1-c2945cb6db01") .header("Content-Type", "application/json") .method("POST", HttpRequest.BodyPublishers.ofByteArray(body.toByteArray())) .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());System.out.println(response.body());fetch('https://api.boletura.com/v1/documents', { method: 'POST', headers: { Authorization: 'Bearer bol_test_TU_CLAVE', 'Idempotency-Key': '2de20fe7-c22e-4c38-a6c1-c2945cb6db01', 'Content-Type': 'application/json' }, body: JSON.stringify({ type: 'boleta', external_id: 'venta-98231', customer: { document_type: 'dni', document_number: '45678912', name: 'Juan Pérez' }, items: [ { description: 'Estacionamiento 2 horas', quantity: 1, unit: 'ZZ', unit_price: 12 } ], metadata: { placa: 'ABC-123' } })})Responde de inmediato con el número, el PDF y el QR; el envío a SUNAT es asíncrono, y su resultado se consulta en sunat_status y sunat.response_code, nunca como un error HTTP de esta operación. La plataforma recalcula todos los importes. Una solicitud rechazada no consume número.
Requiere el scope documents:write.
Autorización
Sección titulada «Autorización»Parámetros
Sección titulada «Parámetros»Parámetros de cabecera
Sección titulada «Parámetros de cabecera»Identifica la operación para reintentarla sin duplicarla durante 24 horas desde la respuesta final; se recomienda un UUID. De 1 a 128 caracteres [A-Za-z0-9._:-]. Sin ella responde 400 idempotency_key_required, y con otro formato, 400 idempotency_key_invalid. La misma clave con otra solicitud responde 422 idempotency_key_reused, y con la primera aún en curso, 409 idempotency_in_progress.
Cuerpo de la solicitudobligatorio
Sección titulada «Cuerpo de la solicitudobligatorio»Boleta o factura por emitir. Las notas de crédito y de débito tienen su propia operación.
object
Tipo de comprobante. Otro valor responde 422 document_type_invalid.
factura: factura electrónica.boleta: boleta de venta electrónica.
UUID de la empresa emisora; sale de GET /v1/companies. Se puede omitir si la clave tiene empresa por defecto (422 company_required si no). Una que no existe en la cuenta responde 422 company_not_found. Una empresa suspendida, o en live una que no está ready, responde 422 company_not_ready.
Código del establecimiento. Normalmente no hace falta, porque la serie ya fija el establecimiento, y GET /v1/companies no devuelve este código. Por defecto, el de series si se envió; si no, el principal. Uno que no existe responde 422 establishment_not_found.
Serie, como B001. Por defecto, la serie por defecto del tipo en ese establecimiento y ambiente. No distingue mayúsculas. Una que no existe o no es del establecimiento responde 422 series_not_found; una de otro tipo, 422 series_type_mismatch; una cerrada, 422 series_closed; y una que llegó a su último número, 422 series_exhausted.
Fecha de emisión; por defecto hoy en Lima. No futura, y hasta hoy menos 3 días en factura y menos 7 en boleta (422 issue_date_out_of_window).
Moneda; por defecto PEN, la única admitida (422 currency_not_supported).
PEN: soles.
Cliente. Obligatorio en una factura y en una boleta de más de S/ 700 con IGV.
object
Tipo de documento. Otro valor responde 422 customer_document_type_invalid, salvo cuando el comprobante exige un tipo: una factura responde 422 customer_ruc_required, y una boleta de más de S/ 700 con IGV, 422 customer_document_required.
dni: documento nacional de identidad, de 8 dígitos.ruc: RUC, de 11 dígitos con dígito verificador válido.ce: carné de extranjería, de hasta 30 caracteres.pasaporte: pasaporte, de hasta 30 caracteres.otros: otro documento. Hoy ningún comprobante lo admite: una boleta responde422 customer_document_type_not_supportedy una factura exigeruc.none: cliente sin documento, sindocument_number.
Número de documento. DNI de 8 dígitos (422 dni_invalid), RUC de 11 dígitos con dígito verificador válido (422 ruc_invalid), carné de extranjería o pasaporte de hasta 30 caracteres (422 field_too_long), sin saltos de línea ni tabuladores (422 field_invalid_characters). No admite |, y con none no se envía (422 customer_document_number_invalid). Se recorta en los extremos.
Nombre o razón social, de 3 a 200 caracteres (422 field_too_short, 422 field_too_long), sin saltos de línea ni tabuladores (422 field_invalid_characters). Obligatorio si el cliente tiene documento (422 field_required). En test, los valores SIMULAR RECHAZO, SIMULAR OBSERVACIONES, SIMULAR TIMEOUT y SIMULAR VENCIMIENTO simulan ese resultado sin ir a SUNAT beta; en live son un nombre cualquiera. En una boleta, el caso actúa sobre su resumen diario: SIMULAR OBSERVACIONES y SIMULAR TIMEOUT alcanzan a todas las boletas del resumen, y SIMULAR RECHAZO devuelve las demás a pending.
Dirección, de hasta 500 caracteres (422 field_too_long), sin saltos de línea ni tabuladores (422 field_invalid_characters).
Correo, de hasta 254 caracteres (422 field_too_long), sin saltos de línea ni tabuladores (422 field_invalid_characters).
Líneas del comprobante, de 1 a 200 (422 items_required, 422 items_too_many).
Línea del comprobante. Lleva exactamente uno entre unit_price y unit_value: ninguno responde 422 unit_amount_required y ambos, 422 unit_amount_ambiguous. Un ítem que suma 0.00 responde 422 amount_invalid. Una factura también responde 422 amount_invalid si sus importes no cuadran con la tolerancia de SUNAT; una boleta en ese caso se emite, porque SUNAT solo la observa.
object
Descripción de la línea, de hasta 500 caracteres, sin saltos de línea ni tabuladores (422 field_too_long, 422 field_invalid_characters).
Cantidad mayor que 0, con hasta 12 enteros y 3 decimales (422 quantity_invalid). Va como número JSON, nunca entre comillas (400 invalid_json).
Código de unidad de medida del catálogo 03 de SUNAT; por defecto NIU. Para servicios, ZZ. No distingue mayúsculas. Uno que no existe responde 422 unit_invalid.
Precio unitario con IGV incluido, mayor que 0, con hasta 12 enteros y 10 decimales (422 amount_invalid).
Valor unitario sin IGV, mayor que 0, con hasta 12 enteros y 10 decimales (422 amount_invalid).
Afectación al IGV; por defecto gravado. Otro valor responde 422 tax_affectation_invalid.
gravado: paga IGV.exonerado: exonerado de IGV.inafecto: inafecto al IGV.
Código interno del integrador, de hasta 30 caracteres (422 field_too_long), sin saltos de línea ni tabuladores (422 field_invalid_characters).
Observación visible en el PDF, de hasta 500 caracteres, sin saltos de línea ni tabuladores (422 field_too_long, 422 field_invalid_characters).
Forma de pago; por defecto al contado.
object
Tipo de pago. Otro valor responde 422 payment_terms_not_supported.
contado: pago al contado, sininstallments(422 installments_not_allowed).credito: el total o una parte se cobra después de la emisión. Solo en facturas: una boleta responde422 payment_terms_not_supported.
Cuotas de una factura al crédito, de 1 a 999 (422 installments_required, 422 installments_too_many), cada una con amount y due_date (422 field_required). Su suma es el monto neto pendiente y no supera el total menos la detracción, si la lleva (422 installments_exceed_total); puede ser menor si el cliente retiene una parte.
Cuota de una factura al crédito.
object
Monto de la cuota en soles, mayor que cero, con hasta 12 enteros y 2 decimales (422 installment_amount_invalid).
Fecha de pago de la cuota, posterior a la fecha de emisión (422 installment_due_date_invalid).
Detracción, solo en facturas sujetas.
object
Código de la operación sujeta; quien emite declara si aplica. Solo facturas, con un total de más de S/ 700 con IGV y todos los ítems gravados. Otro código responde 422 detraction_code_invalid; una boleta, 422 detraction_not_allowed; un total menor, 422 detraction_amount_too_low; un ítem no gravado, 422 detraction_items_not_taxed; y una empresa sin cuenta de detracciones, 422 detraction_account_required.
022: otros servicios empresariales.037: demás servicios gravados con el IGV.
Objeto JSON libre de hasta 4 KB. Se devuelve el mismo objeto, aunque el orden de sus claves y los espacios pueden cambiar. Otro valor, o uno con U+0000, responde 422 metadata_invalid.
Identificador del integrador, de hasta 64 caracteres (422 field_too_long), sin saltos de línea ni tabuladores (422 field_invalid_characters), único por empresa y ambiente entre los documentos no rechazados. Repetirlo responde 409 external_id_conflict con el document_id del existente; tras un rechazo se puede reutilizar para la reemisión.
Documento rechazado que este reemplaza, de la misma empresa y ambiente (422 replaced_document_not_rejected). Cada rechazado se reemplaza una sola vez: otro intento responde 409 document_already_replaced con el document_id del reemplazo.
Ejemplos
Boleta
{ "type": "boleta", "external_id": "venta-98231", "customer": { "document_type": "dni", "document_number": "45678912", "name": "Juan Pérez" }, "items": [ { "description": "Estacionamiento 2 horas", "quantity": 1, "unit": "ZZ", "unit_price": 12 } ], "metadata": { "placa": "ABC-123" }}Factura
{ "type": "factura", "customer": { "document_type": "ruc", "document_number": "20131312955", "name": "Cliente S.A.C." }, "items": [ { "description": "Servicio mensual", "quantity": 2, "unit": "ZZ", "unit_value": 100 } ]}Factura con detracción
La respuesta es igual a la de una factura sin detracción, porque el documento no devuelve ese dato.
{ "type": "factura", "customer": { "document_type": "ruc", "document_number": "20131312955", "name": "Cliente S.A.C." }, "detraction": { "code": "037" }, "items": [ { "description": "Servicio de estacionamiento mensual", "quantity": 1, "unit": "ZZ", "unit_value": 1000 } ]}Respuestas
Sección titulada «Respuestas»Documento emitido y numerado. Con Idempotent-Replayed: true, es la respuesta guardada de la solicitud original.
Comprobante electrónico: una boleta, una factura, una nota de crédito o una nota de débito.
object
UUID del documento.
Siempre document.
Ambiente del documento. Uno de test no se ve con una clave live, ni al revés.
UUID de la empresa emisora.
Tipo de comprobante.
Serie, como B001.
Correlativo dentro de la serie.
Serie y correlativo, como B001-125.
Fecha de emisión, en fecha civil de Lima.
Moneda; hoy siempre PEN.
Cliente del comprobante.
object
Tipo de documento del cliente.
Número de documento; nulo si el cliente no tiene.
Nombre o razón social.
Dirección.
Correo.
Líneas del comprobante. No aparece en el listado.
Línea del comprobante, con los importes calculados por la plataforma.
object
Número de línea, desde 1.
Código interno del integrador; nulo si el ítem no lo trajo.
Descripción de la línea.
Cantidad, sin ceros finales.
Código de unidad de medida.
Precio unitario con IGV, sin ceros finales.
Valor unitario sin IGV, sin ceros finales.
Afectación al IGV.
Tasa del IGV en porcentaje, como 18.
Valor de la línea sin IGV, con 2 decimales.
IGV de la línea, con 2 decimales.
Total de la línea con IGV, con 2 decimales.
Totales calculados por la plataforma.
object
Total de operaciones gravadas, sin IGV.
Total de operaciones exoneradas.
Total de operaciones inafectas.
Total de descuentos; hoy siempre 0.00.
IGV total.
Importe total con IGV.
Importe total en letras.
Estado interno.
Estado fiscal. Es el campo que dice si el documento es válido.
Estado de la entrega por webhook.
Detalle del envío a SUNAT.
object
Código de respuesta de SUNAT; nulo hasta que responde.
Descripción de la respuesta de SUNAT; nula hasta que responde.
Observaciones de SUNAT.
Fin del plazo de envío: la fecha de emisión más 3 días en facturas y sus notas, y más 7 en boletas y sus notas, al final del día de Lima. No limita la llegada del CDR.
Envío a SUNAT; nulo si aún no se envió. Timestamp RFC 3339 en UTC, con seis decimales.
Aceptación de SUNAT; nula si aún no se aceptó. Timestamp RFC 3339 en UTC, con seis decimales.
true si hay un envío con resultado desconocido y se está recuperando el CDR o el ticket. No reemitas mientras dure.
Valor de resumen de la firma del XML (DigestValue).
Texto del QR del comprobante, con sus campos separados por |.
PNG del QR como data URI. No aparece en el listado.
Enlaces de descarga.
object
Ruta del PDF.
Ruta del XML firmado.
Ruta del CDR; nula hasta que SUNAT responde, y en una boleta confirmada con una revisión manual de su resumen, que no tiene CDR.
En una nota de crédito o de débito, el documento que afecta; si no, nulo.
Motivo de la nota de crédito; nulo en los demás comprobantes.
object
Motivo de la nota.
Descripción libre del motivo.
Motivo de la nota de débito; nulo en los demás comprobantes.
object
Motivo de la nota.
Descripción libre del motivo.
Identificador del integrador; nulo si no se envió.
Documento rechazado que este reemplaza; nulo si no reemplaza a ninguno.
El objeto que envió el integrador; nulo si no envió ninguno.
Creación. Timestamp RFC 3339 en UTC, con seis decimales.
Última modificación. Timestamp RFC 3339 en UTC, con seis decimales.
Ejemplos
Boleta
{ "id": "0192f1a2-7c3e-7d4b-9a8f-2b6c1d0e4f5a", "object": "document", "environment": "test", "company_id": "0192f0b1-2d4c-7a1e-8b3f-1c2d3e4f5a6b", "type": "boleta", "series": "B001", "number": 125, "full_number": "B001-125", "issue_date": "2026-10-09", "currency": "PEN", "customer": { "document_type": "dni", "document_number": "45678912", "name": "Juan Pérez", "address": null, "email": null }, "items": [ { "line_number": 1, "product_code": null, "description": "Estacionamiento 2 horas", "quantity": 1, "unit": "ZZ", "unit_price": 12, "unit_value": 10.1694915254, "tax_affectation": "gravado", "igv_rate": 18, "line_value": 10.17, "igv_amount": 1.83, "line_total": 12 } ], "totals": { "taxable": 10.17, "exempt": 0, "unaffected": 0, "discount": 0, "igv": 1.83, "total": 12, "amount_in_words": "DOCE CON 00/100 SOLES" }, "status": "issued", "sunat_status": "pending", "delivery_status": "none", "sunat": { "response_code": null, "description": null, "notes": [], "deadline_at": "2026-10-17T04:59:59.000000Z", "submitted_at": null, "accepted_at": null, "reconciliation_required": false }, "hash": "2/tssig+2hIBSmZyIT0CWMhsTMnRKmApc0tdWRsDs4U=", "qr_text": "20100066603|03|B001|125|1.83|12.00|2026-10-09|1|45678912|2/tssig+2hIBSmZyIT0CWMhsTMnRKmApc0tdWRsDs4U=", "qr_image": "data:image/png;base64,iVBORw0KGgo=", "links": { "pdf": "/v1/documents/0192f1a2-7c3e-7d4b-9a8f-2b6c1d0e4f5a/pdf", "xml": "/v1/documents/0192f1a2-7c3e-7d4b-9a8f-2b6c1d0e4f5a/xml", "cdr": null }, "affected_document_id": null, "credit_note": null, "debit_note": null, "external_id": "venta-98231", "replaces_document_id": null, "metadata": { "placa": "ABC-123" }, "created_at": "2026-10-09T14:03:21.482913Z", "updated_at": "2026-10-09T14:03:21.482913Z"}Factura
{ "id": "0192f1a2-7c3e-7d4b-9a8f-2b6c1d0e4f5b", "object": "document", "environment": "test", "company_id": "0192f0b1-2d4c-7a1e-8b3f-1c2d3e4f5a6b", "type": "factura", "series": "F001", "number": 42, "full_number": "F001-42", "issue_date": "2026-10-09", "currency": "PEN", "customer": { "document_type": "ruc", "document_number": "20131312955", "name": "Cliente S.A.C.", "address": null, "email": null }, "items": [ { "line_number": 1, "product_code": null, "description": "Servicio mensual", "quantity": 2, "unit": "ZZ", "unit_price": 118, "unit_value": 100, "tax_affectation": "gravado", "igv_rate": 18, "line_value": 200, "igv_amount": 36, "line_total": 236 } ], "totals": { "taxable": 200, "exempt": 0, "unaffected": 0, "discount": 0, "igv": 36, "total": 236, "amount_in_words": "DOSCIENTOS TREINTA Y SEIS CON 00/100 SOLES" }, "status": "issued", "sunat_status": "pending", "delivery_status": "none", "sunat": { "response_code": null, "description": null, "notes": [], "deadline_at": "2026-10-13T04:59:59.000000Z", "submitted_at": null, "accepted_at": null, "reconciliation_required": false }, "hash": "2/tssig+2hIBSmZyIT0CWMhsTMnRKmApc0tdWRsDs4U=", "qr_text": "20100066603|01|F001|42|36.00|236.00|2026-10-09|6|20131312955|2/tssig+2hIBSmZyIT0CWMhsTMnRKmApc0tdWRsDs4U=", "qr_image": "data:image/png;base64,iVBORw0KGgo=", "links": { "pdf": "/v1/documents/0192f1a2-7c3e-7d4b-9a8f-2b6c1d0e4f5b/pdf", "xml": "/v1/documents/0192f1a2-7c3e-7d4b-9a8f-2b6c1d0e4f5b/xml", "cdr": null }, "affected_document_id": null, "credit_note": null, "debit_note": null, "external_id": null, "replaces_document_id": null, "metadata": null, "created_at": "2026-10-09T14:03:21.482913Z", "updated_at": "2026-10-09T14:03:21.482913Z"}Factura con detracción
La respuesta es igual a la de una factura sin detracción, porque el documento no devuelve ese dato.
{ "id": "0192f1a2-7c3e-7d4b-9a8f-2b6c1d0e4f5d", "object": "document", "environment": "test", "company_id": "0192f0b1-2d4c-7a1e-8b3f-1c2d3e4f5a6b", "type": "factura", "series": "F001", "number": 43, "full_number": "F001-43", "issue_date": "2026-10-09", "currency": "PEN", "customer": { "document_type": "ruc", "document_number": "20131312955", "name": "Cliente S.A.C.", "address": null, "email": null }, "items": [ { "line_number": 1, "product_code": null, "description": "Servicio de estacionamiento mensual", "quantity": 1, "unit": "ZZ", "unit_price": 1180, "unit_value": 1000, "tax_affectation": "gravado", "igv_rate": 18, "line_value": 1000, "igv_amount": 180, "line_total": 1180 } ], "totals": { "taxable": 1000, "exempt": 0, "unaffected": 0, "discount": 0, "igv": 180, "total": 1180, "amount_in_words": "MIL CIENTO OCHENTA CON 00/100 SOLES" }, "status": "issued", "sunat_status": "pending", "delivery_status": "none", "sunat": { "response_code": null, "description": null, "notes": [], "deadline_at": "2026-10-13T04:59:59.000000Z", "submitted_at": null, "accepted_at": null, "reconciliation_required": false }, "hash": "2/tssig+2hIBSmZyIT0CWMhsTMnRKmApc0tdWRsDs4U=", "qr_text": "20100066603|01|F001|43|180.00|1180.00|2026-10-09|6|20131312955|2/tssig+2hIBSmZyIT0CWMhsTMnRKmApc0tdWRsDs4U=", "qr_image": "data:image/png;base64,iVBORw0KGgo=", "links": { "pdf": "/v1/documents/0192f1a2-7c3e-7d4b-9a8f-2b6c1d0e4f5d/pdf", "xml": "/v1/documents/0192f1a2-7c3e-7d4b-9a8f-2b6c1d0e4f5d/xml", "cdr": null }, "affected_document_id": null, "credit_note": null, "debit_note": null, "external_id": null, "replaces_document_id": null, "metadata": null, "created_at": "2026-10-09T14:05:02.771046Z", "updated_at": "2026-10-09T14:05:02.771046Z"}Cabeceras
Sección titulada «Cabeceras»El del cliente si tiene de 1 a 128 caracteres [A-Za-z0-9._-]; si no, uno generado. Es el request_id de los errores.
Solicitudes admitidas en la ventana de un minuto, de la clave o de la IP.
Solicitudes que quedan en la ventana.
Segundos hasta la ventana siguiente.
true cuando la respuesta es la guardada de una solicitud anterior con la misma Idempotency-Key.
Solicitud mal formada. Códigos: invalid_json, bad_request, idempotency_key_required, idempotency_key_invalid. No se reintenta sin corregirla.
Formato único de los errores de la API.
object
El error principal.
object
Familia del error, como validation_error, conflict o unavailable.
Código estable, para programar contra él.
Mensaje en español, apto para mostrar a un operador. Puede cambiar: no se programa contra él.
Ruta del campo en el JSON, con índices entre corchetes, como items[2].unit_price. Solo cuando el error apunta a un campo.
Identificador de la solicitud, el mismo de X-Request-Id. Inclúyelo al escribir a soporte.
Documento con el que choca la solicitud. Solo en external_id_conflict y document_already_replaced.
Todos los problemas. Solo aparece cuando hay varios.
Uno de los problemas de la solicitud.
object
Código estable, para programar contra él.
Mensaje en español, apto para mostrar a un operador.
Ruta del campo en el JSON, si el error apunta a uno.
Ejemplos
idempotency_key_required
{ "error": { "type": "bad_request", "code": "idempotency_key_required", "message": "Falta la cabecera Idempotency-Key.", "request_id": "req_0192f1a27c3e7d4b9a8f2b6c1d0e4f5a" }}Cabeceras
Sección titulada «Cabeceras»El del cliente si tiene de 1 a 128 caracteres [A-Za-z0-9._-]; si no, uno generado. Es el request_id de los errores.
Solicitudes admitidas en la ventana de un minuto, de la clave o de la IP.
Solicitudes que quedan en la ventana.
Segundos hasta la ventana siguiente.
Sin una API key válida. Códigos: unauthorized, invalid_api_key, revoked_api_key, expired_api_key.
Formato único de los errores de la API.
object
El error principal.
object
Familia del error, como validation_error, conflict o unavailable.
Código estable, para programar contra él.
Mensaje en español, apto para mostrar a un operador. Puede cambiar: no se programa contra él.
Ruta del campo en el JSON, con índices entre corchetes, como items[2].unit_price. Solo cuando el error apunta a un campo.
Identificador de la solicitud, el mismo de X-Request-Id. Inclúyelo al escribir a soporte.
Documento con el que choca la solicitud. Solo en external_id_conflict y document_already_replaced.
Todos los problemas. Solo aparece cuando hay varios.
Uno de los problemas de la solicitud.
object
Código estable, para programar contra él.
Mensaje en español, apto para mostrar a un operador.
Ruta del campo en el JSON, si el error apunta a uno.
Ejemplos
invalid_api_key
{ "error": { "type": "unauthorized", "code": "invalid_api_key", "message": "La API key no es válida.", "request_id": "req_0192f1a27c3e7d4b9a8f2b6c1d0e4f5a" }}Cabeceras
Sección titulada «Cabeceras»El del cliente si tiene de 1 a 128 caracteres [A-Za-z0-9._-]; si no, uno generado. Es el request_id de los errores.
Solicitudes admitidas en la ventana de un minuto, de la clave o de la IP.
Solicitudes que quedan en la ventana.
Segundos hasta la ventana siguiente.
La clave no puede operar. Códigos: forbidden (no tiene el scope), tenant_suspended, plan_without_api (el plan de la cuenta no incluye la API), account_not_activated (emisión en live de una cuenta que Boletura todavía no activó).
Formato único de los errores de la API.
object
El error principal.
object
Familia del error, como validation_error, conflict o unavailable.
Código estable, para programar contra él.
Mensaje en español, apto para mostrar a un operador. Puede cambiar: no se programa contra él.
Ruta del campo en el JSON, con índices entre corchetes, como items[2].unit_price. Solo cuando el error apunta a un campo.
Identificador de la solicitud, el mismo de X-Request-Id. Inclúyelo al escribir a soporte.
Documento con el que choca la solicitud. Solo en external_id_conflict y document_already_replaced.
Todos los problemas. Solo aparece cuando hay varios.
Uno de los problemas de la solicitud.
object
Código estable, para programar contra él.
Mensaje en español, apto para mostrar a un operador.
Ruta del campo en el JSON, si el error apunta a uno.
Ejemplos
forbidden
{ "error": { "type": "forbidden", "code": "forbidden", "message": "La API key no tiene el scope documents:write que exige este endpoint.", "request_id": "req_0192f1a27c3e7d4b9a8f2b6c1d0e4f5a" }}Cabeceras
Sección titulada «Cabeceras»El del cliente si tiene de 1 a 128 caracteres [A-Za-z0-9._-]; si no, uno generado. Es el request_id de los errores.
Solicitudes admitidas en la ventana de un minuto, de la clave o de la IP.
Solicitudes que quedan en la ventana.
Segundos hasta la ventana siguiente.
Conflicto con un documento existente. idempotency_in_progress se reintenta con la misma clave unos segundos después. external_id_conflict no se reintenta: document_id señala el documento existente. document_already_replaced tampoco: document_id señala el reemplazo.
Formato único de los errores de la API.
object
El error principal.
object
Familia del error, como validation_error, conflict o unavailable.
Código estable, para programar contra él.
Mensaje en español, apto para mostrar a un operador. Puede cambiar: no se programa contra él.
Ruta del campo en el JSON, con índices entre corchetes, como items[2].unit_price. Solo cuando el error apunta a un campo.
Identificador de la solicitud, el mismo de X-Request-Id. Inclúyelo al escribir a soporte.
Documento con el que choca la solicitud. Solo en external_id_conflict y document_already_replaced.
Todos los problemas. Solo aparece cuando hay varios.
Uno de los problemas de la solicitud.
object
Código estable, para programar contra él.
Mensaje en español, apto para mostrar a un operador.
Ruta del campo en el JSON, si el error apunta a uno.
Ejemplos
idempotency_in_progress
{ "error": { "type": "conflict", "code": "idempotency_in_progress", "message": "La solicitud con esta Idempotency-Key todavía se está procesando. Reintente en unos segundos.", "request_id": "req_0192f1a27c3e7d4b9a8f2b6c1d0e4f5a" }}Cabeceras
Sección titulada «Cabeceras»El del cliente si tiene de 1 a 128 caracteres [A-Za-z0-9._-]; si no, uno generado. Es el request_id de los errores.
Solicitudes admitidas en la ventana de un minuto, de la clave o de la IP.
Solicitudes que quedan en la ventana.
Segundos hasta la ventana siguiente.
payload_too_large: el cuerpo supera 256 KiB.
Formato único de los errores de la API.
object
El error principal.
object
Familia del error, como validation_error, conflict o unavailable.
Código estable, para programar contra él.
Mensaje en español, apto para mostrar a un operador. Puede cambiar: no se programa contra él.
Ruta del campo en el JSON, con índices entre corchetes, como items[2].unit_price. Solo cuando el error apunta a un campo.
Identificador de la solicitud, el mismo de X-Request-Id. Inclúyelo al escribir a soporte.
Documento con el que choca la solicitud. Solo en external_id_conflict y document_already_replaced.
Todos los problemas. Solo aparece cuando hay varios.
Uno de los problemas de la solicitud.
object
Código estable, para programar contra él.
Mensaje en español, apto para mostrar a un operador.
Ruta del campo en el JSON, si el error apunta a uno.
Ejemplos
payload_too_large
{ "error": { "type": "payload_too_large", "code": "payload_too_large", "message": "El cuerpo supera el tamaño máximo: 256 KiB, o 2 MiB al subir un certificado, un logo o un CDR.", "request_id": "req_0192f1a27c3e7d4b9a8f2b6c1d0e4f5a" }}Cabeceras
Sección titulada «Cabeceras»El del cliente si tiene de 1 a 128 caracteres [A-Za-z0-9._-]; si no, uno generado. Es el request_id de los errores.
Solicitudes admitidas en la ventana de un minuto, de la clave o de la IP.
Solicitudes que quedan en la ventana.
Segundos hasta la ventana siguiente.
unsupported_media_type: el cuerpo no llega con Content-Type: application/json.
Formato único de los errores de la API.
object
El error principal.
object
Familia del error, como validation_error, conflict o unavailable.
Código estable, para programar contra él.
Mensaje en español, apto para mostrar a un operador. Puede cambiar: no se programa contra él.
Ruta del campo en el JSON, con índices entre corchetes, como items[2].unit_price. Solo cuando el error apunta a un campo.
Identificador de la solicitud, el mismo de X-Request-Id. Inclúyelo al escribir a soporte.
Documento con el que choca la solicitud. Solo en external_id_conflict y document_already_replaced.
Todos los problemas. Solo aparece cuando hay varios.
Uno de los problemas de la solicitud.
object
Código estable, para programar contra él.
Mensaje en español, apto para mostrar a un operador.
Ruta del campo en el JSON, si el error apunta a uno.
Ejemplos
unsupported_media_type
{ "error": { "type": "unsupported_media_type", "code": "unsupported_media_type", "message": "El cuerpo debe enviarse con Content-Type application/json.", "request_id": "req_0192f1a27c3e7d4b9a8f2b6c1d0e4f5a" }}Cabeceras
Sección titulada «Cabeceras»El del cliente si tiene de 1 a 128 caracteres [A-Za-z0-9._-]; si no, uno generado. Es el request_id de los errores.
Solicitudes admitidas en la ventana de un minuto, de la clave o de la IP.
Solicitudes que quedan en la ventana.
Segundos hasta la ventana siguiente.
Datos no válidos: error.param señala el campo y errors lista todos los problemas si hay varios. El cuerpo corregido se envía con la misma Idempotency-Key, salvo en idempotency_key_reused: esa clave ya es de otra solicitud y repetirla devuelve el mismo error, así que se envía el cuerpo original o se usa una clave nueva.
Formato único de los errores de la API.
object
El error principal.
object
Familia del error, como validation_error, conflict o unavailable.
Código estable, para programar contra él.
Mensaje en español, apto para mostrar a un operador. Puede cambiar: no se programa contra él.
Ruta del campo en el JSON, con índices entre corchetes, como items[2].unit_price. Solo cuando el error apunta a un campo.
Identificador de la solicitud, el mismo de X-Request-Id. Inclúyelo al escribir a soporte.
Documento con el que choca la solicitud. Solo en external_id_conflict y document_already_replaced.
Todos los problemas. Solo aparece cuando hay varios.
Uno de los problemas de la solicitud.
object
Código estable, para programar contra él.
Mensaje en español, apto para mostrar a un operador.
Ruta del campo en el JSON, si el error apunta a uno.
Ejemplos
customer_document_required
{ "error": { "type": "validation_error", "code": "customer_document_required", "message": "Una boleta mayor a S/ 700.00 requiere identificar al cliente con un documento admitido.", "param": "customer.document_number", "request_id": "req_0192f1a27c3e7d4b9a8f2b6c1d0e4f5a" }}Cabeceras
Sección titulada «Cabeceras»El del cliente si tiene de 1 a 128 caracteres [A-Za-z0-9._-]; si no, uno generado. Es el request_id de los errores.
Solicitudes admitidas en la ventana de un minuto, de la clave o de la IP.
Solicitudes que quedan en la ventana.
Segundos hasta la ventana siguiente.
rate_limited: se superó el límite de 600 solicitudes por minuto por clave o 1200 por IP. Se reintenta después de Retry-After.
Formato único de los errores de la API.
object
El error principal.
object
Familia del error, como validation_error, conflict o unavailable.
Código estable, para programar contra él.
Mensaje en español, apto para mostrar a un operador. Puede cambiar: no se programa contra él.
Ruta del campo en el JSON, con índices entre corchetes, como items[2].unit_price. Solo cuando el error apunta a un campo.
Identificador de la solicitud, el mismo de X-Request-Id. Inclúyelo al escribir a soporte.
Documento con el que choca la solicitud. Solo en external_id_conflict y document_already_replaced.
Todos los problemas. Solo aparece cuando hay varios.
Uno de los problemas de la solicitud.
object
Código estable, para programar contra él.
Mensaje en español, apto para mostrar a un operador.
Ruta del campo en el JSON, si el error apunta a uno.
Ejemplos
rate_limited
{ "error": { "type": "rate_limited", "code": "rate_limited", "message": "Demasiadas solicitudes. Reintente después de los segundos que indica Retry-After.", "request_id": "req_0192f1a27c3e7d4b9a8f2b6c1d0e4f5a" }}Cabeceras
Sección titulada «Cabeceras»El del cliente si tiene de 1 a 128 caracteres [A-Za-z0-9._-]; si no, uno generado. Es el request_id de los errores.
Solicitudes admitidas en la ventana de un minuto, de la clave o de la IP.
Solicitudes que quedan en la ventana.
Segundos hasta la ventana siguiente.
Segundos que conviene esperar antes de reintentar.
Falla transitoria, como database_unavailable, storage_unavailable o encryption_unavailable. Se reintenta con la misma Idempotency-Key y una espera creciente.
Formato único de los errores de la API.
object
El error principal.
object
Familia del error, como validation_error, conflict o unavailable.
Código estable, para programar contra él.
Mensaje en español, apto para mostrar a un operador. Puede cambiar: no se programa contra él.
Ruta del campo en el JSON, con índices entre corchetes, como items[2].unit_price. Solo cuando el error apunta a un campo.
Identificador de la solicitud, el mismo de X-Request-Id. Inclúyelo al escribir a soporte.
Documento con el que choca la solicitud. Solo en external_id_conflict y document_already_replaced.
Todos los problemas. Solo aparece cuando hay varios.
Uno de los problemas de la solicitud.
object
Código estable, para programar contra él.
Mensaje en español, apto para mostrar a un operador.
Ruta del campo en el JSON, si el error apunta a uno.
Ejemplos
database_unavailable
{ "error": { "type": "unavailable", "code": "database_unavailable", "message": "La base de datos no está disponible. Reintente en unos segundos.", "request_id": "req_0192f1a27c3e7d4b9a8f2b6c1d0e4f5a" }}Cabeceras
Sección titulada «Cabeceras»El del cliente si tiene de 1 a 128 caracteres [A-Za-z0-9._-]; si no, uno generado. Es el request_id de los errores.
Solicitudes admitidas en la ventana de un minuto, de la clave o de la IP.
Solicitudes que quedan en la ventana.
Segundos hasta la ventana siguiente.