API de Saldia

Crea facturas y presupuestos desde tu tienda, tu TPV o tu propio programa, da de alta gastos con su PDF y entérate de lo que contesta la AEAT sin tener que preguntar. Las facturas que salen por la API son las mismas que las que haces en Saldia: numeradas sin huecos, con su huella Veri*factu y remitidas a Hacienda.

Una clave por empresa

Solo ve los datos de su empresa y se revoca al momento.

Veri*factu de serie

Lo emitido no se toca: se corrige con una rectificativa.

Webhooks firmados

Te avisa cuando se emite una factura o la AEAT la rechaza.

Empezar

La API está incluida en los planes Pro y Business. Se comprueba en cada llamada: si la empresa pasa a Starter o se le vence la suscripción, la clave deja de funcionar y la respuesta (un 403) dice por qué.

  1. 1. Crea la clave. En Saldia, Empresa, API, «Generar clave». Solo puede hacerlo quien administra la empresa. La clave empieza por slk_live_ y se enseña una sola vez: cópiala y guárdala como una contraseña.
  2. 2. Mándala en la cabecera Authorization: Bearer de cada llamada. Cada clave es de una empresa y solo ve los datos de esa empresa.
  3. 3. Prueba con GET /ping, que dice a qué empresa pertenece la clave.

Petición

curl https://www.saldia.app/api/v1/ping \
  -H "Authorization: Bearer slk_live_TU_CLAVE"

Respuesta

{
  "ok": true,
  "organizationId": "1218ec6f-e6e1-4add-85d7-9375e3fcb6af",
  "company": { "legalName": "Casa Vereda Restauración SL", "taxId": "B18734020" }
}
Usa siempre www.saldia.app. La dirección sin www redirige, y en esa redirección muchos clientes HTTP (curl entre ellos) quitan la cabecera Authorization: la llamada llega sin clave y contesta 401.

Saldia apunta cada llamada: con qué clave, a qué ruta, con qué resultado y desde dónde. En Empresa, API se ve cuántas llamadas ha hecho cada clave en los últimos 30 días y desde cuántos sitios. Si una clave que solo usa tu servidor aparece llamando desde dos, revócala y crea otra.

Formato y errores

Todo va en JSON. Los nombres de campo están en camelCase y son los mismos en el listado y en el detalle. Las fechas, YYYY-MM-DD; los importes, en euros y como número.

400Un dato mal formado o que falta. El mensaje dice cuál. No se ha guardado nada.
401Falta la clave, o no existe o está revocada.
403La empresa no tiene un plan con API o su suscripción no está activa.
404No existe, o es de otra empresa (para la API es lo mismo).
409El estado del documento no lo permite: una factura emitida no se edita, un presupuesto ya facturado no se anula…
429Demasiadas llamadas (ver límites). Espera los segundos que dice la cabecera Retry-After.
502Solo al enviar por correo: el envío ha fallado. Se puede reintentar.

Los errores son siempre { "error": "…" }, con el motivo en español, y a veces algún campo más que lo explica (motivo, camposDesconocidos…).

Campos que no existen

En un PATCH y en las acciones (convertir, emitir, enviar, rectificar…), un campo que no está en la lista es un 400 y no se guarda nada. Así sabes que lo que mandas se aplica de verdad:

{
  "error": "No se admite el campo \"cancelled\". No se ha guardado nada.",
  "camposDesconocidos": ["cancelled"],
  "camposAdmitidos": ["customerId", "issueDate", "dueDate", "notes", "…"]
}

En las altas de ventas y contactos (POST /sales, POST /contacts) no se rechazan, para no romper a quien ya integra, pero la respuesta trae camposIgnorados. La excepción es el cliente de una venta: si llega en un formato que no es el nuestro (customer: {…}, client, nif…) es un 400, porque ignorarlo emitiría la factura sin destinatario.

Límites

Cada clave tiene un tope de llamadas por hora, contado sobre la última hora (no se reinicia a la hora en punto):

