Solavel Documentos
Español
Referencia para desarrolladores

API de finanzas de SolaCount

Versión: v1 URL base: https://solavel.com/api/v1 (sustituir por su dominio) Formato: JSON 33 puntos de conexión

La API de Finanzas de SolaCount permite leer y escribir datos contables mediante programación: clientes, proveedores, facturas de venta y compra, pagos, asientos e informes financieros. Todos los puntos de acceso devuelven JSON. Crear una clave de API →

Autenticación

Cada endpoint protegido requiere tres encabezados:

X-API-Key: solabooks_<prefix>.<secret>
X-Organization-Id: 1
X-Client-Id: 4
  • X-API-Key: la clave completa se muestra una sola vez al crearla, en Configuración → Acceso a la API
  • X-Organization-Id: el ID entero de su organización (visible en la página Acceso a la API)
  • X-Client-Id: su ID de cliente (visible en la página Acceso a la API)
Genere una clave: Ve a Configuración → API Access en SolaCount. La clave completa se muestra una sola vez. Cada clave tiene ámbitos: conceda solo los ámbitos que necesite.

El endpoint GET /api/v1/health no requiere autenticación y puede usarse para verificar la conectividad.

Formato de respuesta

Todas las respuestas usan un sobre JSON coherente.

Objeto único

{
  "success": true,
  "data": { ... }
}

Lista paginada

{
  "success": true,
  "data": [ ... ],
  "meta": {
    "current_page": 1,
    "per_page": 25,
    "total": 100,
    "last_page": 4
  }
}

error

{
  "success": false,
  "error": {
    "code": "error_code",
    "message": "Human readable message."
  }
}

Prueba rápida

Sustituya your_key, 1 y 4 por su clave de API real, su ID de organización y su ID de cliente.

Comprobación de estado (no requiere autenticación)

curl https://solacount.com/api/v1/health

Listar facturas

curl https://solacount.com/api/v1/invoices \
  -H "X-API-Key: your_key" \
  -H "X-Organization-Id: 1" \
  -H "X-Client-Id: 4"

Crear un cliente

curl -X POST https://solacount.com/api/v1/customers \
  -H "X-API-Key: your_key" \
  -H "X-Organization-Id: 1" \
  -H "X-Client-Id: 4" \
  -H "Content-Type: application/json" \
  -d '{"name":"Demo Customer","email":"billing@example.com"}'

Crear un asiento contable

curl -X POST https://solacount.com/api/v1/journal-entries \
  -H "X-API-Key: your_key" \
  -H "X-Organization-Id: 1" \
  -H "X-Client-Id: 4" \
  -H "Content-Type: application/json" \
  -d '{
    "date": "2026-06-07",
    "reference": "JE-001",
    "description": "Manual accrual",
    "lines": [
      {"account_id": 101, "debit": 1000, "credit": 0},
      {"account_id": 202, "debit": 0, "credit": 1000}
    ]
  }'

Todos los endpoints

Haga clic en cualquier endpoint para expandir sus detalles. 33 endpoints en total, distribuidos en 8 grupos de recursos.

Estado

GET /api/v1/health sin autenticación

Confirme que la API está en línea y responde. No se requiere autenticación.

Respuesta HTTP 200

{"success":true,"data":{"service":"finance-api","status":"ok","timestamp":"2026-06-07T12:00:00+00:00"}}

Clientes

GET /api/v1/customers ámbito: customers.get

Lista todos los clientes. Admite búsqueda y paginación.

Parámetros de consulta

ParámetroTipoDescripción
search string opcional Filtrar por nombre, correo electrónico o teléfono (coincidencia parcial)
page integer opcional Número de página (predeterminado: 1)
per_page integer opcional Resultados por página (predeterminado: 25, máximo: 100)

Respuesta HTTP 200

{"success":true,"data":[{"id":1,"name":"Demo Customer","email":"billing@example.com","phone":"+1-555-0100","is_active":true}],"meta":{"current_page":1,"per_page":25,"total":3,"last_page":1}}
GET /api/v1/customers/{id} ámbito: customers.get

