Documentación API

DOCUMENTACIÓN TÉCNICA OFICIAL

Referencia de Integración API NexaFact

La API RESTful de NexaFact automatiza la conexión directa entre tu plataforma externa (ERP, POS, SaaS, E-Commerce) y la infraestructura tributaria peruana SUNAT/OSE, garantizando la emisión legal síncrona en milisegundos bajo el estándar UBL 2.1.

Autenticación por EmpresaHeader x-api-key

Estándar y ProtocoloJSON UBL 2.1 SUNAT / OSE

Capacidades de la Plataforma

Emisión Inmediata: Procesamiento en tiempo real con firma digital y generación de archivos PDF, XML y CDR.

Homologación ERP: Mapeo flexible de equivalencias para conectar cualquier estructura de base de datos sin alterar tu sistema.

Descargas Masivas: Exportación automatizada de comprobantes comprimidos en formato .zip por rangos de fecha.

Alta Disponibilidad: Arquitectura resiliente con conmutación SUNAT / OSE de respuesta 24/7.

Gestión de Equivalencias Externas (Mapeo ERP / POS)

Permite administrar el CRUD completo para homologar códigos o IDs entre tu sistema externo (ERP, CRM, POS) y el facturador (typeDocs, typeCoins, identityDocuments, branches, units, detractionTypes, paymentMethods, operationTypes, creditNoteReason).

POST/api/externalEquivalences

Campo	Tipo	Requerido	Descripción & Uso
entityType	string	Sí	Entidad a mapear ("typeDocs", "typeCoins", "identityDocuments", "branches", "units", "detractionTypes", "paymentMethods", "operationTypes", "creditNoteReason".).
externalId	number	Sí	ID numérico que maneja tu sistema externo.
internalId	number	Sí	ID del catálogo interno en la API de Facturación.
description	string	Opcional	Nota descriptiva del mapeo.

Petición POST /api/externalEquivalences

curl -X POST "https://{url}/api/externalEquivalences" \
  -H "Content-Type: application/json" \
  -H "x-api-key: TU_API_KEY_AQUI" \
  -d '{"entityType":"typeDocs","externalId":101,"internalId":1,"description":"Factura Venta en Sistema ERP Externo","isActive":true}'

Respuesta HTTP 201 Created

{
  "message": "Equivalencia Externa registrado correctamente.",
  "data": {
    "id": 15,
    "companyId": 2,
    "entityType": "typeDocs",
    "externalId": 101,
    "internalId": 1,
    "description": "Factura Venta en Sistema ERP Externo"
  }
}

GET/api/externalEquivalences

Retorna todas las equivalencias de la empresa. Puedes filtrar agregando el parámetro query ?entityType=typeDocs o consultar un registro por su ID GET /api/externalEquivalences/15.

Respuesta HTTP 200 OK (Listado)

{
  "message": "Listado de equivalencias obtenido correctamente.",
  "data": [
    {
      "id": 15,
      "companyId": 2,
      "entityType": "typeDocs",
      "externalId": 101,
      "internalId": 1,
      "description": "Factura Venta en Sistema ERP Externo",
      "isActive": true
    },
    {
      "id": 16,
      "companyId": 2,
      "entityType": "typeCoins",
      "externalId": 201,
      "internalId": 1,
      "description": "Soles en Sistema POS",
      "isActive": true
    }
  ]
}

PUT/api/externalEquivalences/{id}

Petición PUT /api/externalEquivalences/15

curl -X PUT "https://{url}/api/externalEquivalences/15" \
  -H "Content-Type: application/json" \
  -H "x-api-key: TU_API_KEY_AQUI" \
  -d '{"entityType":"typeDocs","externalId":101,"internalId":1,"description":"Factura Venta Actualizada en ERP","isActive":true}'

Respuesta HTTP 200 OK (Actualizado)

{
  "message": "Equivalencia Externa actualizada correctamente.",
  "data": {
    "id": 15,
    "companyId": 2,
    "entityType": "typeDocs",
    "externalId": 101,
    "internalId": 1,
    "description": "Factura Venta Actualizada en ERP",
    "isActive": true
  }
}

DELETE/api/externalEquivalences/{id}

