{
  "openapi": "3.1.0",
  "info": {
    "title": "TU RUC - API REST",
    "description": "Documentación técnica de la API de Tu Ruc para desarrolladores.",
    "termsOfService": "https://swagger.io/about/",
    "license": {
      "name": "Apache 2.0",
      "url": "https://springdoc.org/"
    }
  },
  "servers": [
    {
      "url": "https://turuc.com.py"
    }
  ],
  "paths": {
    "/api/contribuyente": {
      "get": {
        "tags": [
          "API de contribuyentes"
        ],
        "summary": "Obtener un contribuyente a partir de su RUC o documento por parámetro.",
        "description": "Obtiene el contribuyente asociado al RUC o documento proveído.",
        "operationId": "getContribuyenteWithParam",
        "parameters": [
          {
            "name": "ruc",
            "in": "query",
            "description": "RUC o documento del contribuyente deseado.",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 1
            },
            "examples": {
              "Nro. de documento": {
                "description": "Nro. de documento",
                "value": 123456
              },
              "RUC": {
                "description": "RUC",
                "value": "123456-7"
              }
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Contribuyente encontrado satisfactoriamente.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ContribuyenteResponse"
                }
              }
            }
          },
          "400": {
            "description": "Se recibió un parámetro inválido.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GenericResponse"
                }
              }
            }
          },
          "500": {
            "description": "Error interno, favor reportar a soporte.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GenericResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/contribuyente/{ruc}": {
      "get": {
        "tags": [
          "API de contribuyentes"
        ],
        "summary": "Obtener un contribuyente a partir de su RUC o documento por variable en la URL.",
        "description": "Obtiene el contribuyente asociado al RUC o documento proveído.",
        "operationId": "getContribuyenteWithPath",
        "parameters": [
          {
            "name": "ruc",
            "in": "path",
            "description": "RUC o documento del contribuyente deseado.",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 1
            },
            "examples": {
              "Nro. de documento": {
                "description": "Nro. de documento",
                "value": 123456
              },
              "RUC": {
                "description": "RUC",
                "value": "123456-7"
              }
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Contribuyente encontrado satisfactoriamente.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ContribuyenteResponse"
                }
              }
            }
          },
          "400": {
            "description": "Se recibió un parámetro inválido.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GenericResponse"
                }
              }
            }
          },
          "500": {
            "description": "Error interno, favor reportar a soporte.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GenericResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/contribuyente/table": {
      "get": {
        "tags": [
          "API de contribuyentes"
        ],
        "summary": "Obtener un listado de contribuyentes en formato de datatable.",
        "description": "Obtiene una lista de contribuyentes y la cantidad de contribuyentes filtrados. Formato habitual de datatable.",
        "operationId": "searchContribuyentesTable",
        "parameters": [
          {
            "name": "draw",
            "in": "query",
            "description": "Valor constante. Se retornará el mismo valor recibido",
            "required": true,
            "schema": {
              "type": "integer",
              "format": "int32"
            },
            "example": 2
          },
          {
            "name": "start",
            "in": "query",
            "description": "Tamaño del salto.",
            "required": true,
            "schema": {
              "type": "integer",
              "format": "int32"
            },
            "example": 25
          },
          {
            "name": "length",
            "in": "query",
            "description": "Longitud de la lista de contribuyentes. Como máximo 20.",
            "required": true,
            "schema": {
              "type": "integer",
              "format": "int32"
            },
            "example": 15
          },
          {
            "name": "search",
            "in": "query",
            "description": "Nombre, RUC o documento de los contribuyentes deseados. Entre 3 y 50 carácteres.",
            "required": true,
            "schema": {
              "type": "string"
            },
            "examples": {
              "Nro. de documento": {
                "description": "Nro. de documento",
                "value": 123456
              },
              "RUC": {
                "description": "RUC",
                "value": "123456-7"
              },
              "Razón social": {
                "description": "Razón social",
                "value": "Juan Perez"
              }
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Contribuyentes encontrados satisfactoriamente.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DataTableFormatResponse"
                }
              }
            }
          },
          "400": {
            "description": "Se recibió un parámetro inválido.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GenericResponse"
                }
              }
            }
          },
          "500": {
            "description": "Error interno, favor reportar a soporte.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GenericResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/contribuyente/search": {
      "get": {
        "tags": [
          "API de contribuyentes"
        ],
        "summary": "Obtener un listado de contribuyentes y el número de páginas.",
        "description": "Obtiene una lista de contribuyentes y el número de páginas de contribuyentes que estén relacionados al parámetro de búsqueda.",
        "operationId": "searchContribuyentesSimple",
        "parameters": [
          {
            "name": "search",
            "in": "query",
            "description": "Nombre, RUC o documento de los contribuyentes deseados. Entre 3 y 50 carácteres.",
            "required": true,
            "schema": {
              "type": "string",
              "maxLength": 50,
              "minLength": 3
            },
            "examples": {
              "Nro. de documento": {
                "description": "Nro. de documento",
                "value": 123456
              },
              "RUC": {
                "description": "RUC",
                "value": "123456-7"
              },
              "Razón social": {
                "description": "Razón social",
                "value": "Juan Perez"
              }
            }
          },
          {
            "name": "page",
            "in": "query",
            "description": "Número de página.",
            "required": true,
            "schema": {
              "type": "integer",
              "format": "int32"
            },
            "examples": {
              "Primera página": {
                "description": "Primera página",
                "value": 0
              },
              "Segunda página": {
                "description": "Segunda página",
                "value": 2
              }
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Contribuyentes encontrados satisfactoriamente.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SearchContribuyentesResponse"
                }
              }
            }
          },
          "400": {
            "description": "Se recibió un parámetro inválido.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GenericResponse"
                }
              }
            }
          },
          "500": {
            "description": "Error interno, favor reportar a soporte.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GenericResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/contribuyente/persona-juridica": {
      "get": {
        "tags": [
          "API de contribuyentes"
        ],
        "summary": "Obtener una persona jurídica a partir de su RUC o documento por parámetro.",
        "description": "Obtiene el persona jurídica asociado al RUC o documento proveído.",
        "operationId": "searchContribuyentesPersonaJuridica",
        "parameters": [
          {
            "name": "ruc",
            "in": "query",
            "description": "RUC o documento de la persona jurídica deseada. Entre 3 y 50 carácteres.",
            "required": true,
            "schema": {
              "type": "string",
              "maxLength": 50,
              "minLength": 3
            },
            "examples": {
              "Nro. de documento": {
                "description": "Nro. de documento",
                "value": 80024191
              },
              "RUC": {
                "description": "RUC",
                "value": "80024191-6"
              }
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Persona jurídica encontrado satisfactoriamente.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PersonaJuridicaResponse"
                }
              }
            }
          },
          "400": {
            "description": "Se recibió un parámetro inválido.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GenericResponse"
                }
              }
            }
          },
          "500": {
            "description": "Error interno, favor reportar a soporte.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GenericResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/contribuyente/entidad-publica": {
      "get": {
        "tags": [
          "API de contribuyentes"
        ],
        "summary": "Obtener una entidad pública a partir de su RUC o documento por parámetro.",
        "description": "Obtiene el entidad pública asociado al RUC o documento proveído.",
        "operationId": "searchContribuyentesEntidadPublica",
        "parameters": [
          {
            "name": "ruc",
            "in": "query",
            "description": "RUC o documento de la entidad pública deseada. Entre 3 y 50 carácteres.",
            "required": true,
            "schema": {
              "type": "string",
              "maxLength": 50,
              "minLength": 3
            },
            "examples": {
              "Nro. de documento": {
                "description": "Nro. de documento",
                "value": 80024191
              },
              "RUC": {
                "description": "RUC",
                "value": "80024191-6"
              }
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Entidad pública encontrado satisfactoriamente.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EntidadPublicaResponse"
                }
              }
            }
          },
          "400": {
            "description": "Se recibió un parámetro inválido.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GenericResponse"
                }
              }
            }
          },
          "500": {
            "description": "Error interno, favor reportar a soporte.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GenericResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/contribuyente/sitemap/meta": {
      "get": {
        "tags": [
          "API de contribuyentes"
        ],
        "summary": "Metadatos del sitemap de contribuyentes.",
        "description": "Total de contribuyentes indexables (personas jurídicas y entidades públicas) y cómo se reparten en páginas para el sitemap.",
        "operationId": "getSitemapMeta",
        "responses": {
          "200": {
            "description": "Metadatos obtenidos satisfactoriamente.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SitemapMetaResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/contribuyente/sitemap": {
      "get": {
        "tags": [
          "API de contribuyentes"
        ],
        "summary": "Página de RUCs indexables para el sitemap.",
        "description": "Devuelve hasta 50.000 RUCs (formato doc-dv) de personas jurídicas y entidades públicas, ordenados por RUC, para generar los sitemaps por contribuyente. Una página fuera de rango devuelve una lista vacía.",
        "operationId": "getSitemapRucs",
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "description": "Número de página, desde 0.",
            "required": false,
            "schema": {
              "type": "integer",
              "format": "int32",
              "default": 0,
              "minimum": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "RUCs obtenidos satisfactoriamente.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SitemapRucsResponse"
                }
              }
            }
          },
          "400": {
            "description": "Se recibió un parámetro inválido.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GenericResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/stats": {
      "get": {
        "tags": [
          "API de contribuyentes"
        ],
        "summary": "Obtener el estado del conjunto de datos.",
        "description": "Cantidad de registros por tabla, fecha del listado publicado por la DNIT y fecha de generación de la base embebida.",
        "operationId": "stats",
        "responses": {
          "200": {
            "description": "Estado del conjunto de datos.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StatsResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ContribuyenteDTO": {
        "type": "object",
        "properties": {
          "doc": {
            "type": "integer",
            "format": "int32",
            "description": "Número de documento",
            "example": 123456
          },
          "razonSocial": {
            "type": "string",
            "description": "Razón social",
            "example": "Juan Perez"
          },
          "dv": {
            "type": "integer",
            "format": "int32",
            "description": "Divisor del RUC",
            "example": 7
          },
          "ruc": {
            "type": "string",
            "description": "RUC completo",
            "example": "123456-7"
          },
          "estado": {
            "type": "string",
            "description": "Indica el estado del RUC",
            "example": "ACTIVO"
          },
          "esPersonaJuridica": {
            "type": "boolean",
            "description": "Indica si el contribuyente es persona jurídica",
            "example": false
          },
          "esEntidadPublica": {
            "type": "boolean",
            "description": "Indica si el contribuyente es entidad pública",
            "example": false
          }
        }
      },
      "ContribuyenteResponse": {
        "type": "object",
        "properties": {
          "data": {
            "$ref": "#/components/schemas/ContribuyenteDTO"
          },
          "message": {
            "type": "string"
          }
        }
      },
      "GenericResponse": {
        "type": "object",
        "properties": {
          "data": {},
          "message": {
            "type": "string"
          }
        }
      },
      "DataTableFormatResponse": {
        "type": "object",
        "properties": {
          "draw": {
            "type": "integer",
            "format": "int32",
            "description": "Indica si se pudo obtener un listado",
            "example": 2
          },
          "recordsTotal": {
            "type": "integer",
            "format": "int64",
            "description": "Indica el número de contribuyentes filtrados",
            "example": 1200
          },
          "recordsFiltered": {
            "type": "integer",
            "format": "int64",
            "description": "Indica el número de contribuyentes filtrados",
            "example": 1200
          },
          "data": {
            "type": "array",
            "description": "Lista de contribuyentes filtrados.",
            "items": {
              "$ref": "#/components/schemas/ContribuyenteDTO"
            }
          }
        }
      },
      "SearchContribuyentesResponse": {
        "type": "object",
        "properties": {
          "data": {
            "$ref": "#/components/schemas/SearchResponse"
          },
          "message": {
            "type": "string"
          }
        }
      },
      "SearchResponse": {
        "type": "object",
        "properties": {
          "contribuyentes": {
            "type": "array",
            "description": "Listado de contribuyentes filtrados.",
            "items": {
              "$ref": "#/components/schemas/ContribuyenteDTO"
            }
          },
          "paginas": {
            "type": "integer",
            "format": "int32",
            "description": "Número de paginas.",
            "example": 10
          }
        }
      },
      "PersonaJuridicaDTO": {
        "type": "object",
        "properties": {
          "razonSocial": {
            "type": "string",
            "description": "Razón social",
            "example": "Empresa S.A."
          },
          "ruc": {
            "type": "integer",
            "format": "int64",
            "description": "RUC completo",
            "example": "123456-7"
          },
          "dv": {
            "type": "integer",
            "format": "int32",
            "description": "Divisor del RUC",
            "example": 7
          },
          "estado": {
            "type": "string",
            "description": "Indica el estado del RUC",
            "example": "ACTIVO"
          },
          "categoria": {
            "type": "string",
            "description": "Categoría de la persona jurídica",
            "example": "MEDIANO"
          }
        }
      },
      "PersonaJuridicaResponse": {
        "type": "object",
        "properties": {
          "data": {
            "$ref": "#/components/schemas/PersonaJuridicaDTO"
          },
          "message": {
            "type": "string"
          }
        }
      },
      "EntidadPublicaDTO": {
        "type": "object",
        "properties": {
          "razonSocial": {
            "type": "string",
            "description": "Razón social",
            "example": "EMPRESA DE SERVICIOS SANITARIOS DEL PARAGUAY SA (ESSAP SA)"
          },
          "ruc": {
            "type": "integer",
            "format": "int64",
            "description": "RUC sin divisor",
            "example": 80024191
          },
          "dv": {
            "type": "integer",
            "format": "int32",
            "description": "Divisor del RUC",
            "example": 6
          },
          "nivel": {
            "type": "integer",
            "format": "int32",
            "description": "Nivel de la entidad pública",
            "example": 40
          },
          "estado": {
            "type": "string",
            "description": "Indica el estado del RUC",
            "example": "ACTIVO"
          },
          "descripcionNivel": {
            "type": "string",
            "description": "Descripción del nivel",
            "example": "Sociedades Anónimas Con Part. Accionaria May. Del Estado"
          },
          "codigoEntidad": {
            "type": "string",
            "description": "Código de la entidad",
            "example": "2"
          },
          "paginaWeb": {
            "type": "string",
            "description": "Página web de la entidad",
            "example": "www.essap.com.py"
          },
          "correo": {
            "type": "string",
            "description": "Correo electrónico de la entidad",
            "example": "info@essap.gov.py"
          },
          "direccion": {
            "type": "string",
            "description": "Dirección de la entidad",
            "example": "José Berges 516 E/ San José Y Brasil"
          },
          "telefono": {
            "type": "string",
            "description": "Telefono de la entidad",
            "example": "0800110888"
          },
          "sigla": {
            "type": "string",
            "description": "Sigla que representa a la entidad",
            "example": "ESSAP"
          },
          "anho": {
            "type": "integer",
            "format": "int32",
            "description": "Año",
            "example": 2024
          }
        }
      },
      "EntidadPublicaResponse": {
        "type": "object",
        "properties": {
          "data": {
            "$ref": "#/components/schemas/EntidadPublicaDTO"
          },
          "message": {
            "type": "string"
          }
        }
      },
      "StatsDTO": {
        "type": "object",
        "properties": {
          "contribuyentes": {
            "type": "integer",
            "format": "int32",
            "example": 2014770
          },
          "personasJuridicas": {
            "type": "integer",
            "format": "int32",
            "example": 152683
          },
          "entidadesPublicas": {
            "type": "integer",
            "format": "int32",
            "example": 414
          },
          "actualizado": {
            "type": "string",
            "description": "Fecha del listado publicado por la DNIT",
            "example": "2026-09-15"
          },
          "generado": {
            "type": "string",
            "description": "Fecha de generación de la base embebida",
            "example": "2026-09-16T00:28:12+00:00"
          },
          "version": {
            "type": "string",
            "description": "Etiqueta de la imagen en ejecución",
            "example": "2026.09.16-ef976ed"
          }
        }
      },
      "StatsResponse": {
        "type": "object",
        "properties": {
          "data": {
            "$ref": "#/components/schemas/StatsDTO"
          },
          "message": {
            "type": "string",
            "example": "OK"
          }
        }
      },
      "SitemapMetaDTO": {
        "type": "object",
        "properties": {
          "total": {
            "type": "integer",
            "format": "int32",
            "description": "Contribuyentes indexables",
            "example": 152686
          },
          "pageSize": {
            "type": "integer",
            "format": "int32",
            "description": "RUCs por página",
            "example": 50000
          },
          "pages": {
            "type": "integer",
            "format": "int32",
            "example": 4
          }
        }
      },
      "SitemapMetaResponse": {
        "type": "object",
        "properties": {
          "data": {
            "$ref": "#/components/schemas/SitemapMetaDTO"
          },
          "message": {
            "type": "string",
            "example": "OK"
          }
        }
      },
      "SitemapRucsResponse": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "type": "string",
              "example": "80024191-6"
            }
          },
          "message": {
            "type": "string",
            "example": "OK"
          }
        }
      }
    }
  }
}
