Documentación Técnica de QuartUp API-1

Integración con QuartUp ERP mediante REST/JSON API

1. Introducción

QuartUp API permite interactuar programáticamente con QuartUp ERP mediante peticiones REST a:

https://erp.quartup.net/api

Formato de respuesta: JSON:API v1.0 (spec) con adaptaciones para QuartUp ERP.
Autenticación requerida: Todas las peticiones necesitan un API Key válido.
Manejo de errores: Respuestas con códigos HTTP estándar y detalles en JSON.

2. Autenticación

Endpoint:

GET https://erp.quartup.net/api/auth

Requisitos:

Incluir en el header:
```
Authorization: Basic API_KEY
```

Respuestas:

Éxito (200 OK):

{ "status": 200, "message": "Autorizado", "token": "TOKEN_ACCESO" }

Error (401 Unauthorized):

{ "status": 401, "message": "No autorizado" }

Uso del token: Incluirlo en el header de peticiones posteriores:

Authorization: Bearer TOKEN_ACCESO

3. Estructura de Peticiones

Base URL:

https://erp.quartup.net/api/{empresa}/{esquema}/{tabla}[/{registro}][?parametros]

empresa y esquema: Identificadores únicos provistos con el API Key.
tabla: Entidad de datos (ej. clientes, facturas).
registro: Opcional. ID específico para operaciones CRUD.

Métodos HTTP y Acciones

Método	Acción	Ejemplo de URL
`GET`	Consultar datos	`/api/demo/test/clientes` (todos) o `/.../clientes/430100308` (uno)
`POST`	Insertar	`/api/demo/test/clientes` (envía JSON en body)
`PUT`	Actualizar	`/api/demo/test/clientes` (envía JSON en body)
`PATCH`	Insertar/Actualizar	`/api/demo/test/clientes` (envía JSON en body)
`DELETE`	Eliminar	`/api/demo/test/clientes/430100308`

NOTA: Estos son las relaciones entre métodos y acciones estándar, pero si es necesario pueden personalizarse y cambiar el método en las acciones inserción/modificación

4. Operaciones Detalladas

4.1. Lectura (GET)

Parámetros Query:

Parámetro	Descripción	Ejemplo
`select`	Columnas a retornar (si no se especifica, se retornan todas).	`?select=nombre,cif`
`init`	Filtros por igualdad de valor.	`?init=precio:50,cantidad:20`
`filter`	Filtros con sintaxis QuartUp ERP (ver tabla abajo).	`?filter=precio:50..100,cantidad:15..`
`order`	Ordenamiento con lista de columnas y `asc`/`desc`.	`?order=nombre:asc,direccion:desc`
`limit`	Límite de registros (se ignora si se usan los dos siguientes parámetros).	`?limit=50`
`page-size`	Registros por página (paginación).	`?page-size=20&page-number=2`
`page-number`	Número de página (paginación).	`?page-size=20&page-number=2`
`include`	Permite añadir registros de tablas relacionadas.	`?include=direcciones,personas`

Sistema de Filtros (parámetro `filter`)

Soporta condiciones avanzadas con sintaxis especial (los carácteres especiales hay que "escaparlos" para evitar que interfieran con los parámetros de la URI):

Para campos numéricos:

50 → Valor exacto (=50).
50..70 → Rango inclusivo (≥50 AND ≤70).
..100 → Valores ≤100.

Para fechas:

5/7/2023 → Fecha exacta.
today.. → Desde hoy en adelante.
p15.. → Desde hace 15 días en adelante (p = pasado).
..f7 → Hasta 7 días en el futuro (f = futuro).

Para texto:

abc → Que contiene "abc".
*abc* → Que contiene "abc" (igual que el caso anterior).
=abc → Exactamente "abc".
abc* → Empieza con "abc".
*abc → Termina con "abc".

Ejemplo combinado:

GET /api/demo/test/pedidos?filter=total:100..500,fecha:today..,cliente:QUARTUP*&select=id,total

4.2. Inserción/Actualización (POST/PUT/PATCH)

Mecanismo de Operación

Las operaciones de creación y modificación de registros utilizan los métodos POST (creación incondicional), PUT (modificación incondicional), o PATCH (creación o modificación según si existe clave primaria o no):

Para INSERT (creación):

El body no debe incluir las columnas de clave primaria o deben tener valores vacíos/cero.

Ejemplo:

{
  "id": "",  // O ausente, o 0 para campos numéricos
  "nombre": "Nuevo Cliente",
  "cif": "X12345678",
}

Para UPDATE (actualización):

El body debe incluir las columnas de clave primaria con valores válidos.

Ejemplo:

{
  "id": "430000002",  // Clave primaria existente
  "nombre": "Cliente Modificado",
  "cif": "B63728828"
}

Respuestas

Éxito: Retorna el registro afectado con todas sus columnas en formato JSON.

{
  "data": {
    "type": "/test/clientes",
    "id": "430000002",
    "attributes": {
      "nombre": "Cliente Modificado",
      "cif": "B63728828",
      "alta": "20230101"
    }
  }
}

Operaciones Masivas

El body puede contener un array de registros para operaciones batch:

[
    {
      // INSERT
      "nombre": "Cliente 1", "cif": "A11111111"
    },
    {
      // UPDATE
      "id": "430000002",
      "nombre": "Cliente 2 Modificado"
    }
]

Respuesta batch:

{
  "data": [
    {
      "type": "/test/clientes",
      "id": "430000123",  // Nuevo ID generado
      "attributes": { "nombre": "Cliente 1", "cif": "A11111111" }
    },
    {
      "type": "/test/clientes",
      "id": "430000002",
      "attributes": { "nombre": "Cliente 2 Modificado" }
    }
  ]
}

Reglas Clave

Clave primaria vacía/cero → INSERT.
Clave primaria con valor → UPDATE.
Operaciones batch: Máximo rendimiento para cargas masivas.
Respuestas: Siempre incluyen el estado final del registro.

4.3. Eliminación (DELETE)