Documentacion de la API

Referencia completa de todos los endpoints. Parametros, ejemplos de request y response, codigos de error.

Base URL: https://www.contasire.com

Autenticacion

Todos los endpoints requieren tu API Key en el header X-API-Key.

Obtenla desde el Dashboard despues de registrarte.

Tu API Key esta vinculada a tu cuenta y credenciales SUNAT. No necesitas enviar credenciales en cada request.

Header de autenticacion

// En cada request HTTP
X-API-Key: tu_api_key_aqui

Ejemplo con curl

curl -X POST https://www.contasire.com/api/cpe \
  -H "X-API-Key: tu_api_key" \
  -H "Content-Type: application/json" \
  -d '{"document_type":"01","serie":"F001",
       "number":"001172","issue_date":"2026-03-30",
       "total":"48.50"}'

POST

Validar comprobante CPE

/api/cpe

Valida un comprobante de pago electronico (CPE) contra SUNAT. Retorna el estado oficial del comprobante.

Body (JSON)

Parametro	Tipo		Descripcion
document_type	string	req	01=Factura, 03=Boleta, 07=NC, 08=ND
serie	string	req	Serie (ej: F001, B001, E001)
number	string	req	Numero del comprobante
issue_date	string	req	Fecha emision YYYY-MM-DD
total	string	req	Monto total

Status SUNAT: 0=NO EXISTE, 1=ACEPTADO, 2=ANULADO, 3=AUTORIZADO, 4=NO AUTORIZADO

Request

{
  "document_type": "01",
  "serie": "F001",
  "number": "001172",
  "issue_date": "2026-03-30",
  "total": "48.50"
}

Response 200

{
  "success": true,
  "message": "ACEPTADO",
  "data": {
    "ruc": "20610488227",
    "voucher": "F001-001172",
    "sunat_response": true,
    "status": "ACEPTADO",
    "status_code": 1
  }
}

POST

Validacion masiva CPE

/api/multiple-cpe-validation

Valida hasta 1000 comprobantes simultaneamente. 50 conexiones concurrentes, 1 reintento automatico, connection pooling.

Body (JSON)

Parametro	Tipo		Descripcion
vouchers	array	req	Array de comprobantes (ruc, document_type, serie, number, issue_date, total)
timeout	int	opc	Timeout por comprobante en segundos (default: 10)

Request

{
  "timeout": 10,
  "vouchers": [
    {
      "ruc": "20610488227",
      "document_type": "01",
      "serie": "F001",
      "number": "001172",
      "issue_date": "2026-03-30",
      "total": "48.50"
    }
  ]
}

Response 200

{
  "success": true,
  "data": {
    "total": 2,
    "validated": 2,
    "failed": 0,
    "elapsed_seconds": 1.23,
    "results": [
      {
        "ruc": "20610488227",
        "voucher": "F001-001172",
        "status": "ACEPTADO",
        "status_code": 1
      }
    ]
  }
}

POST

Descargar comprobante electronico

/api/voucher

Descarga un comprobante electronico desde SUNAT en formato JSON (parseado con items, IGV, retenciones, detracciones), XML o PDF.

Body (JSON)

Parametro	Tipo		Descripcion
supplier_ruc	string	req	RUC del emisor (11 digitos)
document_type	string	req	01=Factura, 03=Boleta, 07=NC, 08=ND
serie	string	req	Serie del comprobante
number	string	req	Numero del comprobante
output	string	opc	json (default), xml, pdf

Request

{
  "supplier_ruc": "20610488227",
  "document_type": "01",
  "serie": "F001",
  "number": "001172",
  "output": "json"
}

Response 200 (json)

