GCContable · API SUNAT

Guía rápida de integración

1. Autenticación

Incluye tu API Key en el header de cada petición:

X-API-Key: tu_api_key_aqui

Si no tienes una API Key, contacta a gccontable.es.

2. Ejemplo rápido — Consultar un RUC

curl -X GET "https://gccontable.es/contribuyente/ruc/20603408161" \
     -H "X-API-Key: tu_api_key"

Respuesta exitosa

{
  "success": true,
  "data": {
    "ruc": "20603408161",
    "razonSocial": "EMPRESA EJEMPLO S.A.C.",
    "estado": "ACTIVO",
    "condicion": "HABIDO",
    "direccion": "AV. EJEMPLO 123, LIMA"
  }
}

Respuesta con error

{
  "success": false,
  "error": "Credenciales SUNAT inválidas o expiradas.",
  "sunat": {
    "codigo": "invalid_client",
    "mensaje": "El client_id no existe o la clave es incorrecta."
  }
}

3. Endpoints disponibles

Consulta RUC

MétodoRutaDescripción
GET /contribuyente/ruc/{ruc} Datos básicos de un RUC
GET /contribuyente/ruc/{ruc}/full Datos completos (actividad económica, tipo, etc.)
POST /contribuyente/ruc/lote Consultar hasta 20 RUCs en paralelo

Tipo de Cambio

MétodoRutaDescripción
GET /contribuyente/tipo-cambio/sunat Tipo de cambio USD/PEN (SUNAT). Param: ?fecha=YYYY-MM-DD
GET /contribuyente/tipo-cambio/sbs Tipo de cambio promedio SBS. Param: ?moneda=USD&fecha=YYYY-MM-DD

Validar Comprobante (requiere credenciales SUNAT)

MétodoRutaDescripción
POST /contribuyente/{ruc}/validarcomprobante Valida si un comprobante de pago es válido en SUNAT

SIRE — Registro de Ventas (requiere credenciales SUNAT)

MétodoRutaDescripción
GET /contribuyente/sire/periodos?ruc= Listar periodos disponibles
GET /contribuyente/sire/ventas?ruc=&periodo=YYYYMM Registro de Ventas por periodo
GET /contribuyente/sire/rvie?ruc=&periodo=YYYYMM RVIE por periodo

GRE — Guía de Remisión Electrónica (requiere credenciales SOL)

MétodoRutaDescripción
POST /contribuyente/gre/emitir Emitir una guía de remisión electrónica
GET /contribuyente/gre/consultar?serie=&numero= Consultar estado de una guía
POST /contribuyente/gre/confirmar Confirmar recepción de una guía

SSPP — Receptor XML (requiere credenciales SOL)

MétodoRutaDescripción
POST /contribuyente/sspp/enviar Enviar comprobante XML (ZIP en Base64)
GET /contribuyente/sspp/{identificador}/estado Consultar estado/CDR de un comprobante enviado

Control Aduanero (requiere credenciales SOL)

MétodoRutaDescripción
POST /aduanero/documentossustentatorios Transmitir documentos digitalizados (PDF en Base64)

Detracciones SPOT (requiere credenciales SOL)

MétodoRutaDescripción
GET /contribuyente/detracciones/consultar?ruc=&periodo=YYYYMM Consultar constancias de depósito de detracciones SPOT
GET /contribuyente/detracciones/constancia?nro= Descargar constancia individual por número

Declaraciones PDT NUEVO

MétodoRutaDescripción
GET /contribuyente/pdt/declaraciones?ruc=&periodo=YYYYMM Consultar declaraciones PDT presentadas ante SUNAT
GET /contribuyente/pdt/0621?ruc=&periodo=YYYYMM Detalle de declaración IGV-Renta mensual (PDT 621)

Mi Cuenta

MétodoRutaDescripción
GET /mi-cuenta/perfil Ver tu plan, estado y credenciales configuradas
GET /mi-cuenta/uso Ver tu consumo de hoy y total por endpoint
PUT /mi-cuenta/credenciales Actualizar tus credenciales SUNAT

4. Ejemplos de body

POST /contribuyente/ruc/lote

{ "rucs": ["20603408161", "20478963719", "10456789012"] }

POST /contribuyente/{ruc}/validarcomprobante

{
  "numRuc": "20603408161",
  "codComp": "01",
  "numeroSerie": "F001",
  "numero": "1234",
  "fechaEmision": "2024-01-15",
  "monto": 1180.00
}

POST /contribuyente/sspp/enviar

{
  "ruc": "20603408161",
  "nombreArchivo": "20603408161-01-F001-1234.zip",
  "archivo": "UEsDBAoAAAAAAGR..."
}

5. Códigos de error HTTP

CódigoSignificado
400Parámetros inválidos o faltantes
401API Key inválida o credenciales SUNAT incorrectas
403Sin permisos para el servicio (RUC no habilitado en SOL)
404RUC, comprobante o periodo no encontrado
422Formato de datos incorrecto
429Límite diario de requests alcanzado
503SUNAT temporalmente no disponible
504SUNAT tardó demasiado en responder

6. Documentación interactiva

Prueba todos los endpoints directamente desde el navegador:

→ Swagger UI (/docs)   |   → ReDoc (/redoc)