GET1.000 a la hora
POST, PATCH, DELETE500 a la hora: altas, cambios, emisiones y rectificativas
POST /sales/{id}/send100 correos a la hora, que cuentan también como escritura

Al pasarse, la respuesta es un 429 con reintentarEnSegundos y la cabecera Retry-After: espera eso y sigue. Si tu integración necesita más, escríbenos y lo vemos. Para leer muchas ventas, mejor una llamada a GET /sales con fechas que una por documento.

Desde una misma dirección IP, 30 intentos con claves que no existen en 10 minutos bloquean esa dirección hasta que pasan.

Páginas

Contactos y productos van por páginas: limit (hasta 1.000, que es también el valor por defecto) y offset. La respuesta trae total, offset, hasMore y nextOffset. Las ventas y los gastos devuelven todo lo que cumple los filtros, sin corte: acótalos por fechas con from y to.

Ventas

Facturas (invoice), rectificativas (credit_note), presupuestos (quote) y tickets (ticket). Una factura emitida no se cambia ni se borra: es lo que pide Veri*factu. Se corrige con una rectificativa.

GET/sales

Lista documentos de venta, ordenados por fecha de emisión.

typeinvoice, credit_note, quote o ticket. Sin él, todos.
statusSin él, las emitidas, cobradas o no (issued y paid). issued solo las pendientes de cobro, paid las cobradas, draft, void, o all para todo.
from, toFecha de emisión, YYYY-MM-DD.
customerIdSolo las de ese cliente.
referenceLa externalRef exacta con la que lo creaste.
invoicedfalse: presupuestos que faltan por facturar. true: los facturados, en Saldia o fuera.
lines=1Trae también las líneas de cada documento.

GET /sales?type=invoice&from=2026-10-13&to=2026-10-13

{
  "count": 1,
  "totalSubtotal": 160,
  "totalWithTax": 176,
  "documents": [
    {
      "id": "352a623c-3427-4b87-a611-abca28e2eb1e",
      "type": "invoice",
      "status": "paid",
      "fullNumber": "F2026-0011",
      "issueDate": "2026-10-13",
      "dueDate": null,
      "customerId": "77f5784b-9fc5-411f-94a6-99cc61265f59",
      "customerName": "Inés Castillo Romero",
      "customerTaxId": "74638291W",
      "subtotal": 160,
      "taxTotal": 16,
      "irpfTotal": 0,
      "total": 176,
      "notes": null,
      "externalRef": null,
      "paymentMethod": "tarjeta",
      "paidAt": "2026-10-13",
      "convertedInvoiceId": null,
      "invoicingStatus": null,
      "invoicedOutside": null,
      "emailSentAt": null,
      "rectifiesDocumentId": null,
      "replacesDocumentId": null,
      "isAdvance": false,
      "deliveryAddress": null,
      "invoiceType": "F1",
      "verifactuStatus": "none"
    }
  ]
}

totalSubtotal y totalWithTax suman con signo: las rectificativas restan. Un presupuesto facturado lleva además invoiceNumber, el número de la factura que lo recoge.

statusdraft (borrador), issued (emitido), paid (factura cobrada), void (presupuesto anulado).
invoiceTypeF1 completa, F2 simplificada, R1 y R5 rectificativas (R5 la de una simplificada). Vacío en presupuestos y tickets.
verifactuStatusnone, pending, sent, accepted, rejected o annulled. Lo que ha dicho la AEAT del registro.
paymentMethodtransferencia, efectivo, tarjeta, bizum, cheque, domiciliacion, pagare o saldo.
emailSentAtCuándo se mandó por correo al cliente.
replacesDocumentIdEn una completa que sustituye a una simplificada, cuál era.
isAdvanceEs una factura de anticipo.
deliveryAddressDónde se entrega: { address, postalCode, city, province } o null.

Si un presupuesto está facturado

