Generador de Facturación

Genera, firma y envía comprobantes electrónicos a SUNAT u OSE.

Endpoint de Generación

POST


                        https://api.contawebaym.com/generadorxml/api/v1/generarDEXMLV21

Paso obligatorio: autenticación

Antes de utilizar cualquier endpoint del generador, debes obtener tus credenciales en Autenticación.

Luego envía siempre: Authorization: Bearer <ACCESS_TOKEN> y Token: <TOKEN_BD>.

Cómo funciona el generadorxml

Flujo que sigue una solicitud desde la autenticación hasta la respuesta de SUNAT u OSE.

Paso 1

Autenticación

Obtén access_token y tokenBD.

Paso 2

Envía el request

Incluye Authorization, Token y el JSON.

Paso 3

GeneradorXML

Valida, genera y firma el XML.

Paso 4

SUNAT / OSE

Procesa el documento electrónico.

Paso 5

Respuesta

Recibe el estado y los archivos o un ticket.

Respuesta directa

Comprobantes, percepciones y retenciones devuelven estado, XML, PDF y CDR.

Respuesta con ticket

Guías y bajas pueden requerir una consulta posterior para obtener el resultado final.

Endpoints del generadorxml

Rutas productivas verificadas en el servicio. Abre cada operación para consultar el request de la colección.

POST Percepción

https://api.contawebaym.com/generadorxml/api/v1/generarDEXMLV21

{
  "percepcionCabecera": {
    "perSignatureId": "ContawebAym",
    "perSignatoryPartyId": "<RUC_EMISOR>",
    "perSignatoryPartyName": "<RAZON_SOCIAL_EMISOR>",
    "perDigitalSignatureUri": "ContawebAym",
    "perDocNum": "1",
    "perDocSerie": "P001",
    "perDocTipo": "40",
    "perIssueDate": "2026-10-19",
    "perIssueTime": "12:00:00",
    "perAgentPartyId": "<RUC_AGENTE>",
    "perAgentPartyTypeId": "6",
    "perAgentPartyName": "<RAZON_SOCIAL_AGENTE>",
    "perAgentPostalId": "150101",
    "perAgentStreetName": "<DIRECCION>",
    "perAgentCityName": "Lima",
    "perAgentCountrySubentity": "Lima",
    "perAgentDistrict": "Lima",
    "perAgentCountryCode": "PE",
    "perAgentRegistrationName": "<RAZON_SOCIAL_AGENTE>",
    "perReceiverPartyId": "<RUC_CLIENTE>",
    "perReceiverPartyTypeId": "6",
    "perReceiverRegistrationName": "<RAZON_SOCIAL_CLIENTE>",
    "perPerceptionSystemCode": "01",
    "perPerceptionPercent": "2.00",
    "perTotalInvoiceAmount": "100.00",
    "perTotalCashedAmount": "5000.00",
    "perCurrencyID": "PEN",
    "ambSunat": "3",
    "detalles": [{
      "pedReferenceDocTypeId": "01",
      "pedReferenceDocNum": "2",
      "pedReferenceDocSerie": "F001",
      "pedReferenceDocInvoiceAmount": "5000.00",
      "pedReferenceDocCurrencyId": "PEN",
      "pedReferenceDocIssueDate": "2026-10-18",
      "pedPaymentId": "1",
      "pedPaymentPaidAmount": "5100.00",
      "pedPaymentPaidDate": "2026-10-19",
      "pedPerceptionAmount": "100.00",
      "pedPerceptionDate": "2026-10-19",
      "pedNetTotalCashed": "5100.00",
      "pedExchangeRateSourceCurrency": "PEN",
      "pedExchangeRateTargetCurrency": "PEN",
      "pedExchangeRateCalculationRate": "1",
      "pedExchangeRateDate": "2026-10-19"
    }]
  }
}

Response — aceptado

