Buscar distritos

Busca distritos por nombre o código SIFEN. Permite búsquedas flexibles. Retorna la información completa con departamento anidado y paginación.

Entorno

URL Base: https://api.guarani.app

Endpoint

GET /distritos/search?q={query}&page={page}&limit={limit}

Ejemplo de solicitud

curl -X GET "https://api.guarani.app/distritos/search?q=santa&page=1&limit=10" \
  -H "x-api-key: Bearer <access_token>" \
  -H "Accept: application/json" | jq

Nota: Asegúrate de reemplazar {query} por el parámetro a buscar y <access_token> con un token JWT válido proporcionado por el equipo Guarani.
Importante:
Es imprescindible incluir un token de acceso válido en el encabezado x-api-key para autenticar y autorizar el uso de este endpoint. Sin este token, la solicitud será rechazada.

Parámetros de consulta

Parámetro	Tipo	Requerido	Descripción
`q`	`string`	Sí	Parámetro de búsqueda
`page`	`integer`	No	Número de página. Por defecto: `1`.
`limit`	`integer`	No	Resultados por página. Por defecto: `10`.

Encabezados de la Solicitud

Encabezado	Valor	Descripción
`x-api-key`	`Bearer <access_token>`	Token de autenticación necesario para acceder al recurso.
`Accept`	`application/json`	Indica que la respuesta debe devolverse en formato JSON.

Ejemplo de respuesta

{
  "success": true,
  "codigo": 200,
  "message": "Operación realizada correctamente.",
  "data": [
    {
      "id": "78d49201-91f9-4e6c-aadb-4927f56767c0",
      "codigo_sifen": "209",
      "nombre": "SANTA RITA",
      "departamento": {
        "id": "750d3163-6a53-45df-b349-e8139d1ff3a9",
        "codigo_sifen": "11",
        "nombre": "ALTO PARANA"
      }
    }
  ],
  "pagination": {
    "total_registros": 1,
    "pagina": 1,
    "total_paginas": 1
  }
}

Descripción de la respuesta

Campo	Tipo	Descripción
`success`	`boolean`	Indica si la operación fue exitosa
`codigo`	`string`	Código de respuesta
`message`	`string`	Mensaje descriptivo
`data`	`array`	Array de distritos encontrados
`data[].id`	`string`	ID único del distrito (UUID)
`data[].codigo_sifen`	`string`	Código SIFEN del distrito
`data[].nombre`	`string`	Nombre del distrito
`data[].departamento`	`object`	Información del departamento
`data[].departamento.id`	`string`	ID único del departamento (UUID)
`data[].departamento.codigo_sifen`	`string`	Código SIFEN del departamento
`data[].departamento.nombre`	`string`	Nombre del departamento
`pagination`	`object`	Información de paginación
`pagination.total_registros`	`integer`	Total de registros encontrados
`pagination.pagina`	`integer`	Página actual
`pagination.total_paginas`	`integer`	Total de páginas

Ejemplos de respuesta con error

Error: No se encontraron distritos

{
  "success": false,
  "codigo": "DISTRITO_NO_ENCONTRADO",
  "message": "Distrito no encontrado",
  "error": "No se encontraron distritos con el parametro: xyz123"
}

Error: Parámetro de búsqueda vacío

{
  "success": false,
  "codigo": "SOLICITUD_NO_VALIDA",
  "message": "Solicitud no válida",
  "error": "El parámetro de búsqueda es requerido"
}

Recursos adicionales

Para obtener un distrito específico por ID, consulta Obtener distrito por ID
Para listar todos los distritos con paginación, consulta Obtener distritos
Para obtener distritos de un departamento específico, consulta Obtener distritos por departamento
Para información sobre errores, consulta Códigos de error