invoicedEstá en una factura de Saldia (convertedInvoiceId).
invoicedOutsideSe facturó en otro programa y se marcó así (invoicedOutside lleva la referencia).
noAmountTotal 0, como una muestra gratuita: no hay nada que facturar.
notInvoicedFalta por facturar. Es lo que devuelve invoiced=false.

Solo en presupuestos emitidos; en lo demás viene null.

GET/sales/{id}

{ document, lines, customer }: el documento con los mismos campos que el listado, sus líneas y la ficha del cliente. Cada línea:

{
  "productId": "8c75e90e-e33c-48a6-9e37-afa27b999043",
  "description": "Tarta de celebración",
  "quantity": 2,
  "unitPrice": 35,
  "discountPct": 0,
  "taxRate": 10,
  "irpfRate": 0,
  "priceIncludesTax": false,
  "lineSubtotal": 70,
  "lineTax": 7,
  "lineTotal": 77
}

El detalle trae además los nombres antiguos en snake_case (full_number, tax_id…) para no romper a quien ya los lee. Para código nuevo, usa los de camelCase.

POST/sales

Crea un documento. Una factura se emite y se manda a la AEAT al crearla, salvo que pidas un borrador.

Cuerpo

{
  "type": "invoice",
  "issueDate": "2026-10-13",
  "customerName": "Inés Castillo Romero",
  "customerTaxId": "74638291W",
  "paymentMethod": "tarjeta",
  "lines": [
    { "productId": "8c75e90e-e33c-48a6-9e37-afa27b999043", "quantity": 2 },
    { "productId": "93dfe228-111c-487e-8ac8-01bfefd1837a", "quantity": 6 }
  ]
}

Respuesta

{
  "status": "created",
  "id": "352a623c-3427-4b87-a611-abca28e2eb1e",
  "type": "invoice",
  "aviso": null,
  "fullNumber": "F2026-0011",
  "subtotal": 160,
  "taxTotal": 16,
  "irpfTotal": 0,
  "total": 176
}
typeinvoice, credit_note, quote o ticket. Sin él sale un ticket, que no es fiscal: la respuesta lo avisa en aviso.
issueDateObligatorio.
dueDateVencimiento.
customerIdUn contacto que ya existe.
customerName, customerTaxIdSi no hay customerId: busca el cliente por nombre y, si no está, lo crea.
linesLas líneas (ver abajo). Al menos una con precio o producto.
notesObservaciones. Se imprimen en el documento.
referenceTu id del pedido. No se imprime. Si ya hay un documento del mismo tipo con esa referencia, no crea otro: contesta { "status": "duplicate", "id", "fullNumber" }.
dedupefalse para crear aunque la referencia se repita.
drafttrue lo deja en borrador, sin número ni AEAT (status: "draft").
seriesIdLa serie en la que se numera (GET /series). Sin ella, la de por defecto.
paymentMethodForma de pago que se imprime.
paymentIban, bankAccountIdEl IBAN que se imprime para la transferencia, escrito o de una cuenta guardada.
deliveryAddress{ address, postalCode, city, province }. Sin ella, la de entrega del cliente, que queda congelada en el documento.
paymentsLos cobros, uno por forma de pago (ver abajo).
advance, deductAdvancesFacturas de anticipo y su descuento en la final (ver abajo).

Líneas

productIdUn producto del catálogo. Pone su nombre, su precio (o el de la tarifa del cliente) y su IVA.
descriptionEl concepto. Sin él, el nombre del producto.
quantityPor defecto, 1.
unitPricePrecio por unidad. Si lo mandas, manda sobre el del producto.
taxRateIVA en %: 21, 10, 4 o 0. Sin él, el del producto.
discountPctDescuento en %.
irpfRateRetención en %.
priceIncludesTaxtrue si el precio es con IVA. Sin él, lo que diga el producto.

Una línea a 0 € vale si lleva description y unitPrice: 0. Las líneas vacías se descartan.

Completa o simplificada

