# Enumerar instituciones

## ▶️ Uso

Con el método List Institutions, puedes:

1. Listar todas las instituciones disponibles en Belvo.

## 📖 Paginación

Este método devuelve una respuesta paginada (por defecto: 100 elementos por página). Puedes usar el parámetro de consulta page_size para aumentar el número de elementos devueltos hasta un máximo de 1000 elementos. Puedes usar el parámetro de consulta page para navegar a través de los resultados. Para más detalles sobre cómo navegar por las respuestas paginadas de Belvo, consulta nuestro artículo Consejos de paginación.

## 🔦 Filtrado de Respuestas

Consulta la lista de consultas a continuación para ver una lista de campos por los que puedes filtrar tus respuestas. Para más información sobre cómo usar filtros, consulta nuestro artículo Filtrado de respuestas.

Endpoint: GET /api/institutions/
Version: 1.223.0
Security: basicAuth

## Query parameters:

  - `page_size` (integer)
    Indica cuántos resultados devolver por página. Por defecto, devolvemos 100 resultados por página.

ℹ️ El número mínimo de resultados devueltos por página es 1 y el máximo es 1000. Si introduces un valor mayor que 1000, nuestra API usará por defecto el valor máximo (1000).
    Example: 100

  - `page` (integer)
    Un número de página dentro del conjunto de resultados paginados.
    Example: 1

  - `display_name` (string)
    Devuelve las instituciones que coinciden parcialmente con este nombre para mostrar.
    Example: "Erebor Bank"

  - `country_code` (string)
    Devuelve instituciones solo para este código de país de dos letras.
    Example: "MX"

  - `country_code__in` (array)
    Devuelve instituciones solo para estos códigos de país de dos letras.
    Example: ["BR"]

  - `resources__allin` (array)
    Devuelve las instituciones que apoyan esta combinación de recursos.
    Example: ["OWNERS"]

  - `name` (string)
    Devuelve una institución con este nombre designado por Belvo.
    Example: "planet_mx_retail"

  - `name__in` (array)
    Devuelve instituciones con uno o más de estos nombres designados por Belvo.
    Example: ["planet_mx_retail"]

  - `status` (string)
    Devuelve las instituciones con el estado dado. Puedes elegir entre healthy o down.
    Example: "healthy"

  - `status__in` (array)
    Devolver instituciones con uno de los estados dados. Puedes elegir entre healthy o down.
    Example: ["healthy"]

  - `type` (string)
    Devolver instituciones de este tipo. Puede elegir entre bank, fiscal o employment.
    Enum: "bank", "fiscal", "employment"

  - `type__in` (array)
    Devuelve instituciones de uno de estos tipos. Puedes elegir entre bank, fiscal o employment.
    Enum: same as `type` (3 values)

  - `website` (string)
    Devuelve instituciones con esta URL de sitio web.
    Example: "https://www.erebor.mx"

## Response 200 fields (application/json):

  - `count` (integer)
    El número total de resultados en tu cuenta de Belvo.
    Example: 130

  - `next` (string,null)
    La URL a la siguiente página de resultados. Cada página consta de hasta 100 elementos. Si no hay suficientes resultados para una página adicional, el valor es null.

En nuestro ejemplo de documentación, usamos {endpoint} como un valor de marcador de posición. En producción, este valor será reemplazado por el endpoint real que estás utilizando actualmente (por ejemplo, accounts o owners).
    Example: "https://sandbox.belvo.com/api/{endpoint}/?link=1bd948f7-245d-4313-b604-34d1044cb908page=2"

  - `previous` (string,null)
    La URL a la página anterior de resultados. Si no hay una página anterior, el valor es null.

  - `results` (array)
    Matriz de objetos de institución.

  - `results.id` (integer)
    El ID de la institución según lo designado por Belvo.
    Example: 1003

  - `results.name` (string)
    El nombre de la institución, según lo designado por Belvo.
    Example: "erebor_mx_retail"

  - `results.type` (string)
    El tipo de institución. Devolvemos uno de los siguientes valores:

  - bank
  - fiscal
  - employment
    Enum: same as `type` (3 values)

  - `results.website` (string,null)
    La URL del sitio web de la institución.
    Example: "https://www.erebor.com/"

  - `results.display_name` (string)
    El nombre de cara al cliente de la institución.
    Example: "Erebor Mexico"

  - `results.country_codes` (array)
    Los códigos de país donde la institución está disponible, por ejemplo:
- 🇧🇷 BR (Brasil)
- 🇨🇴 CO (Colombia)
- 🇲🇽 MX (México)
    Example: ["MX"]

  - `results.primary_color` (string)
    El color primario en el sitio web de la institución.
    Example: "#056dae"

  - `results.logo` (string,null)
    La URL del logotipo de la institución.
    Example: "https://belvo-api-media.s3.amazonaws.com/logos/erebor_logo.svg"

  - `results.icon_logo` (string,null)
    La URL del logotipo del icono de la institución.
    Example: "https://statics.belvo.io/widget/images/institutions/erebor.svg"

  - `results.text_logo` (string,null)
    La URL del logotipo de texto de la institución.
    Example: "https://statics.belvo.io/widget/images/institutions/erebor.svg"

  - `results.form_fields` (array)

  - `results.form_fields.name` (string)
    El campo de nombre de usuario, contraseña o tipo de nombre de usuario.
    Example: "username"

  - `results.form_fields.type` (string)
    El tipo de entrada para el campo del formulario. Por ejemplo, string.
    Example: "text"

  - `results.form_fields.label` (string)
    La etiqueta del campo del formulario. Por ejemplo:
- Client number
- Key Bancanet
- Document
    Example: "Client number"

  - `results.form_fields.validation` (string)
    El tipo de validación de entrada utilizada para el campo.
    Example: "^.{1,}$"

  - `results.form_fields.placeholder` (string)
    El texto del marcador de posición en el campo del formulario.
    Example: "ABC333333A33"

  - `results.form_fields.validation_message` (string)
    El mensaje que se muestra cuando se proporciona una entrada no válida en el campo del formulario.
    Example: "Invalid client number"

  - `results.form_fields.values` (array)
    Si el campo del formulario es para documentos, la institución puede requerir información adicional sobre el tipo de documento.

  - `results.form_fields.values.code` (string)
    El código del documento.
    Example: "001"

  - `results.form_fields.values.label` (string)
    La etiqueta para el campo. Por ejemplo:
- Cédula de Ciudadanía
- Cédula de Extranjería
- Pasaporte
    Example: "Cédula de Ciudadanía"

  - `results.form_fields.values.validation` (string)
    El tipo de validación de entrada utilizada para el campo.
    Example: "^.{1,}$"

  - `results.form_fields.values.validation_message` (string)
    El mensaje que se muestra cuando se proporciona una entrada no válida en el campo del formulario.
    Example: "Invalid document number"

  - `results.form_fields.values.placeholder` (string)
    El texto del marcador de posición en el campo del formulario.
    Example: "DEF4444908M22"

  - `results.features` (array)
    Las características que la institución admite. Si la institución no tiene características especiales, entonces Belvo devuelve un array vacío.

Aquí hay una lista de las características disponibles:
- token_required indica que la institución puede requerir un token durante la creación del enlace o al realizar cualquier otra solicitud.

  - `results.features.name` (string)
    El nombre de la característica.
    Example: "token_required"

  - `results.features.description` (string)
    La descripción de la característica.
    Example: "The institution may require a token during link creation or login"

  - `results.resources` (array)
    Una lista de recursos de Belvo que puedes usar con la institución. Esta lista incluye uno o más de los siguientes recursos:

  - ACCOUNTS
  - BALANCES
  - BILLS
  - EMPLOYMENTS
  - EMPLOYMENT_RECORDS
  - FINANCIAL_STATEMENTS
  - INCOMES
  - INVESTMENTS
  - INVESTMENT_TRANSACTIONS
  - INVOICES
  - OWNERS
  - RECURRING_EXPENSES
  - RISK_INSIGHTS
  - TRANSACTIONS
  - TAX_COMPLIANCE_STATUS
  - TAX_RETENTIONS
  - TAX_RETURNS
  - TAX_STATUS
    Example: ["ACCOUNTS","BALANCES","INCOMES","OWNERS","RECURRING_EXPENSES","RISK_INSIGHTS","TRANSACTIONS"]

  - `results.integration_type` (string)
    El tipo de tecnología utilizada para acceder a la institución. Devolvemos uno de los siguientes valores:

- credentials: Utiliza la tecnología de scraping de Belvo, combinada con las credenciales del usuario, para realizar solicitudes.
- openfinance: Utiliza la API de open finance del banco para realizar solicitudes.
    Enum: "credentials", "openfinance"

  - `results.status` (string)
    Indica si la integración de Belvo con la institución está actualmente activa (healthy) o en mantenimiento (down).
    Enum: "healthy", "down"

  - `results.openbanking_information` (object,null)
    Información sobre la institución en el entorno de Open Finance.

  - `results.openbanking_information.description` (string,null)
    Una breve descripción de la institución en el entorno de Open Finance. Extraído del listado de instituciones reguladas por Open Finance.
    Example: "A 1ss Bank é uma fintech fundada em janeiro de 2020, com a missão de ajudar empresas com grandes ecossistemas a se tornarem fintechs, integrando e automatizando seus processos financeiros através de APIs e plataforma white-label."

  - `results.openbanking_information.participants` (array,null)
    Lista de servidores de marcas disponibles de la institución en Open Finance. Extraído de la lista de instituciones reguladas por Open Finance.
    Example: ["1ss Bank"]

  - `results.openbanking_information.authorization_server_id` (string,null)
    El ID del servidor de autorización (UUID) de la institución en el Entorno de Finanzas Abiertas.
    Example: "aa18fcd3-2f0b-40b1-87db-8930b10b78b1"

  - `results.code` (string,null)
    Este campo está obsoleto y se eliminará en una versión futura. Por favor, utilice el campo id en su lugar, que es el identificador único para la institución.

## Response 403 fields (application/json):

  - `code` (string)
    Un código de error único (access_to_resource_denied) que te permite clasificar y manejar el error de manera programática.

ℹ️ Consulta nuestro DevPortal para obtener más información sobre cómo manejar 403 access_to_resource_denied.
    Example: "access_to_resource_denied"

  - `message` (string)
    Una breve descripción del error.

Para los errores access_to_resource_denied, la descripción es:

  - You don't have access to this resource..
    Example: "You don't have access to this resource."

  - `request_id` (string)
    Un ID único de 32 caracteres de la solicitud (que coincide con un patrón regex de: [a-f0-9]{32}). Proporcione este ID al contactar al equipo de soporte de Belvo para acelerar las investigaciones.
    Example: "9e7b283c6efa449c9c028a16b5c249fb"

## Response 404 fields (application/json):

  - `code` (string)
    Un código de error único (not_found) que te permite clasificar y manejar el error de manera programática.
    Example: "not_found"

  - `message` (string)
    Una breve descripción del error.

Para errores not_found, la descripción es:

  - Not found
    Example: "Not found"

  - `request_id` (string)
    Un ID único de 32 caracteres de la solicitud (que coincide con un patrón regex de: [a-f0-9]{32}). Proporcione este ID al contactar al equipo de soporte de Belvo para acelerar las investigaciones.
    Example: "9e7b283c6efa449c9c028a16b5c249fb"

## Response 408 fields (application/json):

  - `code` (string)
    Un código de error único (request_timeout) que te permite clasificar y manejar el error de manera programática.

ℹ️ Consulta nuestro DevPortal para obtener más información sobre cómo manejar errores 408 request_timeout.
    Example: "request_timeout"

  - `message` (string)
    Una breve descripción del error.

Para los errores de request_timeout, la descripción es:

  - The request timed out, you can retry asking for less data by changing your query parameters.
    Example: "The request timed out, you can retry asking for less data by changing your query parameters"

  - `request_id` (string)
    Un ID único de 32 caracteres de la solicitud (que coincide con un patrón regex de: [a-f0-9]{32}). Proporcione este ID al contactar al equipo de soporte de Belvo para acelerar las investigaciones.
    Example: "9e7b283c6efa449c9c028a16b5c249fb"

## Response 500 fields (application/json):

  - `code` (string)
    Un código de error único (unexpected_error) que te permite clasificar y manejar el error de manera programática.

ℹ️ Consulta nuestro DevPortal para obtener más información sobre cómo manejar errores 500 unexpected_error.
    Example: "unexpected_error"

  - `message` (string)
    Una breve descripción del error.

Para los errores unexpected_error, la descripción es:

- Belvo no puede procesar la solicitud debido a un problema interno del sistema o a una respuesta no soportada de una institución.
    Example: "Belvo is unable to process the request due to an internal system issue or to an unsupported response from an institution"

  - `request_id` (string)
    Un ID único de 32 caracteres de la solicitud (que coincide con un patrón regex de: [a-f0-9]{32}). Proporcione este ID al contactar al equipo de soporte de Belvo para acelerar las investigaciones.
    Example: "9e7b283c6efa449c9c028a16b5c249fb"