> ## Documentation Index
> Fetch the complete documentation index at: https://docs.onepay.la/llms.txt
> Use this file to discover all available pages before exploring further.

# Listado de ciudades

> Endpoint para obtener el listado de ciudades soportadas por OnePay. Cada ID se usa como `city_id` al crear una empresa.

<Card title="Usado en crear empresa" icon="building" href="/client/companies/create" horizontal>
  El `id` de cada ciudad es el valor que se envía como `city_id` al crear una empresa.
</Card>

### Query Parameters

<ParamField query="filter[name]" type="string" placeholder="bog">
  Filtra ciudades por nombre (búsqueda parcial, case-insensitive).
</ParamField>

<ParamField query="filter[state_id]" type="integer" placeholder="11">
  Filtra ciudades por departamento. Consulta el [endpoint de departamentos](/client/companies/list-states) para obtener los IDs válidos.
</ParamField>

<ParamField query="sort" type="string" default="name">
  Ordenamiento por nombre. Usa `name` para ascendente y `-name` para descendente.
</ParamField>

<ParamField query="per_page" type="integer" default="15">
  Cantidad de resultados por página.
</ParamField>

<ParamField query="page" type="integer" default="1">
  Número de página para paginación.
</ParamField>

### Ejemplos de uso

<Tabs>
  <Tab title="curl">
    ```bash theme={null}
    curl https://api.onepay.la/v1/cities \
      -X GET \
      -H "Authorization: Bearer sk_test_xxx"
    ```

    Con filtro por nombre:

    ```bash theme={null}
    curl "https://api.onepay.la/v1/cities?filter[name]=bog" \
      -X GET \
      -H "Authorization: Bearer sk_test_xxx"
    ```
  </Tab>

  <Tab title="JavaScript">
    ```ts theme={null}
    const response = await fetch('https://api.onepay.la/v1/cities?filter[name]=bog', {
      method: 'GET',
      headers: {
        'Authorization': 'Bearer sk_test_xxx',
      },
    });
    const data = await response.json();
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    import requests

    response = requests.get(
        'https://api.onepay.la/v1/cities',
        params={'filter[name]': 'bog'},
        headers={'Authorization': 'Bearer sk_test_xxx'},
    )
    data = response.json()
    ```
  </Tab>
</Tabs>

### Response

<ResponseField name="data" type="array">
  Lista de ciudades.

  <Expandable title="Propiedades de cada ciudad">
    <ResponseField name="id" type="integer">ID único de la ciudad. Úsalo como `city_id` al crear una empresa.</ResponseField>
    <ResponseField name="name" type="string">Nombre de la ciudad.</ResponseField>

    <ResponseField name="state" type="object">
      Departamento al que pertenece la ciudad.

      <Expandable title="Propiedades del departamento">
        <ResponseField name="id" type="integer">ID del departamento.</ResponseField>
        <ResponseField name="name" type="string">Nombre del departamento.</ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="current_page" type="integer">Página actual.</ResponseField>
<ResponseField name="from" type="integer">Índice del primer registro en la página actual.</ResponseField>
<ResponseField name="last_page" type="integer">Última página disponible.</ResponseField>
<ResponseField name="per_page" type="integer">Cantidad de registros por página.</ResponseField>
<ResponseField name="to" type="integer">Índice del último registro en la página actual.</ResponseField>
<ResponseField name="total" type="integer">Total de ciudades.</ResponseField>

### Ejemplo de respuesta

<ResponseExample>
  ```json 200 theme={null}
  {
    "data": [
      {
        "id": 149,
        "name": "Bogotá",
        "state": {
          "id": 11,
          "name": "Bogotá D.C."
        }
      },
      {
        "id": 312,
        "name": "Medellín",
        "state": {
          "id": 5,
          "name": "Antioquia"
        }
      }
    ],
    "current_page": 1,
    "from": 1,
    "last_page": 74,
    "per_page": 15,
    "to": 15,
    "total": 1102
  }
  ```
</ResponseExample>