Con cliente y NIF sale una completa (F1). Sin cliente sale una simplificada (F2), con el tope legal de 3.000 €; con un cliente sin NIF, hasta 400 €. Por encima no se emite y la respuesta dice qué falta.

Cobros

En una factura que se emite, payments apunta lo cobrado. Un pago mixto son varios. method es una de las formas de pago de arriba, label (hasta 60 caracteres) el nombre que se imprime en vez del de la forma, y date la fecha del cobro (por defecto, la de la factura). No pueden pasar del total; si lo suman, la factura queda cobrada.

"payments": [
  { "method": "saldo", "amount": 12.00, "label": "Saldo de la casa" },
  { "method": "tarjeta", "amount": 8.50 }
]

La respuesta trae entonces "payments": { cobrado, falta, cobrada }: lo cobrado, lo que falta y si la factura ha quedado cobrada.

Anticipos

advance: true crea una factura de anticipo: una factura normal, con su IVA, que se imprime como «Factura de anticipo». En la final, deductAdvances: ["id del anticipo", …] añade por cada anticipo y tipo de IVA una línea en negativo, para que la base y la cuota no se cobren dos veces. Un anticipo se descuenta una sola vez (409 si ya lo está).

PATCH/sales/{id}

Cambia un documento. Lo que no mandas no cambia. La respuesta trae el documento tal como ha quedado y la lista de cambios aplicados, así que no hace falta volver a leerlo.

customerId, issueDate, dueDate, notes, lines, deliveryAddress, paymentIban, bankAccountIdBorradores, presupuestos, tickets y facturas importadas.
paid, paidAtFacturas emitidas: paid: true con paidAt (YYYY-MM-DD) la marca cobrada; false, pendiente.
paymentMethodTodos. En una factura emitida, sola o junto al cobro.
statusPresupuestos: "void" lo anula, "active" lo reactiva.
invoicedOutsidePresupuestos emitidos: el texto de dónde se facturó ("Holded F260279"); null quita la marca.

Respuesta a { "paid": true, "paidAt": "2026-10-13" }

{
  "status": "updated",
  "id": "352a623c-3427-4b87-a611-abca28e2eb1e",
  "cambios": ["paid", "paidAt"],
  "document": { "…": "la venta como ha quedado, con los campos de GET /sales" },
  "fullNumber": "F2026-0011",
  "total": 176,
  "docStatus": "paid"
}

lines sustituye todas las líneas: para cambiar una, manda la lista entera con el cambio. Cambiar el contenido de una factura emitida es un 409: se corrige con POST /sales/{id}/rectify.

GET/sales/{id}/pdf

El PDF del documento, el mismo que se descarga en Saldia.

Convertir, emitir, enviar y rectificar

POST/sales/{id}/convert

Convierte un presupuesto en factura y deja el vínculo (convertedInvoiceId). alsoQuoteIds junta en la misma factura otros presupuestos del mismo cliente, como una remesa de fin de mes. Por defecto la factura queda en borrador; con issue: true se emite y se manda a la AEAT.

Contesta { status, invoice, aeat }: status es issued o draft, invoice la factura con los campos de GET /sales, y aeat, si se ha emitido, { status, error } con lo que ha contestado la AEAT (accepted, rejected, o pending si sigue en cola).

Para que un presupuesto cuente como facturado, conviértelo así. Copiar sus líneas en una factura nueva no deja el vínculo.

POST/sales/{id}/issue

Emite un borrador y lo manda a la AEAT. Sin cuerpo. Contesta { status: "issued", document, aeat }, o 409 con el motivo si no es un borrador o no se puede emitir.

POST/sales/{id}/send

Manda el documento emitido por correo, con su PDF, al email del cliente.

toOtro destinatario en vez del email del cliente.
ccCopia: un correo o una lista de hasta 5.
mensajeUna nota en texto (hasta 2.000 caracteres) antes del texto de siempre. Una línea en blanco separa párrafos.
replyToA dónde llegan las respuestas del cliente. Conviene ponerlo: el remitente de Saldia no recibe correo.
forcetrue para mandarlo otra vez aunque ya se enviara.