{
  "tipocompr": "40",
  "serieCompr": "P001",
  "nroCompr": "1",
  "urlCompr": "<URL_ARCHIVOS>/<RUC>/docGenerados/<RUC>-40-P001-1.pdf",
  "estadoSunat": "0",
  "descrSunat": "<MENSAJE_SUNAT>",
  "urlXML": "<URL_ARCHIVOS>/<RUC>/docGenerados/<RUC>-40-P001-1.xml",
  "urlCDR": "<URL_ARCHIVOS>/<RUC>/docGenerados/R-<RUC>-40-P001-1.xml",
  "codRpta": "1",
  "msjRpta": "Se Proceso Correctamente"
}

POST Retención

https://api.contawebaym.com/generadorxml/api/v1/generarDEXMLV21

{
  "retencionCabecera": {
    "retSignatoryPartyId": "<RUC_EMISOR>",
    "retSignatoryPartyName": "<RAZON_SOCIAL_EMISOR>",
    "retDocNum": "28",
    "retDocSerie": "R002",
    "retDocType": "20",
    "retIssueDate": "2026-10-19",
    "retIssueTime": "00:00:00",
    "retAgentPartyId": "<RUC_AGENTE>",
    "retAgentPartyTypeId": "6",
    "retAgentPartyName": "<RAZON_SOCIAL_AGENTE>",
    "retAgentPostalId": "150118",
    "retAgentStreetName": "<DIRECCION>",
    "retAgentCityName": "Lima",
    "retAgentCountrySubentity": "Lima",
    "retAgentDistrict": "Lima",
    "retAgentCountryCode": "PE",
    "retAgentRegistrationName": "<RAZON_SOCIAL_AGENTE>",
    "retReceiverPartyId": "<RUC_PROVEEDOR>",
    "retReceiverPartyTypeId": "6",
    "retReceiverRegistrationName": "<RAZON_SOCIAL_PROVEEDOR>",
    "retRetentionSystemCode": "01",
    "retRetentionPercent": "3.00",
    "retTotalInvoiceAmount": "51.85",
    "retTotalPaidAmount": "1676.39",
    "retCurrencyID": "PEN",
    "ambSunat": "3",
    "createdBy": "<USUARIO>",
    "detalles": [{
      "redTypeDoc": "01",
      "redNumDoc": "49",
      "redSerieDoc": "FF08",
      "redTotalInvoiceAmount": 1728.24,
      "redTotalInvoiceCurrencyId": "PEN",
      "redIssueDate": "2026-10-18",
      "redPaymentId": "1",
      "redPaymentPaidAmount": 1728.24,
      "redPaymentPaidDate": "2026-10-19",
      "redRetentionCurrencyId": "PEN",
      "redRetentionAmount": "51.85",
      "redRetentionDate": "2026-10-19",
      "redNetTotalPaid": "1676.39",
      "redSourceCurrencyCode": "PEN",
      "redTargetCurrencyCode": "PEN",
      "redCalculationRate": "1.000",
      "redExchangeRateDate": "2026-10-19"
    }]
  }
}

Response — aceptado

{
  "tipocompr": "20",
  "serieCompr": "R002",
  "nroCompr": "28",
  "urlCompr": "<URL_ARCHIVOS>/<RUC>/docGenerados/<RUC>-20-R002-28.pdf",
  "estadoSunat": "0",
  "descrSunat": "<MENSAJE_SUNAT>",
  "urlXML": "<URL_ARCHIVOS>/<RUC>/docGenerados/<RUC>-20-R002-28.xml",
  "urlCDR": "<URL_ARCHIVOS>/<RUC>/docGenerados/R-<RUC>-20-R002-28.xml",
  "codRpta": "1",
  "msjRpta": "Se Proceso Correctamente"
}

POST Anulación de retención

https://api.contawebaym.com/generadorxml/api/v1/generarRDBaja2_1

