API REST · v1

Documentación de la API de facturación electrónica

La API de ConectaSUNAT es REST y usa JSON. Con ella tu sistema emite facturas, boletas, notas de crédito y débito, guías de remisión, retenciones y percepciones electrónicas: tú envías los datos del comprobante y nosotros generamos el XML UBL 2.1, lo firmamos con tu certificado, lo enviamos a SUNAT y guardamos XML, CDR y PDF.

Inicio rápido

  1. Crea tu cuenta: recibes al instante las credenciales de producción y del ambiente de pruebas (SUNAT beta).
  2. Emite tu primera factura en pruebas (ejemplo abajo) y revisa el resultado.
  3. En el panel, en Empresa y SUNAT, sube tu certificado digital y tu usuario SOL secundario, verifica la conexión y pasa a producción.
curl -X POST https://conectasunat.com/api/v1/facturas \
  -H "X-Api-Key: $API_KEY" \
  -H "X-Api-Secret: $API_SECRET" \
  -H "Idempotency-Key: pedido-000123" \
  -H "Content-Type: application/json" \
  -d '{
    "serie": "F001",
    "fecha_emision": "2026-11-18",
    "tipo_moneda": "PEN",
    "esperar_cdr": true,
    "cliente": {"tipo_doc": "6", "num_doc": "20131312955", "razon_social": "CLIENTE SAC"},
    "items": [{"descripcion": "Servicio de soporte", "unidad": "ZZ", "cantidad": 1, "precio_unitario": 118}]
  }'

URL base

Todas las rutas están bajo https://conectasunat.com/api/v1. La versión va en la URL: una futura v2 convivirá con v1 sin romper tu integración.

Autenticación

Cada empresa tiene un par de credenciales. Envíalas en cada petición:

X-Api-Key: <api_key>
X-Api-Secret: <api_secret>
Accept: application/json
Content-Type: application/json
  • El secreto se muestra una sola vez al crearlo. Guárdalo en las variables de entorno de tu servidor, nunca en el código ni en el navegador.
  • Si lo pierdes, genera credenciales nuevas desde el panel: las anteriores dejan de funcionar al instante.
SituaciónHTTPMensaje
Faltan las cabeceras401Las cabeceras X-Api-Key y X-Api-Secret son requeridas.
Credenciales inválidas401Credenciales de API inválidas.
Empresa desactivada403Empresa desactivada. Contacte al administrador.

Ambientes: producción y pruebas

  • Producción: comprobantes con validez tributaria en SUNAT.
  • Pruebas (SUNAT beta): un ambiente aislado con credenciales propias. Todas las rutas funcionan igual, pero envían a SUNAT beta y sus datos no se mezclan con los reales.

Con las credenciales de pruebas, POST /api/v1/empresa/pruebas/verificar ejecuta una batería automática (factura, boleta, notas, baja, resumen y guía) y GET /api/v1/empresa/pruebas/verificaciones/{id} muestra el resultado paso a paso.

GET /api/v1/empresa/conexion-sunat?entorno=production revisa tu certificado, tu usuario SOL y la autenticación con SUNAT real sin emitir nada.

Formato de las respuestas

Éxito:

{ "estado": "exito", "mensaje": "OK", "datos": { } }

Error de validación (422):

{
  "estado": "error",
  "mensaje": "Error de validación",
  "errores": { "serie": ["El campo serie debe contener 4 caracteres."] }
}
HTTPSignificado
200 / 201Éxito / recurso creado
401 / 403Autenticación o permiso
404No existe o pertenece a otra empresa
409Operación en curso (por ejemplo, la misma Idempotency-Key todavía se procesa)
422Validación o regla de negocio
429Límite de peticiones por minuto o cupo del plan alcanzado (ver codigo_error)
500Error interno, sin detalles; incluye request_id para soporte

Cada respuesta trae la cabecera X-Request-Id: cítala si nos escribes por un problema.

