SRI Integration

Integration with Ecuador’s Servicio de Rentas Internas (SRI) for tax authority data

Overview

The SRI (Servicio de Rentas Internas) integration provides access to Ecuador’s tax authority database, enabling validation and retrieval of taxpayer information, including RUC (Registro Único de Contribuyentes) details, tax status, and compliance information.

GraphQL Query

GetApiSriByRuc

Retrieves comprehensive tax information for a taxpayer by their RUC (tax identification number).

query GetApiSriByRuc($ruc: String!) {
  getApiSriByRuc(ruc: $ruc) {
    id
    numeroRuc
    razonSocial
    estadoContribuyenteRuc
    actividadEconomicaPrincipal
    tipoContribuyente
    regimen
    categoria
    obligadoLlevarContabilidad
    agenteRetencion
    contribuyenteEspecial
    fechaInicioActividades
    fechaCese
    fechaReinicioActividades
    fechaActualizacion
    representantesLegales
    motivoCancelacionSuspension
    contribuyenteFantasma
    transaccionesInexistentes
    establecimientos
    tipoPersona
    codigoPersona
    rootEstadoTributarioFecha
    textoEstadoTributario
    deudasFirmes
    dtMotivos
    dtObligacionesPendientes
    dtObligacionesPendientesPresentacion
    dtObligacionesPendientesPago
    createdAt
    updatedAt
  }
}

Location: Schema/Query/Query.cs:1139-1154

Parameters

ruc · String! · required

Tax identification number (RUC). Can be provided in 10-digit or 13-digit format. If 10 digits are provided, the system automatically appends “001” to form the complete RUC.

Response Fields

id · Int!

Unique identifier for the SRI record

numeroRuc · String

Complete RUC number (13 digits)

razonSocial · String

Legal business name or taxpayer name

estadoContribuyenteRuc · String

Current taxpayer status (Active, Inactive, Suspended, etc.)

actividadEconomicaPrincipal · String

Primary economic activity classification

tipoContribuyente · String

Taxpayer type classification

regimen · String

Tax regime type

categoria · String

Taxpayer category

obligadoLlevarContabilidad · String

Indicates if required to maintain accounting records (“SI”/“NO”)

agenteRetencion · String

Withholding agent status

contribuyenteEspecial · String

Special taxpayer designation

fechaInicioActividades · String

Date when business activities started

fechaCese · String

Date of cessation if applicable

fechaReinicioActividades · String

Date of activity resumption if applicable

fechaActualizacion · String

Last update date of taxpayer information

representantesLegales · String

JSON string containing legal representatives information

motivoCancelacionSuspension · String

Reason for cancellation or suspension if applicable

contribuyenteFantasma · String

Ghost taxpayer flag indicator

transaccionesInexistentes · String

Non-existent transactions flag

establecimientos · String

JSON string with establishment information

tipoPersona · String

Person type (Natural/Legal)

codigoPersona · Int

Internal person code

rootEstadoTributarioFecha · Long

Tax status date timestamp

textoEstadoTributario · String

Tax status description text

deudasFirmes · Boolean

Indicates if there are firm debts

dtMotivos · String

JSON string with debt reasons

dtObligacionesPendientes · String

JSON string with pending obligations

dtObligacionesPendientesPresentacion · String

JSON string with pending filing obligations

dtObligacionesPendientesPago · String

JSON string with pending payment obligations

createdAt · DateTime!

Record creation timestamp

updatedAt · DateTime!

Record last update timestamp

Implementation Details

Repository

The ApiSriRepository class provides data access operations:

Location: Services/ApiSri/ApiSriRepository.cs

Methods

• Create(ApiSriDTO) - Creates a new SRI record
• Update(ApiSriDTO) - Updates an existing SRI record
• GetByRuc(string) - Retrieves the most recent record by RUC
• GetById(int) - Retrieves a record by ID

Data Storage

SRI data is stored in the ind_ac_apisri database table with automatic timestamp tracking.

RUC Format Handling

The query automatically handles both RUC formats:

• 10-digit format: Automatically appends “001” to create the 13-digit RUC
• 13-digit format: Used as provided

Error Handling

APISRIDTO_NOT_FOUND

Thrown when no SRI record exists for the provided RUC.

{
  "errors": [{
    "message": "ApiSriDTO NOT_FOUND.",
    "extensions": {
      "code": "APISRIDTO_NOT_FOUND"
    }
  }]
}

Example Usage

Query with 10-digit RUC

query {
  getApiSriByRuc(ruc: "1234567890") {
    numeroRuc
    razonSocial
    estadoContribuyenteRuc
    actividadEconomicaPrincipal
    obligadoLlevarContabilidad
  }
}

Query with 13-digit RUC

query {
  getApiSriByRuc(ruc: "1234567890001") {
    numeroRuc
    razonSocial
    estadoContribuyenteRuc
    representantesLegales
    deudasFirmes
  }
}

Response Example

{
  "data": {
    "getApiSriByRuc": {
      "id": 12345,
      "numeroRuc": "1234567890001",
      "razonSocial": "EMPRESA EJEMPLO S.A.",
      "estadoContribuyenteRuc": "ACTIVO",
      "actividadEconomicaPrincipal": "Fabricación de productos alimenticios",
      "tipoContribuyente": "SOCIEDADES",
      "regimen": "REGIMEN GENERAL",
      "obligadoLlevarContabilidad": "SI",
      "agenteRetencion": "SI",
      "contribuyenteEspecial": "NO",
      "fechaInicioActividades": "2020-01-15",
      "deudasFirmes": false,
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-15T10:30:00Z"
    }
  }
}

Best Practices

1. Cache Management: SRI data is relatively static. Consider caching results appropriately.
2. RUC Validation: Validate RUC format before querying to ensure proper structure.
3. Error Handling: Always handle the APISRIDTO_NOT_FOUND error for non-existent RUCs.
4. Timestamp Tracking: Use updatedAt to determine data freshness.