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

# Estructura general y capacidades de la A3ERP API REST

> Conoce los endpoints de descubrimiento, el modelo de seguridad, los campos disponibles, la paginación, el filtrado y la ordenación de la A3ERP API.

La A3ERP API proporciona acceso programático a los datos de tu instancia SQL Server de A3ERP. Antes de comenzar a consumir los endpoints de negocio, es fundamental que conozcas las capacidades transversales de la API: cómo descubrir los endpoints disponibles, qué campos expone cada vista, cómo autenticar tus peticiones, cómo paginar y ordenar resultados, y cómo aplicar filtros SQL personalizados.

***

## Endpoint de estado

Utiliza el endpoint raíz de la API para obtener un listado completo de todos los endpoints de consulta disponibles en tu instancia.

**`GET /api`**

```http theme={null}
GET /api HTTP/1.1
Host: <domain>:<port>
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
```

Este endpoint requiere un token JWT válido en la cabecera `Authorization`. Devuelve la lista de rutas activas que puedes consultar.

| Código | Descripción                             |
| ------ | --------------------------------------- |
| `200`  | OK — lista de endpoints disponibles     |
| `401`  | Unauthorized — token ausente o inválido |

***

## Descubrimiento de campos

Antes de construir tus consultas, puedes inspeccionar qué campos devuelve cualquier vista de la API.

**`GET /api/campos/{vista}`**

```http theme={null}
GET /api/campos/{vista} HTTP/1.1
Host: <domain>:<port>
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
```

Sustituye `{vista}` por el nombre de la vista que deseas inspeccionar (por ejemplo, `clientes` o `facturas`).

### Respuesta 200 — estructura del objeto `campos`

<ResponseField name="campos" type="array">
  Lista de objetos que describen cada campo disponible en la vista.

  <Expandable title="Propiedades de cada campo">
    <ResponseField name="NombreCampo" type="string">
      Nombre técnico del campo tal como aparece en la respuesta JSON de la API.
    </ResponseField>

    <ResponseField name="Tipo" type="string">
      Tipo de dato del campo (por ejemplo, `varchar`, `int`, `datetime`).
    </ResponseField>

    <ResponseField name="Longitud" type="string">
      Longitud máxima permitida para el campo, cuando aplica.
    </ResponseField>

    <ResponseField name="Descripcion" type="string">
      Descripción legible del propósito o contenido del campo.
    </ResponseField>

    <ResponseField name="PermiteNulos" type="string">
      Indica si el campo acepta valores nulos (`YES` / `NO`).
    </ResponseField>

    <ResponseField name="Cuadrado" type="string">
      Identificador del cuadro o formulario de A3ERP al que pertenece el campo.
    </ResponseField>

    <ResponseField name="Libreria" type="string">
      Librería o módulo de A3ERP que gestiona este campo.
    </ResponseField>
  </Expandable>
</ResponseField>

**Ejemplo de respuesta:**

```json theme={null}
{
  "campos": [
    {
      "NombreCampo": "CodCliente",
      "Tipo": "varchar",
      "Longitud": "15",
      "Descripcion": "Código único del cliente",
      "PermiteNulos": "NO",
      "Cuadrado": "Clientes",
      "Libreria": "GestClientes"
    }
  ]
}
```

***

## Seguridad

La A3ERP API utiliza autenticación mediante **JWT (JSON Web Token)**. El token se obtiene realizando una llamada `POST /api/login` con tus credenciales en Base64 (consulta la sección [Validación](/api/validacion) para más detalles).

Una vez obtenido el token, inclúyelo en **todas** las peticiones dentro de la cabecera `Authorization`:

```http theme={null}
Authorization: Bearer {tu_token_jwt}
```

<Warning>
  Sin un token JWT válido, todos los endpoints devolverán un error **401 Authorization Required**. Asegúrate de renovar el token cuando expire.
</Warning>

***

## Logs

La API registra de forma automática todas las incidencias y resultados de las llamadas en un **fichero de log**. La ubicación de este fichero se configura en el archivo `Config.ini` de tu instalación. Consulta ese fichero para localizar la ruta exacta donde se almacenan los registros de actividad.