Emitir comprobantes

  1. POST /api/v1/facturas (y el resto de comprobantes) valida, calcula impuestos y totales, asigna el correlativo y responde 201.
  2. El envío a SUNAT ocurre en segundo plano, con reintentos automáticos. Estados: pendiente → enviado → aceptado o rechazado.
  3. Consulta GET /api/v1/facturas/{id} o recibe un webhook cuando SUNAT responde.

Envío inmediato: con "esperar_cdr": true el envío se hace en la misma petición y la respuesta ya trae sunat.estado (aceptado o rechazado), el código y la descripción de SUNAT. Si SUNAT tarda más de 20 segundos, el comprobante queda enviado y sigue en la cola.

Observaciones: un comprobante aceptado puede traer observaciones de SUNAT (códigos 4000 o más) en sunat.notas. Un rechazo (códigos 2000 a 3999) deja el estado rechazado, con el XML y el CDR descargables como constancia.

Boletas: se informan a SUNAT en el resumen diario. Con la preferencia resumen_automatico (PUT /api/v1/empresa/preferencias), el resumen se envía solo.

Descargas: GET …/{id}/xml, GET …/{id}/cdr y GET …/{id}/pdf?formato=a4|a5|ticket-80|ticket-58.

Tu cliente: GET …/{id}/enlace devuelve un enlace público firmado para que tu cliente descargue su comprobante, y POST …/{id}/enviar-correo se lo envía por correo con PDF y XML.

Idempotencia

Si tu sistema reintenta una petición (por ejemplo, por un corte de red), envía siempre la misma clave:

Idempotency-Key: pedido-2026-000123
  • Misma clave y mismo cuerpo: misma respuesta, sin duplicar el comprobante.
  • Misma clave con otro cuerpo: 422 idempotency_key_reutilizada.
  • Clave todavía en proceso: 409 idempotency_en_proceso.
  • Se recuerda durante 24 horas.

Webhooks

Configura la URL en PUT /api/v1/empresa (url_webhook). Cuando SUNAT acepta o rechaza un comprobante te enviamos:

POST <tu url>
X-Webhook-Event: document.sent
X-Webhook-Signature: sha256=<HMAC-SHA256 del cuerpo con la clave de firma>
X-Request-Id: <id>

Eventos: document.sent, document.rejected, retention.sent, retention.rejected, perception.sent y perception.rejected. Si tu servidor no responde 2xx, reintentamos 3 veces.

**La clave de firma es el SHA-256 de tu api_secret** (64 caracteres hexadecimales en minúsculas), no el api_secret tal cual: nosotros guardamos solo ese hash y firmamos con él. Las credenciales creadas antes de que se guardara el hash firman con el api_secret directamente; si no sabes de cuándo son las tuyas, acepta las dos.

Verifica siempre la firma antes de confiar en el contenido, sobre el cuerpo crudo (sin volver a codificar el JSON):

$cuerpo  = file_get_contents('php://input');
$secreto = getenv('API_SECRET');
$recibida = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? '';
$conHash = 'sha256=' . hash_hmac('sha256', $cuerpo, hash('sha256', $secreto));
$directa = 'sha256=' . hash_hmac('sha256', $cuerpo, $secreto);   // credenciales antiguas
if (! hash_equals($conHash, $recibida) && ! hash_equals($directa, $recibida)) {
    http_response_code(401);
    exit;
}
const crypto = require('crypto');
const clave = crypto.createHash('sha256').update(process.env.API_SECRET).digest('hex');
const firmar = (k) => 'sha256=' + crypto.createHmac('sha256', k).update(cuerpoCrudo).digest('hex');
const recibida = Buffer.from(req.get('X-Webhook-Signature') || '');
const igual = (s) => { const b = Buffer.from(s); return b.length === recibida.length && crypto.timingSafeEqual(b, recibida); };
const valida = igual(firmar(clave)) || igual(firmar(process.env.API_SECRET));   // la segunda: credenciales antiguas

Para evitar que alguien reenvíe un aviso antiguo, rechaza también los que traigan un timestamp de hace más de unos minutos.

Límites y uso del plan

