ES | EN

Ejemplos por país

⚠️ Errores comunes

Esta guía lista errores frecuentes en Perú tal como aparecen en la API Koywe / FACTO cuando el envío a OSE/SUNAT falla y el objeto result llega con status: 2.

Formato común de result (status 2)

"result": {
  "status": 2,
  "error_message": "Document generated but could not be sent to the Tax bureau - <texto exacto de la(s) alerta(s)> - "
}

Origen del texto tras el prefijo fijo Document generated but could not be sent to the Tax bureau -:

  • Casi todos los mensajes: cadenas literales en module/facto/.../DocumentsMapperPeru.php (vía Alertas::AgregarAlerta).
  • Único caso E-Fact acordado en esta documentación: 1033 con description debajo (sección 1).

1) Único caso E-Fact (OSE) – uso actual

El código 1033 es un rechazo frecuente del OSE cuando el comprobante no puede registrarse como se envió; el detalle concreto viene en la parte description : del mensaje. Un caso habitual es que el número de comprobante o los datos ya existan registrados con otra información.

"result": {
  "status": 2,
  "error_message": "Document generated but could not be sent to the Tax bureau - Error : 1033 - description : El comprobante fue registrado previamente con otros datos. - "
}

El texto tras description : lo devuelve el OSE; el ejemplo anterior es representativo.

2) Validación de cabecera (muy frecuente)

Antes del envío a OSE se validan los datos obligatorios de cabecera (emisor, receptor cuando el tipo lo exige, fecha de emisión, etc.). Si falta un campo requerido, el mensaje suele seguir el patrón The field '…' is required and cannot be empty.

2.1) issue_date

La fecha de emisión del comprobante debe ir en la cabecera del documento como issue_date. Si falta la clave, viene vacía (""), es null o no es una fecha válida para el validador, el flujo se detiene antes del envío a OSE y verás este mensaje.

Revisa: que en el JSON de creación (bloque header o equivalente según tu integración) exista issue_date con el formato de fecha que exige la API (habitualmente YYYY-MM-DD). Comprueba también que no la estés enviando solo en otro campo (por ejemplo una fecha genérica sin mapear a issue_date).

"result": {
  "status": 2,
  "error_message": "Document generated but could not be sent to the Tax bureau - Error : The field 'issue_date' is required and cannot be empty. - "
}

2.2) Emisor

Los datos del vendedor van con prefijo *`issuer_** en la cabecera (RUC, tipo de documento, razón social, dirección, distrito, departamento, ciudad, país, teléfono, actividad económica, etc.). El texto del error cita **un** campo; el ejemplo usa **issuer_tax_id_code**, pero el **mismo patrón** aplica aissuer_tax_id_type,issuer_legal_name,issuer_address,issuer_district,issuer_department,issuer_city,issuer_country_id,issuer_phone,issueractivityy otrosissuer*` obligatorios para tu tipo de comprobante.

Revisa: que ningún valor obligatorio vaya vacío o null, que el RUC tenga el largo correcto y que dirección y ubigeo coincidan con lo exigido para Perú.

"result": {
  "status": 2,
  "error_message": "Document generated but could not be sent to the Tax bureau - Error : The field 'issuer_tax_id_code' is required and cannot be empty. - "
}

2.3) Receptor (documentos que exigen receptor completo)

En facturas, notas y otros documentos donde el receptor debe ir completo, los campos usan el prefijo *`receiver_**. Si falta un dato obligatorio del cliente, el error indica el campo concreto (por ejemplo **receiver_tax_id_code**,receiver_legal_name`, dirección, etc.).

Revisa: tipo y número de documento del receptor, razón social o nombre, y domicilio fiscal cuando el tipo de comprobante lo requiera.

"result": {
  "status": 2,
  "error_message": "Document generated but could not be sent to the Tax bureau - Error : The field 'receiver_tax_id_code' is required and cannot be empty. - "
}

3) Secuencia / serie (frecuente)

La serie (document_sequence_code) y el correlativo deben ser coherentes con la configuración en FACTO y con SUNAT. Los casos siguientes son los más habituales al crear el documento.

3.1) Varias series sin document_sequence_code

Hay más de una serie configurada para el mismo document_type_id y la petición no indica cuál serie usar. El backend no elige una por defecto en ese escenario.

Revisa: envía siempre document_sequence_code (por ejemplo F001, B001) cuando existan varias secuencias para ese tipo.

"result": {
  "status": 2,
  "error_message": "Document generated but could not be sent to the Tax bureau - Error : There is more than one sequence for this document type and no document_sequence_code was provided. - "
}

