Skip to main content

​
Introduction

The FacturaScripts REST API provides programmatic access to your FacturaScripts installation, allowing you to integrate with external applications, automate workflows, and build custom integrations. The API follows REST principles and uses JSON for request and response bodies. All API endpoints require authentication using API keys.

​
Base URL

The API is accessed through your FacturaScripts installation URL with the /api prefix: 
https://your-domain.com/api/{version}/{resource}

​
Example

https://example.com/api/3/facturacliente

​
API Versioning

The FacturaScripts API uses version numbers in the URL path. The current API version is v3.
All API requests must include the version number in the URL. The current version is 3.

​
Version in URL

/api/3/{resource}
If you attempt to use an invalid or missing version, you’ll receive a 400 Bad Request error: 
{
  "error": "api-version-invalid"
}

​
Enabling the API

Before using the API, you must enable it in your FacturaScripts installation:
  1. Navigate to Settings in your FacturaScripts admin panel
  2. Enable the API option
  3. Create an API key for authentication (see Authentication)
Alternatively, you can set a global API key in your configuration file by defining the api_key constant.

​
Request Format

All API requests must:
  • Use HTTPS (recommended for production)
  • Include an X-Auth-Token header with a valid API key
  • Use appropriate HTTP methods (GET, POST, PUT, DELETE)
  • Send request bodies as JSON for POST/PUT requests

​
HTTP Methods

The API supports standard REST HTTP methods:
MethodDescription
GETRetrieve resources
POSTCreate new resources
PUT/PATCHUpdate existing resources
DELETEDelete resources
OPTIONSCORS preflight requests

​
Response Format

All API responses are returned in JSON format with appropriate HTTP status codes.

​
Success Response

{
  "doc": {
    "idempresa": 1,
    "codcliente": "CUST001",
    "total": 1000.00
  },
  "lines": [
    {
      "referencia": "PROD001",
      "cantidad": 2,
      "pvpunitario": 500.00
    }
  ]
}

​
Error Response

{
  "status": "error",
  "message": "customer-not-found"
}

​
HTTP Status Codes

The API uses standard HTTP status codes:
CodeDescription
200Success
201Created
400Bad Request - Invalid parameters
401Unauthorized - Invalid API key
403Forbidden - Insufficient permissions
404Not Found - Resource doesn’t exist
405Method Not Allowed
422Unprocessable Entity - Validation failed
500Internal Server Error

​
Rate Limiting

The API implements basic rate limiting through an incident tracking system:
  • Maximum of 5 failed authentication attempts within 10 minutes
  • After reaching the limit, the IP address is temporarily banned
  • Incidents expire after 10 minutes (600 seconds)
Repeated authentication failures will result in your IP address being temporarily blocked from accessing the API.

​
CORS Support

The API supports Cross-Origin Resource Sharing (CORS) for browser-based applications:
  • Access-Control-Allow-Origin: * (all origins)
  • Access-Control-Allow-Methods: GET, POST, PUT, DELETE, PATCH, OPTIONS
  • Access-Control-Allow-Headers: Custom headers as requested

​
Preflight Requests

The API handles OPTIONS requests for CORS preflight: 
OPTIONS /api/3/facturacliente HTTP/1.1
Host: example.com
Access-Control-Request-Method: POST
Access-Control-Request-Headers: X-Auth-Token

​
Available Resources

To list all available API resources, make a GET request to the API root: 
GET /api/3/
X-Auth-Token: your-api-key

​
Response

{
  "resources": [
    "albarancliente",
    "albaranproveedor",
    "attachedfiles",
    "cliente",
    "crearFacturaCliente",
    "exportarFacturaCliente",
    "facturacliente",
    "facturaproveedor",
    "pagarFacturaCliente",
    "plugins",
    "producto",
    "uploadFiles"
  ]
}

​
Model Resources

The API automatically exposes most FacturaScripts models as API resources. These are located in /Dinamic/Lib/API/ and provide standard CRUD operations.

​
Standard Operations

  • GET /api/3/{model} - List all records
  • GET /api/3/{model}/{id} - Get single record
  • GET /api/3/{model}/schema - Get model schema
  • POST /api/3/{model} - Create new record
  • PUT /api/3/{model}/{id} - Update record
  • DELETE /api/3/{model}/{id} - Delete record

​
Custom Endpoints

In addition to model resources, FacturaScripts provides custom endpoints for specific operations:
  • Document creation (invoices, orders, quotes)
  • Document export (PDF generation)
  • Payment processing
  • File upload and management
  • Plugin management
See the Endpoints documentation for detailed information on each custom endpoint.

​
Error Handling

Always check the HTTP status code and parse the response JSON for error messages: 
if (response.status >= 400) {
  const error = await response.json();
  console.error('API Error:', error.message);
}

​
Next Steps

Authentication

Learn how to authenticate API requests

Endpoints

Explore available API endpoints

Build docs developers (and LLMs) love

Get started for freeTalk to us