{
  "success": true,
  "data": {
    "header": {
      "voucher": "F001-001172",
      "issue_date": "2026-03-30",
      "currency": "PEN",
      "supplier": {"ruc":"20610488227"},
      "customer": {"ruc":"20100066603"},
      "taxable_amount": 41.1,
      "igv": 7.4,
      "total": 48.5,
      "retention": null,
      "detraction": null
    },
    "items": [{
      "description": "SERVICIO X",
      "quantity": 1.0,
      "unit_value": 41.1,
      "tax": 7.4,
      "total": 48.5
    }]
  }
}

Response 200 (pdf/xml)

{
  "success": true,
  "data": {
    "file_name": "F001-001172.pdf",
    "content_base64": "JVBERi0x..."
  }
}

POST

Reporte gerencial tributario

/api/tax-report

Reporte mensual consolidado: compras, ventas, calculo IGV, tipo de cambio, agentes de retencion. JSON o PDF profesional.

Body (JSON)

Parametro	Tipo		Descripcion
period	string	req	Periodo tributario yyyymm
output	string	opc	json (default) o pdf

Compras y ventas se descargan del SIRE en paralelo (~4s). TC y retenciones desde cache.

Request

{
  "period": "202603",
  "output": "json"
}

Response 200

{
  "success": true,
  "data": {
    "period": "202603",
    "ruc": "20610488227",
    "purchases": {
      "total_vouchers": 45,
      "taxable_amount": 125000.00,
      "igv": 22500.00,
      "total": 147500.00
    },
    "sales": {
      "total_vouchers": 120,
      "igv": 45000.00,
      "total": 295000.00
    },
    "igv_balance": {
      "igv_to_pay": 22500.00
    },
    "retentions": {
      "suppliers_with_retention": 5
    },
    "exchange_rate": {
      "average_buy": 3.718,
      "average_sell": 3.725
    },
    "elapsed_seconds": 8.5
  }
}

POST

SIRE Compras - Propuesta

/api/sire/purchases/proposal

Descarga la propuesta completa de compras del SIRE. Combina ticket + polling + descarga en un solo request.

Body (JSON)

Parametro	Tipo		Descripcion
period	string	req	Periodo yyyymm
output	string	opc	raw (ZIP), json, excel
timeout	int	opc	Timeout en segundos (default: 60)
document_type	string	opc	Filtrar por tipo doc
supplier_ruc	string	opc	Filtrar por RUC proveedor
date_from	string	opc	Fecha desde YYYY-MM-DD
date_to	string	opc	Fecha hasta YYYY-MM-DD
amount_from	float	opc	Monto minimo
amount_to	float	opc	Monto maximo

Request (minimo)

{
  "period": "202603",
  "output": "json"
}

Request (con filtros)

{
  "period": "202603",
  "output": "excel",
  "supplier_ruc": "20100066603",
  "date_from": "2026-03-01",
  "date_to": "2026-03-31",
  "amount_from": 100.00,
  "amount_to": 5000.00
}

Response 200 (json)

{
  "success": true,
  "data": {
    "period": "202603",
    "total_vouchers": 45,
    "elapsed_seconds": 12.5,
    "vouchers": [{
      "ruc": "20610488227",
      "supplier_name": "PROVEEDOR SAC",
      "document_type": "01",
      "serie": "E001",
      "taxable_base_dg": 252.2,
      "igv_dg": 45.4,
      "total": 297.6,
      "currency": "PEN"
    }]
  }
}

POST

SIRE Compras - Resumen

/api/sire/purchases/summary

Resumen consolidado del registro de compras de un periodo.

Body (JSON)

Parametro	Tipo		Descripcion
period	string	req	Periodo yyyymm
summary_type	int	opc	1=Propuesta, 2=Preliminar, 3=Excluidos, 4=Registro, 5=Registrados, 6=Ajustes, 7=No domiciliados
file_type	int	opc	0=Default

Request

{
  "period": "202603",
  "summary_type": 1,
  "file_type": 0
}

Response 200