3.2) Sin secuencia en BD para tipo sin default

No existe ninguna secuencia en base de datos para ese tipo de documento y el tipo no tiene serie por defecto generada automáticamente. Sin filas en do_sequence (o equivalente) no se puede continuar.

Revisa: que en la cuenta exista al menos una serie autorizada para ese document_type_id antes de emitir; crea o activa la serie en FACTO si hace falta.

"result": {
  "status": 2,
  "error_message": "Document generated but could not be sent to the Tax bureau - Error : There is no sequence for this document type on database - "
}

3.3) Serie nueva creada (alerta informativa)

El document_sequence_code enviado no existía para ese tipo de documento y el sistema creó la serie (suele iniciar correlativo en 1). El aviso puede ir solo o concatenado con otros textos en error_message. El código F002 es solo ejemplo; el mensaje real repite el código que mandaste.

Si era intencional (nueva serie), normalmente no requiere acción. Si no querías crear serie, corrige el código o la configuración en FACTO.

"result": {
  "status": 2,
  "error_message": "Document generated but could not be sent to the Tax bureau - The sequence code F002 did not exist for this document type. It was created with document_number 1 - "
}

4) Notas de crédito / referencias (frecuente si usas NC)

Las notas de crédito deben referenciar al documento afectado con el document_type_id correcto en la referencia: la 98 (NC sobre factura) exige referencia con tipo 96 (factura); la 155 (NC sobre boleta) exige referencia con tipo 97 (boleta). Si mezclas tipos, el validador responde con estos mensajes.

Revisa: bloque de referencias (references o el nombre que use tu payload), identificadores del documento original y que el document_type_id de la referencia coincida con la NC emitida.

"result": {
  "status": 2,
  "error_message": "Document generated but could not be sent to the Tax bureau - Error : If the issued document is 98 (Credit Note for Invoice), the reference must have document_type_id = 96 (Invoice). If the issued document is 155 (Credit Note for Receipt), the reference must have document_type_id = 97 (Receipt) - "
}
"result": {
  "status": 2,
  "error_message": "Document generated but could not be sent to the Tax bureau - Error : If the issued document is 155 (Credit Note for Receipt), the reference must have document_type_id = 97 (Receipt) - "
}

5) Guía de remisión (document_type_id = 100)

Las guías de remisión (document_type_id = 100) exigen códigos SUNAT válidos. handling_code indica el motivo o tipo de traslado; transport_mode_code indica si el transporte es público (01) o privado (02). Valores fuera de catálogo o campos omitidos generan los errores siguientes.

Revisa: tablas SUNAT vigentes para guías y que ambos campos vayan informados según el contrato del endpoint.

"result": {
  "status": 2,
  "error_message": "Document generated but could not be sent to the Tax bureau - Error: the values for the field handling_code must be '01', '02', '04' or '13'. - "
}
"result": {
  "status": 2,
  "error_message": "Document generated but could not be sent to the Tax bureau - The field handling_code is mandatory for document_type_id = 100. - "
}
"result": {
  "status": 2,
  "error_message": "Document generated but could not be sent to the Tax bureau - The values for the field transport_mode_code must be '01' (Public transport) or '02'(Private transport) - "
}

6) Impuestos / decimales (frecuente en totales)

Los importes de impuestos (por línea o agregados) no pueden superar dos decimales. Suele ocurrir por redondeo incorrecto o por enviar IGV/ISC con demasiadas cifras decimales.

Revisa: normalizar a 2 decimales antes del POST; conviene alinear con la guía de Redondeo.

"result": {
  "status": 2,
  "error_message": "Document generated but could not be sent to the Tax bureau - Error : taxes cannot have more than 2 decimal places. - "
}

7) Plantilla / PDF (POST con plantilla)

Si pides generar PDF con una plantilla (identificador o código en la cuenta) y esa plantilla no existe o no está disponible para el usuario, falla la generación. El segundo mensaje indica que el PDF no se generó en la misma respuesta y que debes obtenerlo con GET cuando el procesamiento termine (flujo asíncrono).

Revisa: id/código de plantilla, que la plantilla esté cargada en la cuenta y la documentación del endpoint para recuperar el PDF.

"result": {
  "status": 2,
  "error_message": "Document generated but could not be sent to the Tax bureau - No se encontró la plantilla en la base de datos - "
}
"result": {
  "status": 2,
  "error_message": "Document generated but could not be sent to the Tax bureau - PDF no fue generado, favor utilizar GET para recuperar PDF - "
}

Referencias útiles