Contesta { "status": "sent", "id", "to", "cc", "emailSentAt" }.

Se puede reintentar sin miedo: si ya se envió, no se manda de nuevo y contesta { "status": "already_sent", "id", "emailSentAt" }. Un 409 trae motivo: no_emitido, rechazada_aeat (hay que corregir sus datos antes) o sin_email.

POST/sales/{id}/rectify

Rectificativa de una factura emitida. Sin lines, copia la factura entera, para anularla y volver a emitir la buena. Con lines, solo lo que se corrige, en positivo (por ejemplo, la diferencia de precio): las rectificativas se guardan en positivo y restan al sumar. reason es el motivo, seriesId la serie de rectificativas, e issue: true la emite; si no, queda en borrador. La de una simplificada sale como R5.

Contesta { status, creditNote, aeat }, como al convertir.

POST/sales/{id}/replace

Cuando un cliente pide factura completa de una simplificada ya emitida. Manda customerId, o customerName y customerTaxId (la completa necesita NIF), y reason si quieres. Saldia hace la completa con las mismas líneas y una rectificativa R5 que deja la simplificada a cero, así que la venta cuenta una sola vez. Contesta { status: "replaced", invoice, creditNote }; si ya estaba sustituida, already_replaced con los mismos documentos.

Series

GET/series

Las series de facturas y rectificativas de la empresa. Se crean en Saldia (Ventas, Series); por la API se leen y se eligen con seriesId.

Respuesta

{
  "series": [
    {
      "id": "c6ecd03c-8d42-4579-97b1-332b0b27c5fb",
      "type": "invoice",
      "prefix": "F2026-",
      "name": null,
      "active": true,
      "isDefault": true,
      "nextNumber": 23
    }
  ]
}

Contactos

GET/contacts

Filtros: type (customer o supplier), q (busca en el nombre y el NIF), limit y offset.

GET /contacts?type=customer&limit=1

{
  "count": 1,
  "total": 6,
  "offset": 0,
  "hasMore": true,
  "nextOffset": 1,
  "contacts": [
    {
      "id": "d659fd07-b45b-4c72-8af4-a116146d4098",
      "name": "Albaicín Software SL",
      "taxId": "B18577148",
      "email": "admin@albaicinsoftware.example.com",
      "phone": null,
      "address": "Avenida de la Constitución, 9",
      "postalCode": "18012",
      "city": "Granada",
      "province": "Granada",
      "country": "ES",
      "isCustomer": true,
      "isSupplier": false,
      "isIntracommunity": false,
      "deliveryAddress": null,
      "deliveryPostalCode": null,
      "deliveryCity": null,
      "deliveryProvince": null
    }
  ]
}

GET/contacts/{id}

La ficha completa, con los mismos campos y, además, los de la base en snake_case (IBAN, cuentas contables, notas).

POST/contacts

Crea un contacto. Solo name es obligatorio. Contesta { "status": "created", "id" }.

name, taxId, email, phoneLos datos básicos. Un NIF español mal escrito se rechaza con el motivo.
address, postalCode, city, province, countryLa dirección fiscal. country se guarda con su código: «España» queda ES.
deliveryAddress, deliveryPostalCode, deliveryCity, deliveryProvinceDónde se le entrega, si no es la dirección fiscal.
isCustomer, isSupplierSi es cliente, proveedor o las dos cosas. Por defecto, cliente.
isIntracommunityEmpresa de otro país de la UE con NIF intracomunitario.
iban, salesAccount, purchaseAccount, notesIBAN, cuentas contables de venta y compra, y notas internas.

PATCH/contacts/{id}

Los mismos campos. Lo que no mandas no cambia. Cambiar el NIF de un cliente no cambia las facturas ya emitidas: llevan los datos del día en que se emitieron.

Productos