CabeceraDescripción
X-RateLimit-Limit, X-RateLimit-RemainingPeticiones por minuto de tu plan
X-Plan, X-Usage-DocumentsPlan y comprobantes usados en el mes
X-Usage-Warning: approaching_limitAviso al pasar el 80 % del cupo mensual

Al llegar al cupo de comprobantes del mes la API responde 429 con codigo_error: LIMIT_REACHED; el cupo de consultas RUC/DNI responde CONSULTAS_LIMIT_REACHED. Puedes subir de plan en cualquier momento desde el panel. Detalle de cada plan en precios.

Paginación

Los listados responden:

{ "estado": "exito", "mensaje": "OK",
  "datos": { "datos": [ ], "paginacion": { "pagina_actual": 1, "ultima_pagina": 3, "por_pagina": 15, "total": 42 } } }

Parámetros: page, por_pagina y los filtros de cada recurso (sunat_status, desde, hasta, search, ordenar_por, orden).

Reportes

GET /api/v1/reportes/* acepta formato=json, pdf o csv. El CSV es UTF-8 y se abre directo en Excel; el registro de ventas en CSV no tiene límite de tamaño.

ReporteRutaNotas
Registro de ventasreportes/registro-ventas
Ventas consolidadoreportes/ventas-consolidado`agrupacion=dia\semana\mes`
Notas de crédito y débitoreportes/notas
Cobranzasreportes/cobranzas
Documentos internosreportes/documentos-internos
Estado de cuentareportes/por-clienteclient_num_doc obligatorio
Comparativo por sucursalreportes/por-sucursal
Guías de remisiónreportes/guiasestado_sunat, serie, client_num_doc (destinatario)
Compras (general)reportes/compraspor proveedor, tipo y mes; client_num_doc = RUC del proveedor
Compras (detalle)reportes/compras-detalleuna fila por comprobante de compra

Todos piden fecha_desde y fecha_hasta (máximo 366 días). Las compras salen de la propuesta del Registro de Compras de SUNAT (SIRE): pida la propuesta de cada periodo para que aparezcan.

Formato 14.1 (PLE)

GET /api/v1/reportes/formato-14-1?periodo=AAAAMM devuelve el resumen, los avisos y las primeras líneas; con formato=txt descarga el archivo LE{RUC}{AAAAMM}00140100001111.txt (ISO-8859-1, CRLF) con los 35 campos del Registro de Ventas e Ingresos (anexo IV de la R.S. 108-2020/SUNAT). Los comprobantes en dólares se pasan a soles con tipo_cambio[AAAA-MM-DD]=3.750; si falta alguno, responde 422 falta_tipo_cambio con las fechas. Es una base para revisar con su contador antes de validarla en el PLE.

SIRE Ventas (RVIE)

Con SIRE activado (POST /api/v1/sire/activar), el Registro de Ventas e Ingresos Electrónico usa los servicios del manual oficial de SUNAT (Ventas v31):

AcciónRuta
PeriodosGET sire/periodos?libro=rvie
Pedir la propuesta (TXT o Excel)`GET sire/rvie/{AAAAMM}/propuesta?formato=txt\excel`
Pedir los no incluidosGET sire/rvie/{AAAAMM}/no-incluidos
Aceptar la propuestaPOST sire/rvie/{AAAAMM}/aceptar-propuesta
Registrar el preliminarPOST sire/rvie/{AAAAMM}/registrar-preliminar
Pedir el preliminarGET sire/rvie/{AAAAMM}/preliminar
Pedir el registro generado`GET sire/rvie/{AAAAMM}/registro?reporte=libro\consolidado`
Resumen (descarga directa)`GET sire/rvie/{AAAAMM}/resumen?tipo=propuesta\preliminar\no_incluidos\registro\preliminar_registrado\ajustes_posteriores&formato=txt\csv`
Constancia de recepción (PDF)GET sire/rvie/constancia?nom_archivo=
Preliminares registradosGET sire/rvie/preliminares-registrados?desde=AAAAMM&hasta=AAAAMM

Las solicitudes de archivo responden 202 con num_ticket: consulte GET sire/tickets/{num_ticket} (o sire/tickets?libro=rvie) y, cuando archivo_disponible sea true, descárguelo con GET sire/tickets/{num_ticket}/archivo. Filtros opcionales de propuesta, no incluidos y preliminar: fec_documento_desde/fec_documento_hasta (AAAA-MM-DD, dentro del periodo), mto_total_desde/mto_total_hasta, num_ruc_adquiriente, num_car_sunat, cod_tipo_cdp, cod_tipo_inconsistencia.

Fechas y horas

Las fechas "de hoy" (bajas, panel, vencimientos y el mes del plan) son de Perú (America/Lima).

Endpoints

Todas las rutas requieren tus credenciales salvo GET /api/v1/planes. Se agrupan por recurso:

anulaciones

MétodoRuta
POST/api/v1/anulaciones
GET/api/v1/anulaciones
GET/api/v1/anulaciones/{id}
GET/api/v1/anulaciones/{id}/estado
GET/api/v1/anulaciones/{id}/xml
GET/api/v1/anulaciones/{id}/cdr
POST/api/v1/anulaciones/{id}/enviar

boletas

MétodoRuta
POST/api/v1/boletas
GET/api/v1/boletas
GET/api/v1/boletas/{id}
PUT/api/v1/boletas/{id}
DELETE/api/v1/boletas/{id}
GET/api/v1/boletas/{id}/xml
GET/api/v1/boletas/{id}/cdr
GET/api/v1/boletas/{id}/pdf
POST/api/v1/boletas/{id}/reenviar
POST/api/v1/boletas/{id}/enviar
POST/api/v1/boletas/{id}/pagos
GET/api/v1/boletas/{id}/pagos
DELETE/api/v1/boletas/{id}/pagos/{paymentId}

buscar-documento

MétodoRuta
GET/api/v1/buscar-documento

catalogos

MétodoRuta
GET/api/v1/catalogos/producto-sunat
GET/api/v1/catalogos/producto-sunat/segmentos
GET/api/v1/catalogos/producto-sunat/familias
GET/api/v1/catalogos/producto-sunat/clases
GET/api/v1/catalogos/producto-sunat/productos
GET/api/v1/catalogos/producto-sunat/{codigo}
GET/api/v1/catalogos/ubigeo/regiones
GET/api/v1/catalogos/ubigeo/provincias
GET/api/v1/catalogos/ubigeo/distritos

clientes

MétodoRuta
GET/api/v1/clientes
POST/api/v1/clientes
GET/api/v1/clientes/{id}
PUT/api/v1/clientes/{id}
PATCH/api/v1/clientes/{id}
DELETE/api/v1/clientes/{id}

comprobantes

MétodoRuta
GET/api/v1/comprobantes/exportar-zip

consultar-cdr

MétodoRuta
POST/api/v1/consultar-cdr

consultar-cpe

MétodoRuta
GET/api/v1/consultar-cpe

consultar-talonario

MétodoRuta
GET/api/v1/consultar-talonario

Talonario de comprobantes físicos (6/10/2026, TalonarioController + App\Services\Consulta\TalonarioFisicoService): ?serie=0001&numero=120[&tipo_doc=03][&buscar_limite=1]. Con la Consulta Integrada de SUNAT (la misma de consultar-cpe, credenciales de API SUNAT de la empresa) dice si ese número está AUTORIZADO (estado 3: impreso con autorización de imprenta) y, con buscar_limite, busca el último número autorizado de la serie (exponencial + binaria, máx. 30 consultas a SUNAT; hasta_exacto = false si se agotaron). SUNAT no sabe qué hojas usó la empresa: el siguiente número lo pone ella. Sin client_id/client_secret → 422 con el paso a seguir.

cotizaciones

MétodoRuta
POST/api/v1/cotizaciones
GET/api/v1/cotizaciones
GET/api/v1/cotizaciones/{id}
PUT/api/v1/cotizaciones/{id}
PUT/api/v1/cotizaciones/{id}/estado
GET/api/v1/cotizaciones/{id}/pdf

credenciales

MétodoRuta
POST/api/v1/credenciales/recuperar
POST/api/v1/credenciales/recuperar/verificar

empresa

MétodoRuta
GET/api/v1/empresa
PUT/api/v1/empresa
DELETE/api/v1/empresa
POST/api/v1/empresa/logo
POST/api/v1/empresa/certificado
GET/api/v1/empresa/credenciales
POST/api/v1/empresa/credenciales/regenerar
GET/api/v1/empresa/pruebas
POST/api/v1/empresa/pruebas
DELETE/api/v1/empresa/pruebas
POST/api/v1/empresa/pruebas/reiniciar
POST/api/v1/empresa/pruebas/credenciales
POST/api/v1/empresa/pruebas/verificar
GET/api/v1/empresa/pruebas/verificaciones
GET/api/v1/empresa/pruebas/verificaciones/{id}
GET/api/v1/empresa/conexion-sunat
GET/api/v1/empresa/alertas
GET/api/v1/empresa/preferencias
PUT/api/v1/empresa/preferencias

facturas

MétodoRuta
POST/api/v1/facturas
POST/api/v1/facturas/masivo
GET/api/v1/facturas
GET/api/v1/facturas/{id}
PUT/api/v1/facturas/{id}
GET/api/v1/facturas/{id}/xml
GET/api/v1/facturas/{id}/cdr
GET/api/v1/facturas/{id}/pdf
POST/api/v1/facturas/{id}/reenviar
POST/api/v1/facturas/{id}/enviar
POST/api/v1/facturas/{id}/pagos
GET/api/v1/facturas/{id}/pagos
DELETE/api/v1/facturas/{id}/pagos/{paymentId}

guias-remision

MétodoRuta
POST/api/v1/guias-remision
GET/api/v1/guias-remision
GET/api/v1/guias-remision/{id}
PUT/api/v1/guias-remision/{id}
GET/api/v1/guias-remision/{id}/pdf
GET/api/v1/guias-remision/{id}/xml
GET/api/v1/guias-remision/{id}/estado
POST/api/v1/guias-remision/{id}/enviar

guias-remision-transportista

MétodoRuta
POST/api/v1/guias-remision-transportista

notas-credito

MétodoRuta
POST/api/v1/notas-credito
GET/api/v1/notas-credito
GET/api/v1/notas-credito/{id}
GET/api/v1/notas-credito/{id}/xml
GET/api/v1/notas-credito/{id}/cdr
GET/api/v1/notas-credito/{id}/pdf
PUT/api/v1/notas-credito/{id}
POST/api/v1/notas-credito/{id}/reenviar
POST/api/v1/notas-credito/{id}/enviar

notas-debito

MétodoRuta
POST/api/v1/notas-debito
GET/api/v1/notas-debito
GET/api/v1/notas-debito/{id}
GET/api/v1/notas-debito/{id}/xml
GET/api/v1/notas-debito/{id}/cdr
GET/api/v1/notas-debito/{id}/pdf
PUT/api/v1/notas-debito/{id}
POST/api/v1/notas-debito/{id}/reenviar
POST/api/v1/notas-debito/{id}/enviar

notas-venta

MétodoRuta
POST/api/v1/notas-venta
GET/api/v1/notas-venta
GET/api/v1/notas-venta/{id}
PUT/api/v1/notas-venta/{id}
GET/api/v1/notas-venta/{id}/pdf
POST/api/v1/notas-venta/{id}/pagos
GET/api/v1/notas-venta/{id}/pagos
DELETE/api/v1/notas-venta/{id}/pagos/{paymentId}

panel

MétodoRuta
GET/api/v1/panel
GET/api/v1/panel/indicadores
GET/api/v1/panel/estado-sunat
GET/api/v1/panel/cobranzas
GET/api/v1/panel/ventas-mensuales
GET/api/v1/panel/por-sucursal
GET/api/v1/panel/por-moneda
GET/api/v1/panel/clientes
GET/api/v1/panel/productos
GET/api/v1/panel/documentos-recientes
GET/api/v1/panel/alertas

percepciones

MétodoRuta
POST/api/v1/percepciones
GET/api/v1/percepciones
GET/api/v1/percepciones/{id}
GET/api/v1/percepciones/{id}/xml
GET/api/v1/percepciones/{id}/cdr
POST/api/v1/percepciones/{id}/enviar

planes

MétodoRuta
GET/api/v1/planes

registro

MétodoRuta
POST/api/v1/registro

reportes

MétodoRuta
GET/api/v1/reportes/registro-ventas
GET/api/v1/reportes/ventas-consolidado
GET/api/v1/reportes/notas
GET/api/v1/reportes/cobranzas
GET/api/v1/reportes/documentos-internos
GET/api/v1/reportes/por-cliente
GET/api/v1/reportes/por-sucursal

resumenes

MétodoRuta
GET/api/v1/resumenes
POST/api/v1/resumenes
GET/api/v1/resumenes/{id}/estado
GET/api/v1/resumenes/{id}/xml
GET/api/v1/resumenes/{id}/cdr
POST/api/v1/resumenes/{id}/enviar

retenciones

MétodoRuta
POST/api/v1/retenciones
GET/api/v1/retenciones
GET/api/v1/retenciones/{id}
GET/api/v1/retenciones/{id}/pdf
GET/api/v1/retenciones/{id}/xml
GET/api/v1/retenciones/{id}/cdr
POST/api/v1/retenciones/{id}/enviar

reversiones

MétodoRuta
POST/api/v1/reversiones

series

MétodoRuta
POST/api/v1/series/init-defaults
GET/api/v1/series
POST/api/v1/series
GET/api/v1/series/{id}
PUT/api/v1/series/{id}
PATCH/api/v1/series/{id}
DELETE/api/v1/series/{id}

sire

MétodoRuta
POST/api/v1/sire/activar
POST/api/v1/sire/desactivar
GET/api/v1/sire/periodos
GET/api/v1/sire/rce/constancia
GET/api/v1/sire/rce/reconciliaciones/{id}
GET/api/v1/sire/rce/{periodo}/propuesta
GET/api/v1/sire/rce/{periodo}/resumen
POST/api/v1/sire/rce/{periodo}/aceptar-propuesta
POST/api/v1/sire/rce/{periodo}/registrar-preliminar
POST/api/v1/sire/rce/{periodo}/reemplazar-propuesta
POST/api/v1/sire/rce/{periodo}/no-domiciliados
POST/api/v1/sire/rce/{periodo}/complementar-propuesta
POST/api/v1/sire/rce/{periodo}/ajustes-posteriores/{variant}/cargar
POST/api/v1/sire/rce/{periodo}/ajustes-posteriores/{variant}/enviar
GET/api/v1/sire/rce/{periodo}/ajustes-posteriores/{variant}/descargar
POST/api/v1/sire/rce/{periodo}/ajustes-posteriores/{variant}/eliminar
GET/api/v1/sire/rce/{periodo}/comprobantes
GET/api/v1/sire/rce/{periodo}/comprobantes/{id}
GET/api/v1/sire/rce/{periodo}/reconciliar
POST/api/v1/sire/rce/{periodo}/reconciliar-async
GET/api/v1/sire/rce/{periodo}/reconciliaciones
GET/api/v1/sire/tickets
GET/api/v1/sire/tickets/{numTicket}
POST/api/v1/sire/tickets/{numTicket}/refrescar
GET/api/v1/sire/tickets/{numTicket}/archivo

sucursales

MétodoRuta
GET/api/v1/sucursales
POST/api/v1/sucursales
GET/api/v1/sucursales/{id}
PUT/api/v1/sucursales/{id}
PATCH/api/v1/sucursales/{id}
DELETE/api/v1/sucursales/{id}

sunat

MétodoRuta
GET/api/v1/sunat/estado

suscripcion

MétodoRuta
GET/api/v1/suscripcion
POST/api/v1/suscripcion
PUT/api/v1/suscripcion/cambiar-plan
PUT/api/v1/suscripcion/cancelar
GET/api/v1/suscripcion/pagos
GET/api/v1/suscripcion/uso