{
  "ambienteSunat": "3",
  "nroDoc": "<RUC_EMPRESA>",
  "tipoDoc": "6",
  "nombreRS": "<RAZON_SOCIAL>",
  "fechaGeneracion": "2026-10-19",
  "fechaComunicacion": "2026-10-19",
  "identificador": "12072",
  "tipoBaja": "RR",
  "enviarCorreo": "0",
  "correoCliente1": "<EMAIL>",
  "listaItems": [{
    "tipoDocBaja": "20",
    "serieDocBaja": "R001",
    "nroDocBaja": "497",
    "motivoBaja": "Anulacion",
    "nroItemBaja": "1"
  }],
  "listaResumenDiario": []
}

Response — envío registrado

{
  "codRpta": "1",
  "msjRpta": "Se Proceso Correctamente nro de ticket: <TICKET_SUNAT>"
}

POST Consultar ticket SUNAT

https://api.contawebaym.com/generadorxml/api/v1/getStatusSunat

{
  "ambienteSunat": "3",
  "nroRuc": "<RUC_EMPRESA>",
  "nroTicket": "<TICKET_SUNAT>"
}

Response — procesado

{
  "codRpta": "1",
  "msjRpta": "Se Proceso Correctamente - <MENSAJE_SUNAT>"
}

POST Guía de remisión

https://api.contawebaym.com/generadorxml/api/v1/generarGuideDEXMLV21

{
  "cab": {
    "ambSunat": "3",
    "sunatTrans": "1",
    "guideElectrovTipoDoc": "09",
    "guideElectronvSerieDoc": "T002",
    "guideElectronvNroDoc": "295",
    "guideElectronvTipoDocDestinatario": "6",
    "guideElectronvNroDocDestinatario": "<RUC_DESTINATARIO>",
    "guideElectronvRazonsocialDocDestinatario": "<RAZON_SOCIAL_DESTINATARIO>",
    "guideElectronvcorreo_cliente": "<EMAIL>",
    "guideElectrontMovementDate": "2026-10-19",
    "guideElectronvstate": "0",
    "busiBident": "1",
    "idEmpleado": "01",
    "guideElectronvMtc": "",
    "guideElectronvmodalidad_traslado": "01",
    "guideElectronvCodMotivoTraslado": "01",
    "guideElectronvDescripMotivoTraslado": "VENTA",
    "documento_relacionado_codigo": "",
    "guideElectronvPesoBrutoTotal": 1.0,
    "guideElectronvUnidadBrutoTotal": "NIU",
    "guideElectronvnro_pallets": "1",
    "tipo_oper": "0111",
    "guideElectrontinicio_traslado_date": "2026-10-19",
    "guideElectronvtipo_doc_reference": "",
    "guideElectronvserienro_doc_reference": "BB04-00003344",
    "guideElectrontregistro_date": "",
    "guideElectronintegracion": "0",
    "guideElectronvempresa_pais": "PE",
    "guideElectronvPlaca": "<PLACA>",
    "guideElectronvTipoDocConductor": "6",
    "guideElectronvNroDocConductor": "<RUC_TRANSPORTISTA>",
    "guideElectronvRazonsocialDocConductor": "<RAZON_SOCIAL_TRANSPORTISTA>",
    "guideElectronvLicencia": "<LICENCIA>",
    "guideElectronvubigeo_partida": "150115",
    "guideElectronvdireccion_partida": "<DIRECCION_PARTIDA>",
    "guideElectronvubigeo_llegada": "210402",
    "guideElectronvdireccion_llegada": "<DIRECCION_LLEGADA>",
    "guideElectronvobservacion": "",
    "razonsocialEmpr": "<RAZON_SOCIAL_EMISOR>",
    "guideElectronvTipoDocTercero": "6",
    "guideElectronvRazonsocialDocTercero": "<RAZON_SOCIAL_TERCERO>",
    "guideElectronvNroDocTercero": "<RUC_TERCERO>",
    "nombrecomercialEmpr": "<NOMBRE_COMERCIAL>",
    "nrorucEmpr": "<RUC_EMISOR>",
    "tipodocEmpr": "6",
    "guideElectronvMarca": "",
    "integracion": "1",
    "enviarCorreoCliente": "1",
    "enviarSunat": "1"
  },
  "items": [{
    "guideElectronvnro_subpartida_nacional": "",
    "guideElectroBident": "1",
    "detguideelectron_vnro_item": "1",
    "detguideelectron_vcod_item": "<CODIGO_ITEM>",
    "detguideelectron_vdescripcion_item": "<DESCRIPCION>",
    "detguideelectron_vcantidad_item": "12.00",
    "detguideelectron_vunimed_item": "NIU",
    "detguideelectron_vregister_date": "2026-10-19",
    "store_bident": "",
    "detguideelectron_vpeso": "1",
    "detguideelectron_vcantidadxpeso": "0",
    "detguideelectron_vobservacion_item": ""
  }],
  "clientId": "<CLIENT_ID_SUNAT>",
  "clientSecret": "<CLIENT_SECRET_SUNAT>",
  "username": "<USUARIO_SOL>",
  "password": "<CLAVE_SOL>"
}

