API REST de Beply

API REST de Beply: URL base, formatos y primera petición

Con esta guía harás tu primera petición a la API de tu servicio y sabrás qué formato envía y devuelve cada tipo de operación.

Aplicabilidad: API versión 3 · Plan Profesional, con la API activada en el servicio.

Contrato común

Elemento	Valor
URL base	`https://<TU_SERVICIO>.beply.es/api/3/` (la dirección de tu programa seguida de `/api/3/`)
Versión	`3`. Otra versión en la URL devuelve un error de versión.
Autenticación	Cabecera `Token: <TU_CLAVE_API>` (también se acepta `X-Auth-Token`). Ver Autenticación.
Envío en escrituras	Formulario: `application/x-www-form-urlencoded` o `multipart/form-data`. No se envía un cuerpo JSON; las líneas de un documento van como texto JSON dentro del campo `lineas`.
Respuesta	JSON en lecturas, escrituras y errores. Las funciones `exportar…` devuelven el archivo (por defecto PDF), no JSON.
Paginación	`limit` (50 por defecto) y `offset`; el total llega en la cabecera `X-Total-Count`.

Recursos de datos y funciones

Tipo	Convención	Ejemplos	Cuándo usarlo
Recurso de datos	Nombre del modelo en minúsculas y plural	`clientes`, `productos`, `facturaclientes`, `reciboclientes`	Leer, crear, modificar o borrar registros sueltos.
Función	camelCase	`crearFacturaCliente`, `pagarFacturaCliente`, `exportarFacturaCliente`	Operaciones compuestas: documento con líneas y totales, cobro de recibos, exportación.

El nombre del recurso se forma con el modelo en singular más el plural: factura + clientes = facturaclientes (no facturasclientes). Los plugins activos pueden añadir recursos; consulta siempre la lista real con Mostrar recursos disponibles.

Primera petición

Guarda la dirección del servicio y la clave en variables de entorno (no las escribas en el código ni en el navegador):
```
export BEPLY_URL="https://<TU_SERVICIO>.beply.es"
export BEPLY_TOKEN="<TU_CLAVE_API>"
```

Pide la lista de recursos:

curl -s "$BEPLY_URL/api/3/" -H "Token: $BEPLY_TOKEN"

Resultado esperado: HTTP 200 y un JSON con la clave resources:

{ "resources": ["agentes", "albaranclientes", "clientes", "crearFacturaCliente", "…"] }

Ejemplo fallido

Sin cabecera o con una clave errónea la respuesta es HTTP 401:

{ "status": "error", "message": "Clave de API no válida" }

Cinco intentos fallidos desde la misma IP en 10 minutos bloquean esa IP durante 10 minutos (HTTP 429). Corrige la clave antes de repetir.

Facturas y normativa fiscal

Las facturas creadas por API pasan por la misma lógica del programa que las creadas en pantalla: numeración, impuestos y los procesos fiscales que tenga configurados tu servicio (por ejemplo, VeriFactu o TicketBAI si están activos). Comprueba en el programa la configuración fiscal antes de automatizar la emisión.

Siguiente paso

Listar, filtrar y ordenar o Crear facturas.