Petición HTTP DELETE

DELETE /api/externalEquivalences/15

Respuesta HTTP 200 OK

{ "message": "Equivalencia eliminada correctamente" }

POST/api/vouchers

Emisión de Factura / Boleta Electrónica

Emite Facturas (01) o Boletas de Venta (03). La API realiza automáticamente el cálculo de impuestos IGV, generación de XML UBL 2.1, firma digital y la transmisión a SUNAT/OSE.

Importante: Homologación via Equivalencias Externas

Los campos typeDocId, operationTypeId, typeCoinId, client.identityDocumentId, details[].unitId, details[].detractionTypeId y detraction.paymentMethodId aceptan valores enteros (number) correspondientes a los IDs originales que maneja tu sistema externo (ERP / POS). Por ello, es fundamental armar primero las equivalencias externas en la sección Mapeo ERP / POS para que el facturador homologue automáticamente los datos sin necesidad de realizar conversiones manuales en tu sistema.

Parámetros de Petición (Request Body)

Campo	Tipo	Requerido	Descripción
typeDocId	number	Sí	ID del tipo de comprobante en tu ERP/POS (Ej: 1 = Factura, 2 = Boleta). Homologado via equivalencias.
operationTypeId	number	Sí	ID del tipo de operación en tu ERP/POS (Ej: 1 = Venta interna). Homologado via equivalencias.
issueDate	string	Sí	Fecha y hora de emisión en formato ISO 8601 (YYYY-MM-DDTHH:mm:ss).
typeCoinId	number	Sí	ID de la moneda en tu ERP/POS (Ej: 1 = Soles PEN, 2 = Dólares USD). Homologado via equivalencias.
exchangeRate	number	No	Tipo de cambio. Usar 1 si la moneda es PEN.
voucherNumber	string	No	Número de comprobante (Ej: F001-00000123). Si se omite, el sistema lo genera automáticamente.
paymentTerms.type	string	No	Condición de pago. Valores: "contado" \| "credito".
client — Datos del Cliente / Adquirente
client.numDoc	string	Sí	Número de RUC o DNI del cliente.
client.name	string	Sí	Razón social o nombre completo del adquirente.
client.identityDocumentId	number	Sí	ID del tipo de documento de identidad (Ej: 1 = RUC, 2 = DNI). Homologado via equivalencias.
client.address	string	No	Dirección del adquirente.
client.email	string	No	Email del adquirente (se usa para envío del comprobante).
client.phone	string	No	Teléfono del adquirente.
client.districtId	number	No	ID del distrito del adquirente según catálogo del sistema.
client.provinceId	number	No	ID de la provincia del adquirente según catálogo del sistema.
client.departmentId	number	No	ID del departamento del adquirente según catálogo del sistema.
details[] — Líneas del comprobante
details[].id	number	No	ID interno del ítem en tu ERP/POS (referencia externa).
details[].description	string	Sí	Descripción del bien o servicio.
details[].unitPrice	number	Sí	Precio unitario del bien o servicio (sin IGV si es gravado).
details[].quantity	number	Sí	Cantidad de unidades del ítem.
details[].discountAmount	number \| null	No	Monto de descuento aplicado al ítem. Enviar null si no aplica.
details[].isIgvExempt	boolean	Sí	true si el ítem está exonerado de IGV.
details[].isInafecto	boolean	Sí	true si el ítem está inafecto al IGV.
details[].unitId	number	Sí	ID de la unidad de medida en tu ERP/POS (Ej: 1 = Unidad NIU). Homologado via equivalencias.
details[].detractionTypeId	number \| null	No	ID del tipo de detracción si aplica. Enviar null si no aplica.
observation	string \| null	No	Observaciones o glosa del comprobante. Enviar null si no aplica.
detraction — Detracción (solo si la operación es sujeta a detracción)
detraction.paymentMethodId	number	Condicional	ID del método de pago de la detracción según catálogo del sistema. Solo se envía cuando la operación está sujeta a detracción; omitir el objeto completo si no aplica.

Cuerpo de la Petición (JSON)