Recupera un único cliente por ID.

Respuesta HTTP 200

{"success":true,"data":{"id":1,"name":"Demo Customer","email":"billing@example.com","phone":"+1-555-0100","is_active":true}}
POST /api/v1/customers ámbito: customers.post

Crear un nuevo cliente.

Cuerpo de la solicitud (JSON)

CampoTipoDescripción
name string obligatorio Nombre del cliente
email string opcional Correo electrónico (debe ser válido)
phone string opcional Número de teléfono (máx. 50 caracteres)
is_active boolean opcional Estado activo (predeterminado: true)

Respuesta HTTP 201

{"success":true,"data":{"id":42,"name":"Demo Customer","email":"billing@example.com","phone":null,"is_active":true}}

Proveedores

GET /api/v1/suppliers ámbito: suppliers.get

Lista todos los proveedores. Admite búsqueda y paginación.

Parámetros de consulta

ParámetroTipoDescripción
search string opcional Filtrar por nombre (coincidencia parcial)
page integer opcional Número de página
per_page integer opcional Resultados por página (máximo 100)

Respuesta HTTP 200

{"success":true,"data":[{"id":1,"name":"Demo Supplier","email":"ap@example.com","tax_id":"GB123456789","is_vat_registered":true}],"meta":{"current_page":1,"per_page":25,"total":1,"last_page":1}}
GET /api/v1/suppliers/{id} ámbito: suppliers.get

Recupera un único proveedor por ID.

Respuesta HTTP 200

{"success":true,"data":{"id":1,"name":"Demo Supplier","email":"ap@example.com","phone":null,"tax_id":"GB123456789","is_overseas":false,"is_vat_registered":true,"reverse_charge":false}}
POST /api/v1/suppliers ámbito: suppliers.post

Crear un nuevo proveedor.

Cuerpo de la solicitud (JSON)

CampoTipoDescripción
name string obligatorio Nombre del proveedor
email string opcional Dirección de correo electrónico
phone string opcional Número de teléfono
tax_id string opcional Número de registro de IVA / fiscal
is_overseas boolean opcional Si el proveedor es extranjero (predeterminado: falso)
is_vat_registered boolean opcional Registrado en IVA (predeterminado: verdadero)
reverse_charge boolean opcional Se aplica el IVA por inversión del sujeto pasivo (predeterminado: false)

Respuesta HTTP 201

{"success":true,"data":{"id":15,"name":"Demo Supplier","email":"ap@example.com","tax_id":"GB123456789","is_vat_registered":true}}

Facturas

GET /api/v1/invoices ámbito: invoices.get

Lista todas las facturas con la relación de cliente. Admite filtro por estado y paginación.

Parámetros de consulta

ParámetroTipoDescripción
status string opcional Filtro: draft | unpaid | paid | void | overdue
page integer opcional Número de página
per_page integer opcional Resultados por página (máximo 100)

Respuesta HTTP 200

{"success":true,"data":[{"id":101,"number":"INV-00101","date":"2026-06-01","due_date":"2026-07-01","status":"unpaid","total":5000.00,"customer":{"id":1,"name":"Demo Customer"}}],"meta":{"current_page":1,"per_page":25,"total":48,"last_page":2}}
GET /api/v1/invoices/{id} ámbito: invoices.get

Recupera una única factura con el cliente y sus líneas de detalle.

Respuesta HTTP 200

{"success":true,"data":{"id":101,"number":"INV-00101","date":"2026-06-01","due_date":"2026-07-01","status":"unpaid","subtotal":4347.83,"tax_total":652.17,"total":5000.00,"customer":{"id":1,"name":"Demo Customer"},"lines":[{"id":1,"description":"Consulting services","qty":10,"unit_price":434.78,"total":4347.83}]}}
POST /api/v1/invoices ámbito: invoices.post