Response — envío recibido por SUNAT

{
  "tipocompr": "09",
  "serieCompr": "T002",
  "nroCompr": "295",
  "urlCompr": "<URL_ARCHIVOS>/<RUC>/docGenerados/<RUC>-09-T002-295.pdf",
  "estadoSunat": "0",
  "descrSunat": "<MENSAJE_SUNAT>",
  "urlXML": "<URL_ARCHIVOS>/<RUC>/docGenerados/<RUC>-09-T002-295.xml",
  "urlCDR": "<URL_ARCHIVOS>/<RUC>/docGenerados/R-<RUC>-09-T002-295.xml",
  "nroTicket": "<TICKET_SUNAT>",
  "tokenSunat": "<TOKEN_SUNAT>",
  "pathFile": "<RUTA_CDR>",
  "codRpta": "0",
  "msjRpta": "<NOTA_SUNAT>"
}

GET Consultar ticket de guía

https://api.contawebaym.com/generadorxml/api/v1/consultaTicket

curl --request GET \
  --url "https://api.contawebaym.com/generadorxml/api/v1/consultaTicket?tokenSunat=<TOKEN_SUNAT>&ticket=<TICKET>&pathFile=<RUTA_ARCHIVO>&rucEmpresa=<RUC>&serieDoc=<SERIE>&nroDoc=<NUMERO>" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer <ACCESS_TOKEN>" \
  --header "Token: <TOKEN_BD>"

Response — estado del CDR

{
  "codRpta": "0",
  "msjRpta": "<MENSAJE_SUNAT>",
  "estadoCdr": "0",
  "descrSunat": "<NOTA_SUNAT>"
}

Ambiente SUNAT de la empresa

Consulta el ambiente configurado antes de emitir. El cambio se aplica a la empresa autenticada.

BETA

Pruebas SUNAT. COD_SUNAT = 1.

PRODUCCION

Envío real a SUNAT. COD_SUNAT = 3.

OSE_PRODUCCION

Envío real por Nubefact. COD_SUNAT = 4.

Código 2 no disponible

COD_SUNAT = 2 no está operativo. No lo utilices.

Usa series exclusivas para pruebas

En BETA usa una serie y un correlativo exclusivos, por ejemplo F099 o B099.

Nunca reutilices una serie real ni alternes la misma serie entre BETA y PRODUCCIÓN. Las pruebas pueden consumir correlativos internos y afectar la serie productiva.

Flujo recomendado

Consulta el ambiente con GET.
Si corresponde, cámbialo con PATCH y vuelve a verificarlo.
Genera el comprobante con una serie adecuada para ese ambiente.

1. Consultar el ambiente actual

GET


                        https://api.contawebaym.com/operacion/api/v1/admin/empresas/{ruc}/ambiente-sunat

cURL — Consulta

curl --request GET \
  --url "https://api.contawebaym.com/operacion/api/v1/admin/empresas/20123456789/ambiente-sunat" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer <ACCESS_TOKEN>" \
  --header "Token: <TOKEN_BD>"

2. Cambiar el ambiente

PATCH


                        https://api.contawebaym.com/operacion/api/v1/admin/empresas/{ruc}/ambiente-sunat

