03 — CRUD básico

Los recursos genéricos de Beply siguen un patrón REST estándar. Estos endpoints sirven para cualquier recurso: clientes, productos, proveedores, agentes, impuestos, series, almacenes, etc.

Para flujos especializados como crear facturas con líneas, marcar pagadas o exportar PDF, hay endpoints dedicados — ver 04 — Facturas.

Obtener un registro concreto

GET /api/3/<recurso>/<id>

El <id> es la clave primaria del modelo (puede ser numérica, alfanumérica o texto).

Ejemplo

curl https://miempresa.beply.es/api/3/clientes/123 \
  -H "Token: a1b2c3d4..."

Respuesta (HTTP 200)

El JSON devuelto contiene todos los campos del modelo:

{
  "codcliente": "123",
  "nombre": "Talleres López, S.L.",
  "cifnif": "B85123456",
  "email": "facturacion@tallereslopez.es",
  "telefono1": "+34 666 777 888",
  "fechaalta": "03-11-2025",
  "regimeniva": "General",
  "personafisica": false,
  "debaja": false,
  "riesgoalcanzado": 1247.50,
  "riesgomax": null
}

📋 Las fechas vienen siempre en formato DD-MM-YYYY (no ISO).

Buscar por un campo que no es PK

Si necesitas localizar un registro por un campo distinto a su PK (por ejemplo, buscar un cliente por teléfono), primero filtra el listado:

GET /api/3/clientes?filter[telefono1]=666777888

Luego, con la PK obtenida, accede al detalle: GET /api/3/clientes/<codcliente>.

Crear un registro

POST /api/3/<recurso>
Content-Type: application/x-www-form-urlencoded
Token: <tu-api-key>

El body se envía como un formulario (no JSON). Solo necesitas mandar los campos requeridos por el modelo — el resto toma sus valores por defecto.

Ejemplo: crear una divisa

curl https://miempresa.beply.es/api/3/divisas \
  -H "Token: a1b2c3d4..." \
  -d "coddivisa=GBP" \
  -d "descripcion=Libra esterlina" \
  -d "simbolo=£" \
  -d "tasaconv=0.86"

Ejemplo: crear un cliente

curl https://miempresa.beply.es/api/3/clientes \
  -H "Token: a1b2c3d4..." \
  -d "codcliente=NUEVO01" \
  -d "nombre=Nuevo Cliente, S.L." \
  -d "cifnif=B12345678" \
  -d "email=info@nuevocliente.es"

Respuesta de éxito (HTTP 200)

Las creaciones genéricas devuelven una estructura con dos campos:

{
  "ok": "Registro actualizado correctamente.",
  "data": {
    "codcliente": "NUEVO01",
    "nombre": "Nuevo Cliente, S.L.",
    "cifnif": "B12345678",
    "email": "info@nuevocliente.es",
    "fechaalta": "20-05-2026",
    "regimeniva": "General",
    "personafisica": false,
    "debaja": false
  }
}

📅 Formato de fecha: las fechas se envían en formato YYYY-MM-DD ("fecha": "2026-05-20") pero llegan en la respuesta en formato DD-MM-YYYY ("fechaalta": "20-05-2026"). Es asimetría heredada del motor — ver README — Formato de fechas.

⚠️ Importante: las creaciones genéricas (POST /api/3/<recurso>) devuelven { "ok": "...", "data": {...} }. Sin embargo, las funciones especiales (como crearFacturaCliente) usan otra estructura — ver 04 — Facturas. Comprueba siempre la respuesta del endpoint concreto que estás llamando.

Modificar un registro

PUT /api/3/<recurso>/<id>
Content-Type: application/x-www-form-urlencoded
Token: <tu-api-key>

Solo necesitas enviar los campos que quieres modificar. El resto se mantiene sin cambios.

Ejemplo: actualizar solo el teléfono de un cliente

curl -X PUT https://miempresa.beply.es/api/3/clientes/123 \
  -H "Token: a1b2c3d4..." \
  -d "telefono1=+34 999 888 777"

El cliente conserva todos los demás campos (nombre, CIF, dirección, etc.).

Eliminar un registro

DELETE /api/3/<recurso>/<id>
Token: <tu-api-key>

No requiere body.

Ejemplo

curl -X DELETE https://miempresa.beply.es/api/3/divisas/GBP \
  -H "Token: a1b2c3d4..."

Respuesta

• Éxito: HTTP 200 OK con JSON confirmando la operación.
• Error: HTTP distinto de 200. Ver formatos exactos en 07 — Errores y validaciones.

Algunos registros no se pueden eliminar si están referenciados por otros (ej. no puedes borrar un cliente con facturas asociadas). El error te lo indica.

💡 PATCH también funciona: la API acepta tanto PUT como PATCH para modificaciones parciales. El comportamiento es equivalente: solo los campos enviados se actualizan.

Obtener el esquema de un modelo

Útil para conocer los campos disponibles, sus tipos y restricciones sin tener que crear o consultar registros.

GET /api/3/<recurso>/schema

Ejemplo

curl https://miempresa.beply.es/api/3/familias/schema \
  -H "Token: a1b2c3d4..."

Respuesta

{
  "codfamilia": {
    "type": "character varying(8)",
    "default": null,
    "is_nullable": "NO"
  },
  "descripcion": {
    "type": "character varying(100)",
    "default": null,
    "is_nullable": "NO"
  },
  "numproductos": {
    "type": "integer",
    "default": "0",
    "is_nullable": "NO"
  }
}

Para cada campo te devuelve:

Propiedad	Significado
type	Tipo PostgreSQL: character varying(N), integer, double precision, boolean, date, text, etc.
default	Valor por defecto si no se envía
is_nullable	"YES" admite nulos, "NO" es obligatorio

Próximos pasos

• 04 — Facturas: endpoints específicos del ciclo de facturación
• 07 — Errores y validaciones: qué pasa cuando algo va mal