Cree una nueva factura. Se crea con estado=borrador y un número generado automáticamente.

Cuerpo de la solicitud (JSON)

CampoTipoDescripción
customer_id integer obligatorio ID de un cliente existente
date date obligatorio Fecha de la factura (AAAA-MM-DD)
due_date date opcional Fecha de vencimiento del pago (AAAA-MM-DD)
notes string opcional Notas internas o visibles para el cliente
subtotal decimal opcional Total sin impuestos (predeterminado: 0)
tax_total decimal opcional Importe del impuesto (predeterminado: 0)
discount_total decimal opcional Importe de descuento (predeterminado: 0)
total decimal opcional Total general (predeterminado: 0)

Respuesta HTTP 201

{"success":true,"data":{"id":102,"number":"INV-00102","status":"draft","date":"2026-06-07","due_date":"2026-07-07","total":5000.00,"customer_id":1}}
PUT /api/v1/invoices/{id} ámbito: invoices.update

Actualiza una factura en borrador existente. Todos los campos son opcionales.

Cuerpo de la solicitud (JSON)

CampoTipoDescripción
customer_id integer opcional Nuevo ID de cliente
date date opcional Fecha de la factura (AAAA-MM-DD)
due_date date opcional Fecha de vencimiento del pago
notes string opcional Notas
subtotal decimal opcional Total sin impuestos
tax_total decimal opcional Importe del impuesto
total decimal opcional Total general

Respuesta HTTP 200

{"success":true,"data":{"id":102,"status":"draft","total":6000.00,"customer":{"id":1,"name":"Demo Customer"},"lines":[]}}
POST /api/v1/invoices/{id}/post ámbito: invoices.post

Contabilizar una factura de venta en borrador en el libro mayor. Requiere un total > 0 y una fecha. Cambia el estado a impagada.

Respuesta HTTP 200

{"success":true,"data":{"id":102,"status":"unpaid","posted_at":"2026-06-07T12:00:00Z","total":5000.00}}

Posibles errores: invoice_already_posted, invoice_total_required, invoice_date_required

POST /api/v1/invoices/{id}/void ámbito: invoices.void

Anular una factura contabilizada. Revierte todos los asientos del libro mayor y marca la factura como anulada.

Respuesta HTTP 200

{"success":true,"data":{"id":102,"status":"void"}}
POST /api/v1/invoices/{id}/mark-sent ámbito: invoices.send

Marcar una factura en borrador como enviada al cliente (cambia el estado de borrador a impagada). Idempotente.

Respuesta HTTP 200

{"success":true,"data":{"id":102,"status":"unpaid"}}
DELETE /api/v1/invoices/{id} ámbito: invoices.delete

Eliminar de forma permanente un borrador de factura y todas sus líneas. No se pueden eliminar facturas contabilizadas ni facturas con asignaciones de pago.

Respuesta HTTP 200

{"success":true,"data":{"message":"Invoice deleted."}}

Posibles errores: posted_invoice_not_deletable, invoice_has_allocations

Facturas de proveedor

GET /api/v1/bills ámbito: bills.get

Lista todas las facturas de proveedor. Admite filtro por estado y paginación.

Parámetros de consulta

ParámetroTipoDescripción
status string opcional Filtro: draft | unpaid | paid | void
page integer opcional Número de página
per_page integer opcional Resultados por página (máximo 100)

Respuesta HTTP 200

{"success":true,"data":[{"id":55,"number":"BILL-00055","date":"2026-06-01","status":"draft","total":2000.00,"supplier":{"id":3,"name":"Demo Supplier"}}],"meta":{"current_page":1,"per_page":25,"total":12,"last_page":1}}
GET /api/v1/bills/{id} ámbito: bills.get

Recupera una única factura de proveedor con sus líneas de detalle.

Respuesta HTTP 200