El RUC debe coincidir con el token.

cURL — Cambio de ambiente

curl --request PATCH \
  --url "https://api.contawebaym.com/operacion/api/v1/admin/empresas/20123456789/ambiente-sunat" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer <ACCESS_TOKEN>" \
  --header "Token: <TOKEN_BD>" \
  --header "Content-Type: application/json" \
  --data '{
    "ambiente": "BETA",
    "motivo": "Pruebas de retención para incidencia 1234"
  }'

Respuesta del cambio

JSON — 200 OK

{
  "ruc": "20123456789",
  "ambiente": "BETA",
  "codigoSunat": "1",
  "ambienteAnterior": "PRODUCCION",
  "codigoAnterior": "3",
  "modificado": true,
  "motivo": "Pruebas de retención para incidencia 1234",
  "actualizadoPor": "usuario_api"
}

Código HTTP	Qué revisar
400	RUC, ambiente o motivo inválido.
401	Access token ausente, vencido o inválido.
403	El RUC no pertenece al token o falta el permiso `write`.
404	La empresa no tiene un parámetro activo `COD_SUNAT`.
409	`COD_SUNAT` contiene un valor no admitido. Solo se aceptan `1`, `3` y `4`; el código `2` no está operativo.

Estructura del Payload (JSON)

El envío de un comprobante a SUNAT requiere más de 60 parámetros en total. Para facilitar su comprensión, los hemos agrupado lógicamente. Todos los campos pertenecen al objeto cab a menos que se indique que son arreglos (items o cuotas).

1. Datos del Documento (Cabecera)

Campo	Descripción
cab.docu_tipodocumento	Código SUNAT del comprobante. Los más comunes son: `01`: Factura `03`: Boleta de Venta `07`: Nota de Crédito `08`: Nota de Débito
cab.docu_serie	Serie del comprobante (Ej. `F001`, `BB04`).
cab.docu_numero	Correlativo del documento (Ej. `00002816`).
cab.docu_fecha_emision	Fecha en formato `YYYY-MM-DD`.
cab.docu_moneda	Código internacional (`PEN`, `USD`).

2. Datos de Emisor y Cliente

Campo	Descripción
cab.empr_nroruc	RUC de la empresa emisora.
cab.clie_tipodoc	Tipo de documento del cliente (Ej. `1`=DNI, `6`=RUC).
cab.clie_numero	Número de documento del cliente.

3. Importes y Totales

cab.docu_total_gravada	Sumatoria de ítems gravados con IGV.
cab.docu_total_exonerada	Sumatoria de ítems exonerados (Ej. tipo 20).
cab.docu_total_igv	Monto total del IGV calculado.
cab.docu_total	Monto final a cobrar. Debe cuadrar con la suma de gravada + inafecta + exonerada + IGV + cargos.

4. Arrays de Detalle

items [ ]	Arreglo de productos/servicios. Cada objeto debe incluir: `item_unidad_medida` (Ej. NIU), `item_cantidad`, `item_valor_unitario` y `item_tipo_igv`. *Nota: Si el ítem es exonerado, el tipo de IGV suele ser "20".
cuotas [ ]	Define la forma de pago (`Contado` o a crédito con sus respectivas cuotas).

Ejemplo

El envío es simple, este es un ejemplo de la generación de una factura electrónica con sus respectivos items.

