Emite una nota de crédito sobre un documento aceptado
curl https://api.boletura.com/v1/documents/0192f2c4-7d1e-7a3b-9c4d-5e6f7a8b9c0d/credit-notes \ --request POST \ --header 'Authorization: Bearer bol_test_TU_CLAVE' \ --header 'Idempotency-Key: 312cd9a5-d9fe-4a09-a865-dc4a87ffee2f' \ --header 'Content-Type: application/json' \ --data '{ "reason_code": "anulacion_operacion", "reason": "Anulación de la operación"}'$ch = curl_init("https://api.boletura.com/v1/documents/0192f2c4-7d1e-7a3b-9c4d-5e6f7a8b9c0d/credit-notes");
curl_setopt($ch, CURLOPT_POST, true);curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: Bearer bol_test_TU_CLAVE', 'Idempotency-Key: 312cd9a5-d9fe-4a09-a865-dc4a87ffee2f', 'Content-Type: application/json']);curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([ 'reason_code' => 'anulacion_operacion', 'reason' => 'Anulación de la operación']));
curl_exec($ch);
curl_close($ch);import http.clientimport json
conn = http.client.HTTPSConnection("api.boletura.com")
payload = json.dumps({ "reason_code": "anulacion_operacion", "reason": "Anulación de la operación"})headers = { "Authorization": "Bearer bol_test_TU_CLAVE", "Idempotency-Key": "312cd9a5-d9fe-4a09-a865-dc4a87ffee2f", "Content-Type": "application/json"}
conn.request( "POST", "/v1/documents/0192f2c4-7d1e-7a3b-9c4d-5e6f7a8b9c0d/credit-notes", 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/0192f2c4-7d1e-7a3b-9c4d-5e6f7a8b9c0d/credit-notes");request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", "bol_test_TU_CLAVE");request.Headers.TryAddWithoutValidation("Idempotency-Key", "312cd9a5-d9fe-4a09-a865-dc4a87ffee2f");request.Content = new StringContent("""{ "reason_code": "anulacion_operacion", "reason": "Anulación de la operación"}""",System.Text.Encoding.UTF8, "application/json");
using var response = await client.SendAsync(request);java.io.ByteArrayOutputStream body = new java.io.ByteArrayOutputStream();body.write("{\n \"reason_code\": \"anulacion_operacion\",\n \"reason\": \"Anulación de la operació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/0192f2c4-7d1e-7a3b-9c4d-5e6f7a8b9c0d/credit-notes")) .header("Authorization", "Bearer bol_test_TU_CLAVE") .header("Idempotency-Key", "312cd9a5-d9fe-4a09-a865-dc4a87ffee2f") .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/0192f2c4-7d1e-7a3b-9c4d-5e6f7a8b9c0d/credit-notes', { method: 'POST', headers: { Authorization: 'Bearer bol_test_TU_CLAVE', 'Idempotency-Key': '312cd9a5-d9fe-4a09-a865-dc4a87ffee2f', 'Content-Type': 'application/json' }, body: JSON.stringify({ reason_code: 'anulacion_operacion', reason: 'Anulación de la operación' })})El afectado debe ser una factura o una boleta issued, con sunat_status en accepted o accepted_with_observations (422 affected_document_not_accepted, 422 affected_document_not_supported). Ni el total ni lo gravado, lo exonerado o lo inafecto, cada uno por separado, pueden superar lo que queda del afectado después de sus notas no rechazadas (422 credit_note_exceeds_affected). El cliente y la moneda son los del afectado, y la nota va a SUNAT por el canal de este, con su plazo.
Requiere el scope documents:write.
Autorización
Sección titulada «Autorización»Parámetros
Sección titulada «Parámetros»Parámetros de la ruta
Sección titulada «Parámetros de la ruta»UUID del documento afectado. Uno que no existe en el tenant y ambiente de la clave, o que no es un UUID, responde 404 not_found.
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»Nota de crédito sobre el documento de la ruta. Una nota no lleva detracción, aunque la lleve su afectado (422 detraction_not_allowed), ni forma de pago, aunque su afectado sea al crédito (422 payment_terms_not_supported).
object
Motivo de la nota. Otro valor responde 422 credit_note_reason_invalid, y uno que no se admite sobre una boleta, 422 credit_note_reason_not_allowed.
anulacion_operacion: anulación de la operación.anulacion_error_ruc: anulación por error en el RUC.correccion_descripcion: corrección por error en la descripción.descuento_global: descuento global. No se admite sobre una boleta.descuento_item: descuento por ítem. No se admite sobre una boleta.devolucion_total: devolución total.devolucion_item: devolución por ítem.bonificacion: bonificación. No se admite sobre una boleta.disminucion_valor: disminución en el valor.otros: otros conceptos.
Descripción libre del motivo, de hasta 250 caracteres, sin saltos de línea ni tabuladores (422 field_required, 422 field_too_long, 422 field_invalid_characters).
Ítems de la nota, como en la emisión. Si se omite, la nota cubre el total del afectado con sus mismos ítems.
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).
Serie de notas de crédito, con la letra del afectado (422 credit_note_series_mismatch). Por defecto, la serie por defecto del establecimiento del afectado o, si esa no tiene su letra, la única serie activa de notas que la tenga. 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 anterior a la del afectado (422 credit_note_before_affected). No futura, y hasta hoy menos 3 días si el afectado es una factura y menos 7 si es una boleta (422 issue_date_out_of_window).
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).
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.
Ejemplos
Nota de crédito por el total
{ "reason_code": "anulacion_operacion", "reason": "Anulación de la operación"}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
Nota de crédito
{ "id": "0192f1a2-7c3e-7d4b-9a8f-2b6c1d0e4f5c", "object": "document", "environment": "test", "company_id": "0192f0b1-2d4c-7a1e-8b3f-1c2d3e4f5a6b", "type": "nota_credito", "series": "FC01", "number": 7, "full_number": "FC01-7", "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|07|FC01|7|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-2b6c1d0e4f5c/pdf", "xml": "/v1/documents/0192f1a2-7c3e-7d4b-9a8f-2b6c1d0e4f5c/xml", "cdr": null }, "affected_document_id": "0192f1a2-7c3e-7d4b-9a8f-2b6c1d0e4f5b", "credit_note": { "reason_code": "anulacion_operacion", "reason": "Anulación de la operación" }, "debit_note": null, "external_id": null, "replaces_document_id": null, "metadata": null, "created_at": "2026-10-09T15:42:10.204518Z", "updated_at": "2026-10-09T15:42:10.204518Z"}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.
not_found: no existe en el tenant y ambiente de la clave.
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
not_found
{ "error": { "type": "not_found", "code": "not_found", "message": "El documento no existe.", "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.
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
affected_document_not_accepted
{ "error": { "type": "validation_error", "code": "affected_document_not_accepted", "message": "El documento a modificar debe estar emitido y aceptado por SUNAT, con observaciones o sin ellas.", "param": "id", "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.