{"success":true,"data":{"id":55,"number":"BILL-00055","date":"2026-06-01","due_date":"2026-07-01","status":"draft","reference":"PO-001","total":2000.00,"supplier":{"id":3,"name":"Demo Supplier"},"lines":[]}}
POST /api/v1/bills ámbito: bills.post

Cree una nueva factura de proveedor. Se crea con estado=borrador y un número BILL-XXXXX generado automáticamente.

Cuerpo de la solicitud (JSON)

CampoTipoDescripción
supplier_id integer obligatorio ID de un proveedor existente
date date obligatorio Fecha de la factura (AAAA-MM-DD)
due_date date opcional Fecha de vencimiento del pago
reference string opcional Referencia del proveedor / número de orden de compra (máx. 120)
notes string opcional Notas internas
subtotal decimal opcional Total sin impuestos (predeterminado: 0)
tax_total decimal opcional Importe del impuesto (predeterminado: 0)
discount_total decimal opcional Descuento (predeterminado: 0)
total decimal opcional Total general (predeterminado: 0)

Respuesta HTTP 201

{"success":true,"data":{"id":56,"number":"BILL-00056","status":"draft","date":"2026-06-07","total":2000.00,"supplier_id":3}}
PUT /api/v1/bills/{id} ámbito: bills.update

Actualiza una factura de proveedor en borrador existente. Todos los campos son opcionales.

Cuerpo de la solicitud (JSON)

CampoTipoDescripción
supplier_id integer opcional Nuevo ID de proveedor
date date opcional Fecha de la factura
due_date date opcional Fecha de vencimiento del pago
reference string opcional Referencia del proveedor
total decimal opcional Total general

Respuesta HTTP 200

{"success":true,"data":{"id":56,"status":"draft","total":2500.00,"supplier":{"id":3,"name":"Demo Supplier"}}}
POST /api/v1/bills/{id}/post ámbito: bills.post

Contabilizar una factura de proveedor en borrador en el libro mayor, registrando la cuenta por pagar.

Respuesta HTTP 200

{"success":true,"data":{"id":56,"status":"unpaid","posted_at":"2026-06-07T12:00:00Z"}}

Posibles errores: bill_post_failed

DELETE /api/v1/bills/{id} ámbito: bills.delete

Eliminar de forma permanente un borrador de factura. La factura debe estar en estado borrador y no tener asignaciones de pago.

Respuesta HTTP 200

{"success":true,"data":{"message":"Bill deleted."}}

Posibles errores: posted_bill_not_deletable, bill_has_allocations

Pagos

GET /api/v1/payments ámbito: payments.get

Lista todos los pagos (cobros y desembolsos).

Parámetros de consulta

ParámetroTipoDescripción
type string opcional Filtro: receipt | disbursement
status string opcional Filtro: draft | posted
page integer opcional Número de página
per_page integer opcional Resultados por página (máximo 100)

Respuesta HTTP 200

{"success":true,"data":[{"id":20,"type":"receipt","payment_date":"2026-06-07","amount_total":5000.00,"status":"draft","customer_id":1}],"meta":{"current_page":1,"per_page":25,"total":8,"last_page":1}}
POST /api/v1/payments ámbito: payments.post

Registre un recibo de pago (el cliente pagó) o un desembolso (usted pagó al proveedor). Opcionalmente, asígnelo a una factura o recibo.

Cuerpo de la solicitud (JSON)

CampoTipoDescripción
type string obligatorio receipt (pago de cliente) o disbursement (pago a proveedor)
payment_date date obligatorio Fecha de pago (AAAA-MM-DD)
amount_total decimal obligatorio Importe total pagado (debe ser > 0)
method string opcional Método de pago, p. ej., bank_transfer, cash, card
reference string opcional Referencia bancaria o número de cheque (máximo 120)
description string opcional Descripción o memorando
customer_id integer cond. Obligatorio para los pagos de cobro (se deduce de la factura si document_type=ar_invoice)
supplier_id integer cond. Obligatorio para los pagos de desembolso (se deduce de la factura si document_type=ap_bill)
document_type string opcional «ar_invoice» o «ap_bill» — activa la asignación automática
document_id integer opcional ID de la factura o recibo al que asignar (obligatorio cuando se indica document_type)
allocated_amount decimal opcional Importe a asignar (por defecto, amount_total)