{
  "cab": {
    "tipo_oper": "0101",
    "docu_tipodocumento": "03",
    "docu_fecha_emision": "2026-06-23",
    "docu_hora_emision": "18:05:11",
    "docu_serie": "B099",
    "docu_numero": "00000001",
    "sunatTrans": "1",
    "docu_fecha_venc": "2026-06-23",
    "docu_moneda": "PEN",
    "docu_tipo_cambio": "1.000",
    "docu_porc_igv": "0.18",
    "docu_dscto_global": "0.00",
    "docu_total_anticipo": "0",
    "docu_total_gravada": "0.00",
    "docu_total_inafecta": "0.00",
    "docu_total_exonerada": "150.00",
    "docu_total_igv": "0.00",
    "docu_total_gratuita": "0.00",
    "docu_total_otros_cargos": "0.00",
    "docu_total_otros_atrib": "0.00",
    "docu_total": "150.00",
    "docu_tipo_percep": "",
    "docu_total_percepcion": "",
    "docu_mot_dcto": "00",
    "docu_observaciones": "",
    "enviarSunat": "1",
    "enviarCorreoCliente": "0",
    "ambSunat": "4",
    "clie_numero": "47730675",
    "clie_tipodoc": "1",
    "clie_nombre": "ORTEGA RAMOS RAUL REYNALDO",
    "clie_direccion": "",
    "empr_razonsocial": "INVERSIONES PIANDA S.A.C.",
    "empr_nombrecomercial": "AP Games",
    "empr_direccion": "Av. Paseo de la Republica Nro. 475 Int. 13",
    "empr_provincia": "LIMA",
    "empr_departamento": "LIMA",
    "empr_distrito": "La Victoria",
    "empr_pais": "PE",
    "empr_nroruc": "20609359651",
    "empr_tipodoc": "6",
    "empr_codEstb": "0000",
    "formaPago": "1",
    "tipo_oper_cw": "1",
    "validacionIgv": "18.00",
    "validacionGratuita": "0"
  },
  "items": [
    {
      "cod_item": "1",
      "item_unidad_medida": "NIU",
      "item_codigo": "045496905019",
      "item_descr": "SW DONKEY KONG RETURN HD",
      "item_cantidad": "1.00",
      "item_valor_unitario": "150.0000000000",
      "item_precio_unitario": "150.00",
      "item_pnohonerosa": "0.00",
      "item_subTota": "150.00",
      "item_tipo_igv": "20",
      "item_igv": "0.00",
      "item_total": "150.00",
      "item_antic_regula": "0",
      "item_tasa_igv": "0.18",
      "item_name_short": "",
      "item_precio_descr": "1",
      "item_moneda_descr": "20",
      "item_name_marca": "",
      "item_inclu_igv": "false",
      "item_igv_unitario": "0.00",
      "item_total_neto": "150.00",
      "item_indicator": "20",
      "item_dcto": "150.00",
      "item_dcto_igv": "0.00",
      "item_dcto_total": "0.00",
      "item_impor_dcto": "0.00",
      "item_cod_cargodescuento": "",
      "item_multiplicador_descuento": "0.00",
      "item_indicador_cargodescuento": "false",
      "item_valor_base": "150.0000000000",
      "item_valor_base_cantidad": "150.00"
    }
  ],
  "cuotas": [
    {
      "formaPagoID": "FormaPago",
      "tipoFormaPaymentID": "Contado",
      "amountID": "150.00"
    }
  ]
}

curl --request POST \
  --url "https://api.contawebaym.com/generadorxml/api/v1/generarDEXMLV21" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer <ACCESS_TOKEN>" \
  --header "Token: <TOKEN_BD>" \
  --header "Content-Type: application/json" \
  --data-binary "@payload.json"

{
  "tipocompr": "03",
  "serieCompr": "B099",
  "nroCompr": "00000001",
  "urlCompr": "https://contawebaym.com/files_gen/20102030405/docGenerados/20102030405-03-B099-00000001.pdf",
  "estadoSunat": "0",
  "descrSunat": "La Boleta de Venta numero B099-00000001 ha sido aceptada",
  "urlXML": "https://contawebaym.com/files_gen/20102030405/docGenerados/20102030405-03-B099-00000001.xml",
  "urlCDR": "https://contawebaym.com/files_gen/20102030405/docGenerados/R-20102030405-03-B099-00000001.xml",
  "codRpta": "1",
  "msj": "Se Proceso Correctamente"
}

TIP

También puedes consultar nuestras preguntas frecuentes y listado de errores para saber el significado de cada código que responde la SUNAT y cómo manejar un documento rechazado u observado.