{
  "success": true,
  "data": { // Resumen SUNAT del periodo }
}

POST

SIRE Compras - Periodos

/api/sire/purchases/periods

Retorna los periodos tributarios disponibles para el registro de compras (RCE). No requiere body.

Request

// POST /api/sire/purchases/periods
// No body required

Response 200

{
  "success": true,
  "data": [
    "202601", "202602", "202603"
  ]
}

POST

SIRE Ventas - Propuesta

/api/sire/sales/proposal

Descarga la propuesta completa de ventas del SIRE. Mismos parametros y formatos que purchases/proposal.

Body (JSON)

Parametro	Tipo		Descripcion
period	string	req	Periodo yyyymm
output	string	opc	raw, json, excel
timeout	int	opc	Timeout (default: 60)
document_type	string	opc	Filtrar por tipo doc
date_from / date_to	string	opc	Rango de fechas
amount_from / amount_to	float	opc	Rango de montos

Request

{
  "period": "202603",
  "output": "json"
}

Response 200

{
  "success": true,
  "data": {
    "period": "202603",
    "total_vouchers": 120,
    "elapsed_seconds": 10.2,
    "vouchers": [{
      "ruc": "20100066603",
      "document_type": "01",
      "serie": "F001",
      "total": 1180.00,
      "currency": "PEN"
    }]
  }
}

POST

SIRE Ventas - Resumen

/api/sire/sales/summary

Resumen consolidado del registro de ventas. Mismos parametros que purchases/summary.

Request

{
  "period": "202603",
  "summary_type": 1,
  "file_type": 0
}

POST

SIRE Ventas - Periodos

/api/sire/sales/periods

Retorna los periodos tributarios disponibles para el registro de ventas (RVIE). No requiere body.

Request

// POST /api/sire/sales/periods
// No body required

Response 200

{
  "success": true,
  "data": [
    "202601", "202602", "202603"
  ]
}

POST

Estado de ticket SIRE

/api/sire/ticket-status

Consulta el estado de procesamiento de un ticket del SIRE.

Body (JSON)

Parametro	Tipo		Descripcion
period_from	string	req	Periodo desde yyyymm
period_to	string	req	Periodo hasta yyyymm
ticket	string	req	Numero de ticket

Status: 06 = Listo, 01 = Procesando

Request

{
  "period_from": "202603",
  "period_to": "202603",
  "ticket": "20260300000028"
}

POST

Descargar archivo SIRE

/api/sire/download-file

Descarga un archivo procesado de un ticket completado. Retorna contenido en base64.

Body (JSON)

Parametro	Tipo		Descripcion
file_name	string	req	Nombre del archivo
file_type_code	string	req	Codigo tipo (ej: "00")
period	string	req	Periodo yyyymm
process_code	string	req	Codigo proceso (ej: "10")
ticket	string	req	Numero de ticket

Request

{
  "file_name": "20610488227-propuesta.zip",
  "file_type_code": "00",
  "period": "202603",
  "process_code": "10",
  "ticket": "20260300000028"
}

Response 200

{
  "success": true,
  "data": {
    "content_base64": "UEsDBBQA..."
  }
}

GET

Consultar RUC

/api/ruc?number=20610488227

Informacion completa de un contribuyente: razon social, estado, condicion, direccion, actividad economica, agente de retencion.

Query Parameters

Parametro	Tipo		Descripcion
number	string	req	RUC (11 digitos)

Response 200

{
  "success": true,
  "data": {
    "ruc": "20610488227",
    "legal_name": "GRETA NATURAL SAC",
    "trade_name": "GRETA NATURAL",
    "status": "ACTIVO",
    "condition": "HABIDO",
    "type": "SOC. ANONIMA CERRADA",
    "is_active": true,
    "is_habido": true,
    "address": "CAL. LOS HALCONES 209...",
    "department": "LIMA",
    "province": "LIMA",
    "district": "SAN ISIDRO",
    "ubigeo": "150131",
    "economic_activity": "VTA. MAY...",
    "is_retention_agent": false,
    "registration_date": "19/01/2023"
  }
}

GET

Consultar DNI

/api/dni?number=06256217

Consulta nombres y apellidos de una persona por su numero de DNI.

Query Parameters

Parametro	Tipo		Descripcion
number	string	req	DNI (8 digitos)

Response 200

{
  "success": true,
  "data": {
    "dni": "06256217",
    "full_name": "BOLUARTE ZEGARRA, DINA ERCILIA",
    "last_name": "BOLUARTE ZEGARRA",
    "first_name": "DINA ERCILIA"
  }
}

GET

Tipo de cambio SUNAT

/api/exchange-rate

Tipo de cambio USD/PEN oficial SUNAT. Soporta hoy, fecha especifica o rango.

Query Parameters

Parametro	Tipo		Descripcion
date	string	opc	Fecha YYYY-MM-DD (default: hoy)
from	string	opc	Inicio rango YYYY-MM-DD
to	string	opc	Fin rango YYYY-MM-DD

Fines de semana y feriados no tienen TC. Retorna el del ultimo dia habil. Datos desde enero 2025.

Response 200 (fecha)

// GET /api/exchange-rate?date=2026-03-30
{
  "success": true,
  "data": {
    "date": "2026-03-30",
    "buy": 3.715,
    "sell": 3.722,
    "source": "SUNAT"
  }
}

Response 200 (rango)

// GET /api/exchange-rate?from=2026-03-01&to=2026-03-31
{
  "success": true,
  "data": {
    "from": "2026-03-01",
    "to": "2026-03-31",
    "total": 22,
    "rates": [
      {"date":"2026-03-03","buy":3.715,"sell":3.722}
    ]
  }
}

GET

Agente de retencion

/api/retention-agent

Consulta si un RUC es agente de retencion designado por SUNAT. Permite buscar por nombre.

Query Parameters

Parametro	Tipo		Descripcion
ruc	string	*	RUC a consultar
search	string	*	Buscar por nombre o RUC
limit	int	opc	Max resultados (default: 20)

Padron se actualiza automaticamente 1 vez al mes desde SUNAT.

Response 200 (es agente)

// GET /api/retention-agent?ruc=20100119227
{
  "success": true,
  "data": {
    "ruc": "20100119227",
    "legal_name": "3M PERU S A",
    "is_retention_agent": true,
    "resolution": "RS R.S.037-2002",
    "valid_from": "2002-06-01"
  }
}

Response 200 (no es agente)

{
  "success": true,
  "data": {
    "ruc": "20000000001",
    "is_retention_agent": false
  }
}

POST

Sincronizar buzon SUNAT

/api/buzon/sync

Conecta a SOL, descarga mensajes y notificaciones, guarda en base de datos. No requiere body.

Plan: Profesional o superior. Requiere credenciales SOL.

Request

// POST /api/buzon/sync
// Header: X-API-Key: tu_api_key
// No body required

Response 200

{
  "success": true,
  "message": "5 nuevos mensajes sincronizados",
  "data": {
    "new_count": 5,
    "total_notifications": 23,
    "total_messages": 12
  }
}

POST

Listar mensajes del buzon

/api/buzon/messages

Retorna mensajes y notificaciones almacenados con filtros opcionales.

Query Parameters

Parametro	Tipo		Descripcion
type	int	opc	0=ambos, 1=mensajes, 2=notificaciones
search	string	opc	Buscar por asunto
is_read	bool	opc	Filtrar leido/no leido
is_urgent	bool	opc	Filtrar urgente
limit	int	opc	Default: 50, max: 200
offset	int	opc	Paginacion

Plan: Profesional o superior.

Response 200

{
  "success": true,
  "data": {
    "total": 35,
    "limit": 50,
    "offset": 0,
    "items": [{
      "id": 1,
      "code": 12345,
      "type": "notification",
      "subject": "Notificacion SUNAT",
      "date_sent": "15/03/2026",
      "is_read": false,
      "is_urgent": true
    }]
  }
}

POST

Detalle de mensaje

/api/buzon/detail?code=12345

Detalle completo de un mensaje/notificacion. Si ya fue consultado, retorna desde cache. Si no, se conecta a SUNAT SOL. Los adjuntos se suben a S3 automaticamente.

Query Parameters

Parametro	Tipo		Descripcion
code	int	req	Codigo del mensaje (de /messages)

Plan: Profesional o superior. Requiere credenciales SOL.

Request

// POST /api/buzon/detail?code=12345
// Header: X-API-Key: tu_api_key

Response 200

{
  "success": true,
  "data": {
    "code": 12345,
    "type": "notification",
    "subject": "Notificacion SUNAT",
    "sender": "SUNAT",
    "text": "Contenido en texto plano...",
    "attachments": [
      {"name":"doc.pdf", "code":"ATT001"}
    ],
    "attachments_status": "ready",
    "attachments_s3": [{
      "name": "doc.pdf",
      "s3_key": "buzon/1/12345/doc.pdf",
      "size": 45678
    }]
  }
}

POST

Recibos por honorarios

/api/honorarios/query

Consulta los recibos por honorarios electronicos (RHE) recibidos por la empresa en un periodo. Descarga el reporte TXT del portal SOL.

Body (JSON)

Parametro	Tipo		Descripcion
period	string	req	Periodo yyyymm (ej: 202604)

Plan: Profesional o superior. Requiere credenciales SOL. Toma 10-20 seg.

Campos de cada item

Campo	Descripcion
fecha_emision	Fecha DD/MM/YYYY
numero	Numero completo (E001-3)
serie / correlativo	Serie y correlativo separados
estado	NO ANULADO, ANULADO, REVERTIDO
ruc_emisor	RUC del emisor
nombre_emisor	Nombre o razon social
descripcion	Servicio prestado
moneda	SOLES o DOLARES
renta_bruta	Monto bruto
impuesto_renta	Retencion IR (8%)
renta_neta	Monto neto
monto_pendiente	Pendiente de pago

Request

// POST /api/honorarios/query
// Header: X-API-Key: tu_api_key

{
  "period": "202604"
}

Response 200

{
  "success": true,
  "message": "3 recibos encontrados",
  "data": {
    "total": 3,
    "period": "202604",
    "items": [{
      "fecha_emision": "05/04/2026",
      "tipo_doc": "RH",
      "numero": "E001-3",
      "serie": "E001",
      "correlativo": "3",
      "estado": "NO ANULADO",
      "ruc_emisor": "10456789012",
      "nombre_emisor": "GARCIA LOPEZ JUAN",
      "tipo_renta": "A",
      "gratuito": "NO",
      "descripcion": "ASESORIA CONTABLE",
      "moneda": "SOLES",
      "renta_bruta": "2500.00",
      "impuesto_renta": "200.00",
      "renta_neta": "2300.00",
      "monto_pendiente": "2300.00"
    }]
  }
}

Codigos de error

Todos los endpoints retornan errores en formato consistente.

Codigo	Significado	Descripcion
400	Bad Request	Parametros faltantes o invalidos
401	Unauthorized	Token SUNAT invalido o credenciales SOL incorrectas
402	Payment Required	Suscripcion expirada
403	Forbidden	API Key invalida o funcionalidad no disponible en tu plan
404	Not Found	RUC/DNI no encontrado o recurso inexistente
429	Rate Limited	Excediste el limite de requests
500	Server Error	Error interno, contacta soporte si persiste

Formato de error

{
  "success": false,
  "message": "Descripcion del error",
  "data": null
}

Ejemplo 403

{
  "success": false,
  "message": "Invalid API key or inactive account",
  "data": null
}

Ejemplo 402

{
  "success": false,
  "message": "Subscription expired",
  "data": null
}

Ejemplo 429

{
  "success": false,
  "message": "Rate limit exceeded",
  "data": null
}