Respuesta HTTP 201

{"success":true,"data":{"id":21,"type":"receipt","payment_date":"2026-06-07","amount_total":5000.00,"status":"draft","allocations":[{"document_type":"ar_invoice","document_id":101,"allocated_amount":5000.00}]}}

Posibles errores: document_required, document_type_mismatch, invoice_not_found, bill_not_found, client_required, supplier_required

Asientos de diario

GET /api/v1/journal-entries ámbito: journal_entries.get

Lista los asientos contables con sus líneas y cuentas. Admite filtro por rango de fechas.

Parámetros de consulta

ParámetroTipoDescripción
status string opcional Filtro: draft | posted
from date opcional Fecha de inicio (AAAA-MM-DD)
to date opcional Fecha de fin (AAAA-MM-DD)
page integer opcional Número de página
per_page integer opcional Resultados por página (máximo 100)

Respuesta HTTP 200

{"success":true,"data":[{"id":5,"entry_date":"2026-06-07","reference":"JE-001","status":"posted","lines_count":2}],"meta":{"current_page":1,"per_page":25,"total":5,"last_page":1}}
POST /api/v1/journal-entries ámbito: journal_entries.post

Cree y contabilice de inmediato un asiento contable equilibrado. El total del debe debe ser igual al total del haber (tolerancia ±0,01).

Cuerpo de la solicitud (JSON)

CampoTipoDescripción
date date obligatorio Fecha del asiento (AAAA-MM-DD)
reference string opcional Código de referencia, p. ej., JE-001 (máx. 120)
description string opcional Nota / descripción (máx. 2000)
lines array obligatorio Mínimo 2 líneas. Cada línea: account_id (obligatorio), debit (decimal), credit (decimal), description (cadena)

Respuesta HTTP 201

{"success":true,"data":{"id":6,"entry_date":"2026-06-07","reference":"JE-001","status":"posted","posted_at":"2026-06-07T12:00:00Z","lines":[{"account_id":101,"account":{"code":"1100","name":"Cash"},"debit":1000,"credit":0},{"account_id":202,"account":{"code":"3000","name":"Equity"},"debit":0,"credit":1000}]}}

Posibles errores: journal_not_balanced

DELETE /api/v1/journal-entries/{id} ámbito: journal_entries.delete

Elimine un asiento contable no contabilizado. Los asientos contabilizados no se pueden eliminar a través de la API.

Respuesta HTTP 200

{"success":true,"data":{"message":"Journal entry deleted."}}

Posibles errores: posted_journal_not_deletable

Informes

Todos los endpoints de informes aceptan ?from=YYYY-MM-DD&to=YYYY-MM-DD. Los informes de balance general, balance de comprobación y antigüedad también aceptan ?as_of=YYYY-MM-DD (equivalente a to).

GET /api/v1/reports/income-statement ámbito: reports.income_statement

Informe de pérdidas y ganancias. Muestra los ingresos, gastos y el resultado neto del periodo indicado.

Parámetros de consulta

ParámetroTipoDescripción
from date opcional Inicio del período (AAAA-MM-DD)
to date opcional Fin del período (AAAA-MM-DD)

Respuesta HTTP 200

{"success":true,"data":{"revenue":150000,"expenses":85000,"net_income":65000}}
GET /api/v1/reports/balance-sheet ámbito: reports.balance_sheet

Instantánea del balance. Muestra activos, pasivos y patrimonio a la fecha indicada.

Parámetros de consulta

ParámetroTipoDescripción
to date opcional Fecha de corte (AAAA-MM-DD). También se acepta como ?as_of=

Respuesta HTTP 200

{"success":true,"data":{"assets":{"total":250000},"liabilities":{"total":80000},"equity":{"total":170000}}}
GET /api/v1/reports/cash-flow ámbito: reports.cash_flow