GET/products

Filtros: q (nombre, referencia o código de barras), limit y offset. Los productos se crean en Saldia; por la API se leen y se cambian.

GET /products?limit=1

{
  "count": 1,
  "total": 8,
  "offset": 0,
  "hasMore": true,
  "nextOffset": 1,
  "products": [
    {
      "id": "b1cd8e63-c7da-49f4-9676-58225cde2c00",
      "sku": null,
      "barcode": null,
      "name": "Catering por persona",
      "description": null,
      "unitPrice": 26,
      "taxRate": 10,
      "priceIncludesTax": false,
      "isService": true,
      "stockQty": 0,
      "active": true
    }
  ]
}

GET/products/{id}

{ "product": { … } }, con los mismos campos.

PATCH/products/{id}

name, sku, barcode, description, unitPrice, taxRate, priceIncludesTax, isService y active. barcode es el código de barras del fabricante (EAN o UPC): uno de 8, 12, 13 o 14 cifras tiene que tener bien el dígito de control. active: false lo archiva: sale del catálogo y del TPV, y sus facturas no cambian. El precio y el IVA nuevos valen para lo que se facture desde ese momento.

Gastos

GET/expenses

Filtros: from y to (fecha de la factura), supplierId, invoiceNumber y paid (true los pagados, false los pendientes de pago).

GET /expenses?invoiceNumber=PES-1210

{
  "count": 1,
  "totalSubtotal": 640.3,
  "totalTax": 64.03,
  "totalIrpf": 0,
  "totalWithTax": 704.33,
  "expenses": [
    {
      "id": "b6dade63-4d68-41e7-84a5-362b2600ac06",
      "issueDate": "2026-11-06",
      "dueDate": "2026-12-06",
      "paidAt": null,
      "supplierId": "4facd1ef-c623-4364-891b-3c444e62837e",
      "supplierName": "Pescados La Caleta de Motril SL",
      "supplierTaxId": "B18311787",
      "invoiceNumber": "PES-1210",
      "description": "Pescado y marisco, noviembre",
      "category": null,
      "expenseAccount": "601",
      "subtotal": 640.3,
      "taxRate": 10,
      "taxAmount": 64.03,
      "taxBreakdown": [],
      "irpfRate": 0,
      "irpfAmount": 0,
      "total": 704.33,
      "deductiblePct": 100,
      "operationType": "nacional",
      "reverseChargeRate": 0,
      "currency": "EUR",
      "exchangeRate": 1,
      "originalTotal": null,
      "notes": null,
      "hasDocument": false,
      "uploadedAt": "2026-11-11T12:17:10.743169+00:00"
    }
  ]
}

GET/expenses/{id}

{ "expense": { … } }, con los mismos campos y documentUrl: un enlace al PDF o la foto original que vale 5 minutos.

POST/expenses

Da de alta un gasto con su factura.

Cuerpo

{
  "supplier": { "name": "Pescados La Caleta de Motril SL", "taxId": "B18311787" },
  "invoiceNumber": "PES-1210",
  "issueDate": "2026-11-06",
  "dueDate": "2026-12-06",
  "subtotal": 640.30,
  "taxRate": 10,
  "expenseAccount": "601",
  "description": "Pescado y marisco, noviembre",
  "documentBase64": "JVBERi0xLjcK…",
  "documentMediaType": "application/pdf"
}

Respuesta

