Desarrolladores: integrar tu software con la API de Beply
CRUD básico
Patrón general para leer, crear, actualizar y eliminar recursos.
Actualizado el 22 de octubre de 2026
Leer, crear, modificar y borrar registros con la API (CRUD)
Todos los recursos de datos admiten las mismas operaciones. Esta guía las resume con un ejemplo completo sobre clientes; la referencia de recursos detalla cada operación.
Aplicabilidad: API versión 3 · Plan Profesional, con la API activada en el servicio.
Operaciones
| Operación | Método y ruta | Respuesta correcta |
|---|---|---|
| Listar | GET /api/3/clientes | Array JSON + X-Total-Count. |
| Obtener uno | GET /api/3/clientes/<código> | Objeto JSON del registro. |
| Ver campos | GET /api/3/clientes/schema | Campos con tipo, valor por defecto y si admiten nulo. |
| Crear | POST /api/3/clientes | {"ok": "…", "data": {…}} |
| Modificar | PUT /api/3/clientes/<código> | {"ok": "Registro actualizado correctamente.", "data": {…}} |
| Borrar | DELETE /api/3/clientes/<código> | {"ok": "Registro eliminado correctamente!", "data": {…}} |
El identificador de la ruta es la clave primaria del modelo (en clientes, codcliente; en facturas, idfactura). Consúltala con /schema o en la respuesta de un listado.
Crear un cliente
Los campos se envían como formulario, no como JSON:
curl -s -X POST "$BEPLY_URL/api/3/clientes" -H "Token: $BEPLY_TOKEN" \
--data-urlencode "nombre=Suministros Ejemplo SL" \
--data-urlencode "cifnif=B00000000"
Para dejar un campo vacío envía el texto null. Si no envías la clave primaria, el programa la genera; guárdala de la respuesta (data.codcliente) para operar después.
Modificar
curl -s -X PUT "$BEPLY_URL/api/3/clientes/<CODCLIENTE>" -H "Token: $BEPLY_TOKEN" \
--data-urlencode "telefono1=600000000"
Solo cambian los campos que envías. Las reglas de la pantalla siguen aplicándose: un documento bloqueado o una factura con restricciones no se modifica por API.
Descubrir campos con /schema
curl -s "$BEPLY_URL/api/3/clientes/schema" -H "Token: $BEPLY_TOKEN"
Los plugins y los campos personalizados amplían los modelos: no supongas que dos servicios tienen los mismos campos.
Reintentos sin duplicar
- Un
POSTque incluye una clave primaria ya existente devuelve HTTP 400 «Registro duplicado» y no crea nada: envía tu propio código si quieres que el reintento sea seguro. - Si un
POSTsin clave primaria se corta (tiempo de espera, red), no lo repitas a ciegas: busca antes el registro con un filtro (por ejemplofilter[cifnif]=…) y repite solo si no existe. PUTyDELETEsobre el mismo registro se pueden repetir sin crear registros nuevos.
Si algo falla
«Ningún dato recibido por formulario» (HTTP 400) indica que el cuerpo no llegó como formulario. «Ha ocurrido un error mientras se guardaban los datos» (HTTP 400) incluye detrás el motivo de la validación. Más casos en Errores y validaciones.