{
  "typeDocId": 1,
  "operationTypeId": 1,
  "issueDate": "2026-08-12T10:30:00",
  "typeCoinId": 1,
  "exchangeRate": 1,
  "voucherNumber": "F001-00000123",
  "paymentTerms": {
    "type": "contado"
  },
  "client": {
    "numDoc": "20123456789",
    "name": "EMPRESA DEMO S.A.C.",
    "identityDocumentId": 1,
    "address": "Av. Principal 123, Lima",
    "email": "facturacion@empresa.com",
    "phone": "014567890",
    "districtId": 1501,
    "provinceId": 150,
    "departmentId": 15
  },
  "details": [
    {
      "id": 1,
      "description": "SERVICIO DE CONSULTORIA",
      "unitPrice": 1000,
      "discountAmount": null,
      "quantity": 1,
      "isIgvExempt": false,
      "isInafecto": false,
      "unitId": 1,
      "detractionTypeId": null
    }
  ],
  "observation": null,
  "detraction": {
    "paymentMethodId": 1
  }
}

Ejemplo de Solicitud (Código)

curl -X POST "https://{url}/api/vouchers" \
  -H "Content-Type: application/json" \
  -H "x-api-key: TU_API_KEY_AQUI" \
  -d '{"typeDocId":1,"operationTypeId":1,"issueDate":"2026-08-12T10:30:00","typeCoinId":1,"exchangeRate":1,"voucherNumber":"F001-00000123","paymentTerms":{"type":"contado"},"client":{"numDoc":"20123456789","name":"EMPRESA DEMO S.A.C.","identityDocumentId":1,"address":"Av. Principal 123, Lima","email":"facturacion@empresa.com","phone":"014567890","districtId":1501,"provinceId":150,"departmentId":15},"details":[{"id":1,"description":"SERVICIO DE CONSULTORIA","unitPrice":1000,"discountAmount":null,"quantity":1,"isIgvExempt":false,"isInafecto":false,"unitId":1,"detractionTypeId":null}],"observation":null,"detraction":{"paymentMethodId":1}}'

Respuesta HTTP 201 Created

{
  "success": true,
  "message": "Comprobante creado y procesado correctamente.",
  "data": {
    "id": 142,
    "series": "F001",
    "correlative": "00000045",
    "sunatStatus": "ACCEPTED",
    "sunatDescription": "La Factura numero F001-00000045 ha sido aceptada",
    "pdfUrl": "https://api.tudominio.com/api/vouchers/142/pdf",
    "xmlUrl": "https://api.tudominio.com/api/vouchers/142/xml",
    "cdrUrl": "https://api.tudominio.com/api/vouchers/142/cdr"
  }
}

POST/api/vouchers

Emisión de Nota de Crédito Electrónica

Emite Notas de Crédito (07) vinculadas a comprobantes emitidos previamente para anular o corregir montos.

Parámetros de Petición (Nota de Crédito)

Campo	Tipo	Requerido	Descripción & Motivos SUNAT
tipoDoc	number (Entero)	Sí	ID entero del tipo de comprobante Nota de Crédito (ej: 3).
issueDate	string	Sí	Fecha y hora de emisión en formato ISO 8601 (YYYY-MM-DDTHH:mm:ss).
creditNoteReasonId	number	Sí	ID del tipo de razón en tu ERP/POS (Ej: 1 = Anulación de la operación). Homologado via equivalencias.
voucherNumber	string	Sí	Número de comprobante (Ej: F001-00000123). Si se omite, el sistema lo genera automáticamente.
affectedDocumentNumber	string	Sí	Serie y correlativo del comprobante afectado (Ej. "F001-00000045").
reasonDescription	string	Sí	Descripción explicativa del motivo.

Cuerpo de la Petición (JSON)

{
  "typeDocId": 3,
  "issueDate": "2026-08-13T01:30:24",
  "creditNoteReasonId": 1,
  "voucherNumber": "BC02-00000009",
  "affectedDocumentNumber": "B002-00000030",
  "reasonDescription": "Anulación de la operación por error en el RUC"
}

Petición Nota de Crédito

curl -X POST "https://{url}/api/vouchers" \
  -H "Content-Type: application/json" \
  -H "x-api-key: TU_API_KEY_AQUI" \
  -d '{"typeDocId":3,"issueDate":"2026-08-13T01:30:24","creditNoteReasonId":1,"voucherNumber":"BC02-00000009","affectedDocumentNumber":"B002-00000030","reasonDescription":"Anulación de la operación por error en el RUC"}'