{
  "status": "created",
  "id": "b6dade63-4d68-41e7-84a5-362b2600ac06",
  "subtotal": 640.3,
  "taxAmount": 64.03,
  "irpfAmount": 0,
  "total": 704.33,
  "operationType": "nacional",
  "reverseChargeRate": 0,
  "ivaAutoliquidado": 0
}
issueDateObligatorio.
subtotal, taxRateLa base y el IVA. Con varios tipos, taxBreakdown: [{ base, taxRate }, …] en su lugar.
supplier{ name, taxId, email, phone, address, postalCode, city, province, iban }. Se busca por NIF (con o sin prefijo de país de la UE) y, si no está, se crea.
invoiceNumber, dueDate, irpfRateNúmero de la factura del proveedor, vencimiento y retención.
expenseAccount, categoryCuenta contable (601, 628…) y categoría.
descriptionEl concepto, corto: es lo que se ve en las listas.
notesNotas internas: lo que explique el gasto.
documentBase64, documentMediaTypeEl PDF o la foto (JPG, PNG, WEBP o HEIC, hasta 10 MB), en base64. Hacen falta los dos.
operationType, reverseChargeRatenacional, intracomunitario o extracomunitario, y el IVA que se autoliquida. Sin él se deduce del NIF.
currency, exchangeRate, originalTotalPara facturas en otra moneda.
dedupefalse para crearlo aunque se parezca a uno que ya está.

Antes de crear, mira si la factura ya está. La respuesta lo dice en status:

createdNo había ninguno parecido: se ha creado.
duplicateYa hay uno del mismo proveedor con ese número, o con número, a dos días como mucho y la misma base. No crea nada.
mergedHabía uno del mismo proveedor, a dos días y con la misma base, pero sin número. Le pone el número y el PDF que traes (completado dice qué).
possible_duplicateUn 409: misma fecha y base que uno ya registrado, pero distinto IVA. No crea nada: hay que mirar cuál está bien.

Si el documento no es un PDF o una imagen válida, el gasto se crea igual sin él y la respuesta trae documentoNoGuardado con el motivo. Los gastos no se borran por la API.

Justificantes de saldo

Para quien vende saldo prepagado: bonos, tarjetas regalo o monedas de la casa. Una recarga no es una factura ni lleva IVA hasta que se gasta; lo que se gasta se factura con POST /sales y un cobro con method: "saldo". Los justificantes no suman en ventas ni en impuestos, ni van a la AEAT. Tienen su propia numeración sin huecos: JR2026-0001 las recargas y JD2026-0001 las devoluciones.

POST/receipts

typetopup (recarga) o refund (devolución de saldo no gastado). Obligatorio.
dateYYYY-MM-DD. Obligatorio.
amountEuros, mayor que 0. Obligatorio.
accountLa cuenta del cliente: tu id o su nombre. Obligatorio.
units, unitLo abonado en la unidad de la casa, si la hay: cuántas y cómo se llaman.
paymentMethodCómo pagó o cómo se le devolvió: las mismas formas que en ventas.
referenceTu id de la operación. Con la misma referencia y tipo no se crea otro: contesta duplicate.
originIdEn una devolución, la recarga de la que sale.
notesObservaciones que se imprimen.

Contesta 201 con { "status": "created", "receipt" }. Cada justificante: id, type, number (JR2026-0001), date, issuedAt, amount, units, unit, account, paymentMethod, reference, originId y notes. Un campo que no existe o un dato mal es un 400 y no se guarda nada.

GET/receipts

Filtros: type, from, to, reference y account. Trae count, totalTopups, totalRefunds y receipts.

GET/receipts/{id} · /receipts/{id}/pdf

Un justificante ({ "receipt": { … } }) y su PDF para dar al cliente.

Webhooks

Para enterarte sin preguntar de lo que pasa con tus facturas, sobre todo de un rechazo de la AEAT.

POST/webhooks

Cuerpo

{ "url": "https://tu-servidor.es/saldia", "events": ["invoice.aeat_rejected", "invoice.issued"] }

Contesta 201 con { webhook: { id, url, events, createdAt }, secret }.

events: ["*"] para todos. El secret se enseña una sola vez: guárdalo. Hasta 5 por empresa; la URL tiene que ser https y pública.

GET/webhooks

Los activos (webhooks) y los eventos que hay (availableEvents).

GET/webhooks/{id}

Sus últimas 50 entregas en deliveries: id, event, status (delivered, pending o failed), attempts, lastError, createdAt, deliveredAt y nextAttempt.

