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ónMétodo y rutaRespuesta correcta
ListarGET /api/3/clientesArray JSON + X-Total-Count.
Obtener unoGET /api/3/clientes/<código>Objeto JSON del registro.
Ver camposGET /api/3/clientes/schemaCampos con tipo, valor por defecto y si admiten nulo.
CrearPOST /api/3/clientes{"ok": "…", "data": {…}}
ModificarPUT /api/3/clientes/<código>{"ok": "Registro actualizado correctamente.", "data": {…}}
BorrarDELETE /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 POST que 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 POST sin clave primaria se corta (tiempo de espera, red), no lo repitas a ciegas: busca antes el registro con un filtro (por ejemplo filter[cifnif]=…) y repite solo si no existe.
  • PUT y DELETE sobre 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.

Captura ampliada

Abrir en otra pestaña

¿Te ha resultado útil esta página?

¿Aún tienes dudas?

Habla con nuestro equipo y te resolvemos cualquier duda al instante.