***

## Contar registros

En cualquier consulta puedes obtener únicamente el **número total de registros** que devolvería ese endpoint, sin recuperar el contenido completo. Para ello, añade la cabecera `contar` con el valor `T`.

<ParamField header="contar" type="string" required>
  Indica a la API que devuelva el recuento de registros en lugar de los datos. Usa el valor `T`.

  Ejemplo: `contar: T`
</ParamField>

**Ejemplo de petición:**

```http theme={null}
GET /api/{endpoint} HTTP/1.1
Host: <domain>:<port>
Authorization: Bearer YOUR_SECRET_TOKEN
contar: T
Accept: */*
```

**Ejemplo de respuesta:**

```json theme={null}
[
  {
    "registros": 342
  }
]
```

<Note>
  El conteo de registros **no** es compatible con la ruta de ordenación (`/order/…`). Úsalo únicamente sobre el endpoint base.
</Note>

***

## Paginación

Para recorrer conjuntos grandes de datos puedes paginar los resultados combinando la ruta de ordenación con las cabeceras `Page` y `PageSize`.

**URL:** `GET /api/{endpoint}/order/{columna} {asc|desc}`

<ParamField header="Page" type="integer" required>
  Número de página a partir del cual se devuelven resultados. La primera página es `1`.
</ParamField>

<ParamField header="PageSize" type="integer" required>
  Número máximo de registros a devolver por página.
</ParamField>

**Ejemplo de petición (página 2, 25 registros por página, ordenado por `CodCliente` ascendente):**

```http theme={null}
GET /api/clientes/order/CodCliente asc HTTP/1.1
Host: <domain>:<port>
Authorization: Bearer YOUR_SECRET_TOKEN
Page: 2
PageSize: 25
Accept: */*
```

**Ejemplo de respuesta:**

```json theme={null}
[
  {
    "CodCliente": "000026",
    "NomCliente": "Empresa Ejemplo S.L.",
    "Email": "contacto@empresa.es"
  }
]
```

<Note>
  La paginación **requiere** que uses la ruta con `/order/`. Sin la cláusula de ordenación, las cabeceras `Page` y `PageSize` no tienen efecto.
</Note>

***

## Filtrado

Puedes restringir los resultados de cualquier endpoint aplicando un **filtro SQL** directamente en la URL.

**`GET /api/{endpoint}/filtro/{filtro}`**

<ParamField path="filtro" type="string" required>
  Expresión de filtro SQL que se aplicará sobre los registros devueltos por el endpoint. Por ejemplo: `CodCliente='000001'` o `Provincia='Madrid'`.
</ParamField>

**Ejemplo de petición (clientes de Madrid):**

```http theme={null}
GET /api/clientes/filtro/Provincia='Madrid' HTTP/1.1
Host: <domain>:<port>
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
```

**Ejemplo de respuesta:**

```json theme={null}
[
  {
    "CodCliente": "000042",
    "NomCliente": "Distribuciones Madrid S.A.",
    "Provincia": "Madrid"
  }
]
```

<Note>
  Puedes **combinar** filtrado y ordenación en la misma petición: `GET /api/{endpoint}/filtro/{filtro}/order/{columna} {asc|desc}`. Consulta la documentación de cada endpoint para conocer los campos filtrables disponibles.
</Note>

***

## Campos de la base de datos

Si necesitas consultar el listado completo de campos de A3ERP junto con sus tipos y definiciones, descarga el siguiente archivo Excel. Los campos están agrupados por **tabla** (no por vista), por lo que el nombre puede diferir del que expone la API. En caso de duda, consulta con tu proveedor de A3ERP.

<Note>
  Algunos campos no son modificables una vez creados. Si intentas actualizar uno de estos campos, la API devolverá un error controlado indicando que el campo no es modificable.
</Note>

[**Descargar Campos\_a3ERP.xlsx**](https://4077647765-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0sOtLXdM9Nln6L8P8MBe%2Fuploads%2FkJHqePswaGbdevMmD3dd%2FCampos_a3ERP.xlsx?alt=media\&token=4a9f288a-a40c-4451-a555-f58ecbb5f786) — 462 KB