Documentación de la API

Introducción

La API te permite emitir boletas, facturas, notas de crédito/débito y anulaciones a SUNAT, y obtener el PDF, el XML firmado y el CDR. Tú envías la venta en JSON; nosotros armamos el XML UBL 2.1, lo firmamos y lo enviamos a SUNAT.

URL base:

https://api.factusmart.pe/api/v1/issuer

Modelo de cuenta: tu cuenta tiene una bolsa de créditos compartida y puede emitir para uno o varios RUCs. Cada comprobante emitido descuenta 1 crédito de tu cuenta.

Autenticación

Toda petición lleva tu API key en el header:

X-API-Key: TU_API_KEY

Si tu cuenta tiene varios RUCs, indica el RUC emisor en cada petición con el campo ruc (en el body o como query ?ruc=20123456789). Si tu cuenta tiene un solo RUC, se usa automáticamente.

Créditos

• Prepago: compras un paquete de comprobantes por adelantado.
• Se descuenta 1 crédito por comprobante emitido (aceptado u observado).
• Compartidos por todos los RUCs de tu cuenta.
• Vigencia de 1 año; te avisamos por correo al 20% y 10% de saldo.
• Si te quedas sin créditos, la emisión responde 402 y no emite.

Emitir comprobante

El correlativo lo asigna FactuSmart: envía "numero_documento": "#". Cambia codigo_tipo_documento según el tipo (01 factura, 03 boleta, 07/08 notas).

Ejemplo — factura (cURL):

curl -X POST https://api.factusmart.pe/api/v1/issuer/documents \
  -H "X-API-Key: TU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "ruc": "20123456789",
  "serie_documento": "F001",
  "numero_documento": "#",
  "fecha_de_emision": "2026-06-17",
  "codigo_tipo_operacion": "0101",
  "codigo_tipo_documento": "01",
  "codigo_tipo_moneda": "PEN",
  "fecha_de_vencimiento": "2026-06-17",
  "datos_del_cliente_o_receptor": {
    "codigo_tipo_documento_identidad": "6",
    "numero_documento": "20555555555",
    "apellidos_y_nombres_o_razon_social": "EMPRESA CLIENTE S.A.C.",
    "direccion": "Av. Ejemplo 123"
  },
  "totales": {
    "total_operaciones_gravadas": 100.00,
    "total_igv": 18.00,
    "total_impuestos": 18.00,
    "total_valor": 100.00,
    "total_venta": 118.00
  },
  "items": [
    {
      "descripcion": "Servicio de consultoría",
      "unidad_de_medida": "NIU",
      "cantidad": 1,
      "valor_unitario": 100.00,
      "codigo_tipo_precio": "01",
      "precio_unitario": 118.00,
      "codigo_tipo_afectacion_igv": "10",
      "total_base_igv": 100.00,
      "porcentaje_igv": 18,
      "total_igv": 18.00,
      "total_impuestos": 18.00,
      "total_valor_item": 100.00,
      "total_item": 118.00
    }
  ]
}'

Respuesta:

{
  "success": true,
  "estado": "05",
  "estado_descripcion": "Aceptado",
  "serie_numero": "F001-1234",
  "external_id": "9822f52c-108e-47ff-...",
  "sunat": { "code": "0", "description": "La Factura F001-1234 ha sido aceptada" },
  "creditos_restantes": 4830
}

Para boleta usa "codigo_tipo_documento": "03". Para nota de crédito/débito usa "07"/"08" e incluye documento_afectado y codigo_tipo_nota.

Consultar estado

{
  "success": true,
  "estado": "05",
  "estado_descripcion": "Aceptado",
  "serie_numero": "F001-1234",
  "total": 118.00,
  "links": { "pdf": "...", "xml": "...", "cdr": "..." }
}

Descargar PDF / XML / CDR

Devuelven el archivo directamente (PDF, XML firmado o ZIP del CDR).

Anulaciones (comunicación de baja)

Es un proceso asíncrono: SUNAT devuelve un ticket y consultas el resultado después. La fecha va en formato DD-MM-AAAA.

{
  "ruc": "20123456789",
  "fecha_de_emision_de_documentos": "17-06-2026",
  "documentos": [
    { "external_id": "9822f52c-...", "motivo_anulacion": "Error en el documento" }
  ]
}

Consultar el resultado:

Consultar saldo

{
  "success": true,
  "cuenta": "Mi Integración",
  "creditos_disponibles": 4830,
  "creditos_recargados_total": 5000,
  "creditos_consumidos": 170,
  "rucs": [ { "ruc": "20123456789", "nombre": "..." } ]
}

Códigos de respuesta

Tipos de comprobante