Estado de flujo de efectivo del periodo especificado (método directo).

Parámetros de consulta

ParámetroTipoDescripción
from date opcional Inicio del período
to date opcional Fin del período

Respuesta HTTP 200

{"success":true,"data":{"operating":45000,"investing":-12000,"financing":-8000,"net_change":25000}}
GET /api/v1/reports/trial-balance ámbito: reports.trial_balance

Balance de comprobación que muestra todas las cuentas con los totales de débito y crédito a una fecha determinada.

Parámetros de consulta

ParámetroTipoDescripción
to date opcional Fecha de corte (AAAA-MM-DD)

Respuesta HTTP 200

{"success":true,"data":[{"account_code":"1100","account_name":"Cash","debit":50000,"credit":0},{"account_code":"2000","account_name":"Accounts Payable","debit":0,"credit":15000}]}
GET /api/v1/reports/ar-aging ámbito: reports.ar_aging

Antigüedad de cuentas por cobrar. Facturas de cliente pendientes agrupadas según su retraso.

Parámetros de consulta

ParámetroTipoDescripción
to date opcional Fecha de corte del envejecimiento (AAAA-MM-DD)

Respuesta HTTP 200

{"success":true,"data":{"current":12000,"1_30":3500,"31_60":800,"61_90":0,"over_90":500,"total":16800}}
GET /api/v1/reports/ap-aging ámbito: reports.ap_aging

Antigüedad de cuentas por pagar. Facturas de proveedor pendientes agrupadas según su retraso.

Parámetros de consulta

ParámetroTipoDescripción
to date opcional Fecha de corte del envejecimiento (AAAA-MM-DD)

Respuesta HTTP 200

{"success":true,"data":{"current":8000,"1_30":1200,"31_60":0,"61_90":0,"over_90":0,"total":9200}}
GET /api/v1/reports/tax ámbito: reports.tax

Resumen de IVA / impuestos. Muestra el impuesto cobrado en ventas y el impuesto pagado en compras del periodo.

Parámetros de consulta

ParámetroTipoDescripción
from date opcional Inicio del período
to date opcional Fin del período

Respuesta HTTP 200

{"success":true,"data":{"tax_collected":15000,"tax_paid":4200,"net_vat_payable":10800}}

Referencia de error

Código de error HTTP Significado
invoice_already_posted 422 La factura ya está contabilizada en el libro mayor
invoice_total_required 422 No se puede contabilizar una factura con total cero o negativo
invoice_date_required 422 La fecha del documento es obligatoria antes de contabilizar
posted_invoice_not_deletable 422 Anule o desregistre la factura antes de eliminarla
invoice_has_allocations 422 Elimine las asignaciones de pago antes de borrar
posted_bill_not_deletable 422 No se puede eliminar una factura contabilizada o que no esté en borrador
bill_has_allocations 422 Elimine las asignaciones de pago antes de borrar
bill_post_failed 422 La factura no superó la validación interna de contabilización
journal_not_balanced 422 El total de débitos no coincide con el total de créditos
posted_journal_not_deletable 422 Solo se pueden eliminar las entradas en borrador (no contabilizadas)
document_required 422 document_id es obligatorio cuando se establece document_type
document_type_mismatch 422 ar_invoice requiere receipt; ap_bill requiere disbursement
invoice_not_found 404 La factura con ese ID no existe
bill_not_found 404 No existe ninguna factura con ese ID
client_required 422 customer_id es obligatorio para los pagos receipt
supplier_required 422 supplier_id es obligatorio para los pagos disbursement

Paginación

Todos los endpoints de lista devuelven resultados paginados. Controle la paginación con parámetros de consulta:

ParámetroPredeterminadoMáx.Descripción
page1—Número de página a recuperar
per_page25100Número de resultados por página

El objeto meta de cada respuesta de lista contiene current_page, per_page, total y last_page.