DELETE/webhooks/{id}

Lo da de baja.

Eventos

invoice.issuedSe emite una factura o rectificativa, por la API o en Saldia. id, type, fullNumber, invoiceType, total, externalRef, verifactuStatus.
invoice.aeat_acceptedLa AEAT acepta el registro. id, type, fullNumber, externalRef, verifactuStatus, aeatCsv.
invoice.aeat_rejectedLa AEAT lo rechaza. Lo mismo y aeatErrorCode, aeatErrorMessage.
receipt.createdSe emite un justificante de saldo. El justificante, como en GET /receipts/{id}.

Lo que recibe tu servidor (data, de la factura F2026-0011)

POST https://tu-servidor.es/saldia
Content-Type: application/json
Saldia-Delivery: <id de la entrega>
Saldia-Signature: t=<segundos>,v1=<firma>

{
  "id": "<id del aviso>",
  "event": "invoice.issued",
  "createdAt": "<fecha y hora ISO>",
  "data": {
    "id": "352a623c-3427-4b87-a611-abca28e2eb1e",
    "type": "invoice",
    "fullNumber": "F2026-0011",
    "invoiceType": "F1",
    "total": 176,
    "externalRef": null,
    "verifactuStatus": "none"
  }
}

v1 es el HMAC-SHA256, con tu secret, de "<t>.<cuerpo tal cual llega>". Compruébalo y rechaza los avisos con un t de hace más de 5 minutos:

Node.js

import crypto from 'node:crypto'

function avisoValido(cuerpo, cabecera, secreto) {
  const { t, v1 } = Object.fromEntries(cabecera.split(',').map((p) => p.split('=')))
  if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false
  const esperado = crypto.createHmac('sha256', secreto).update(`${t}.${cuerpo}`).digest('hex')
  return crypto.timingSafeEqual(Buffer.from(esperado), Buffer.from(v1))
}

Contesta con un 2xx en menos de 5 segundos. Si no, se reintenta a los 1, 5, 15 y 60 minutos y a las 3, 6 y 12 horas (más o menos), y después queda como failed. Un mismo aviso puede llegar dos veces: usa su id para no procesarlo dos veces.

Cuenta de resultados y banco

GET/pnl

La cuenta de resultados entre from y to (sin ellos, de todo el histórico): cifraNegocios, aprovisionamientos, personal, otrosExplotacion, amortizacion y financiero, cada una con { label, total, rows: [{ account, name, amount }] }; los resultados (resultadoExplotacion, resultadoAntesImpuestos, resultadoEjercicio), ingresosTotal, gastosTotal, el desglose por mes en monthly ({ month, ingresos, gastos, resultado }) y las ventas por serie en ventasPorSerie.

GET/tesoreria

El saldo de las cuentas conectadas y los últimos movimientos (?movimientos=, 20 por defecto y 200 como mucho). Los IBAN y los números de tarjeta salen tapados.

GET /tesoreria?movimientos=2

{
  "saldoTotal": 73725.37,
  "porConciliar": 2,
  "cuentas": [
    {
      "nombre": "Cuenta principal",
      "banco": "Banco de ejemplo",
      "iban": "ES91····1332",
      "saldo": 73725.37,
      "saldoA": "2026-11-11",
      "conectada": false,
      "ultimaSincronizacion": "2026-11-11T12:17:30.465+00:00",
      "consentimientoHasta": null
    }
  ],
  "movimientos": [
    { "fecha": "2026-11-11", "concepto": "Pago Bodegas Contraviesa SL", "importe": -492.47, "conciliado": true },
    { "fecha": "2026-11-09", "concepto": "Abono TPV ventas sala 2026-11-08", "importe": 1809, "conciliado": true }
  ]
}

¿Te falta algo para tu integración?

Escríbenos a hola@dfmsaas.solutions y cuéntanos qué necesitas. Casi todo lo que hay en esta página salió de una integración que lo pidió.