API de finanzas de SolaCount
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)
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
/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
/api/v1/customers
ámbito: customers.get
Lista todos los clientes. Admite búsqueda y paginación.
Parámetros de consulta
| Parámetro | Tipo | Descripció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}}
/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}}
/api/v1/customers
ámbito: customers.post
Crear un nuevo cliente.
Cuerpo de la solicitud (JSON)
| Campo | Tipo | Descripció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
/api/v1/suppliers
ámbito: suppliers.get
Lista todos los proveedores. Admite búsqueda y paginación.
Parámetros de consulta
| Parámetro | Tipo | Descripció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}}
/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}}
/api/v1/suppliers
ámbito: suppliers.post
Crear un nuevo proveedor.
Cuerpo de la solicitud (JSON)
| Campo | Tipo | Descripció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
/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ámetro | Tipo | Descripció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}}
/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}]}}
/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)
| Campo | Tipo | Descripció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}}
/api/v1/invoices/{id}
ámbito: invoices.update
Actualiza una factura en borrador existente. Todos los campos son opcionales.
Cuerpo de la solicitud (JSON)
| Campo | Tipo | Descripció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":[]}}
/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
/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"}}
/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"}}
/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
/api/v1/bills
ámbito: bills.get
Lista todas las facturas de proveedor. Admite filtro por estado y paginación.
Parámetros de consulta
| Parámetro | Tipo | Descripció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}}
/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":[]}}
/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)
| Campo | Tipo | Descripció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}}
/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)
| Campo | Tipo | Descripció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"}}}
/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
/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
/api/v1/payments
ámbito: payments.get
Lista todos los pagos (cobros y desembolsos).
Parámetros de consulta
| Parámetro | Tipo | Descripció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}}
/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)
| Campo | Tipo | Descripció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
/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ámetro | Tipo | Descripció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}}
/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)
| Campo | Tipo | Descripció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
/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).
/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ámetro | Tipo | Descripció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}}
/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ámetro | Tipo | Descripció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}}}
/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ámetro | Tipo | Descripció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}}
/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ámetro | Tipo | Descripció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}]}
/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ámetro | Tipo | Descripció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}}
/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ámetro | Tipo | Descripció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}}
/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ámetro | Tipo | Descripció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ámetro | Predeterminado | Máx. | Descripción |
|---|---|---|---|
page | 1 | — | Número de página a recuperar |
per_page | 25 | 100 | Número de resultados por página |
El objeto meta de cada respuesta de lista contiene current_page, per_page, total y last_page.