Respuesta HTTP 201 Created

{
  "success": true,
  "message": "Comprobante creado y procesado correctamente.",
  "data": {
    "id": 142,
    "series": "F001",
    "correlative": "00000045",
    "sunatStatus": "ACCEPTED",
    "sunatDescription": "La Factura numero F001-00000045 ha sido aceptada",
    "pdfUrl": "https://api.tudominio.com/api/vouchers/142/pdf",
    "xmlUrl": "https://api.tudominio.com/api/vouchers/142/xml",
    "cdrUrl": "https://api.tudominio.com/api/vouchers/142/cdr"
  }
}

POST/api/vouchers/{voucherNumber}/void

Anulación / Comunicación de Baja

Transmite la Comunicación de Baja oficial a SUNAT para invalidar un comprobante emitido previamente.

Reglas de Validación del Sistema

El comprobante debe tener estado sunatStatus = "ACCEPTED".
No debe haber sido anulado previamente.
La fecha de emisión debe estar dentro del plazo legal límite SUNAT.

Cuerpo de la Petición (JSON)

{
  "reason": "Anulacion solicitada por el cliente por duplicidad de comprobante"
}

Petición de Baja

curl -X POST "https://{url}/api/vouchers/{voucherNumber}/void" \
  -H "Content-Type: application/json" \
  -H "x-api-key: TU_API_KEY_AQUI" \
  -d '{"reason":"Anulacion solicitada por el cliente por duplicidad de comprobante"}'

Respuesta HTTP 200 OK

{
  "success": true,
  "message": "Proceso de anulacion iniciado. El estado se actualizara en unos momentos.",
  "voidSunatStatus": "PENDING"
}

GET/api/vouchers/downloadZip

Descarga Masiva de Comprobantes en ZIP por Rango de Fechas

Permite descargar en un único archivo comprimido (.zip) los archivos digitales (PDF y XML) de todos los comprobantes emitidos en un rango de fechas determinado para tu empresa.

Parámetros Query (Obligatorios)

Parámetro	Tipo	Formato	Descripción & Reglas
startDate	string	YYYY-MM-DD	Fecha inicial del rango de búsqueda.
endDate	string	YYYY-MM-DD	Fecha final del rango de búsqueda (endDate >= startDate).

Ejemplo de Solicitud (GET)

curl -X GET "https://{url}/api/vouchers/downloadZip?startDate=2026-08-01&endDate=2026-08-12" \
  -H "x-api-key: TU_API_KEY_AQUI"

Respuestas del Sistema

200 OK: Descarga Directa del Archivo ZIP

Content-Type: application/zip | Nombre: comprobantes_YYYYMMDD_HHMMSS.zip

404 Not Found

No existen comprobantes registrados en la empresa para ese rango de fechas.

422 Unprocessable Entity

La cantidad de comprobantes a descargar supera el límite máximo permitido por la configuración de la empresa.

Diagnóstico Códigos HTTP

Códigos de estado estándar devueltos por el servidor

Código	Significado	Causa & Tratamiento
200 / 201	Éxito	Operación procesada correctamente.
401 Unauthorized	No autorizado	La API Key falta o es inválida / caducada.
422 Unprocessable Entity	Error de Validación	Error en estructura de datos enviada, superó plazo de anulación o el documento no cumple los requisitos SUNAT.
500 Internal Server Error	Error de Servidor	Falla en comunicación con el OSE/SUNAT o error de base de datos.

Referencia de Integración API NexaFact

Autenticación (API Key)

Gestión de Equivalencias Externas (Mapeo ERP / POS)

Emisión de Factura / Boleta Electrónica

Parámetros de Petición (Request Body)

Emisión de Nota de Crédito Electrónica

Parámetros de Petición (Nota de Crédito)

Anulación / Comunicación de Baja

Descarga Masiva de Comprobantes en ZIP por Rango de Fechas

Parámetros Query (Obligatorios)

Consultas y Descarga de Documentos

Diagnóstico Códigos HTTP