Configuración de la empresa

Bajo /settings/... vive la configuración de la empresa que la API pública expone como solo lectura: la ficha de la empresa y su forma de trabajar, los impuestos disponibles, las series de numeración por tipo de documento y las plantillas de impresión. La modificación de esta configuración se hace desde la interfaz, no por API.

Las 5 operaciones#

Las cinco requieren scope settings:read.

Para los catálogos de impuestos consulta directamente la guía de Impuestos — cubre el modelo completo (dos catálogos, schema, autorepercutidos, lineAmountIsTax…). Esta página documenta las tres operaciones restantes (company, series y themes).

Operaciones#

• Ficha de la empresa
• Lista de series de numeración
• Lista de plantillas

Ficha de la empresa#

GET /{companyId}/settings/company devuelve los datos de la empresa y su configuración operativa. Es la llamada recomendada justo después de GET /profile: el perfil dice qué empresas hay y esta operación dice cómo trabaja cada una, lo que un integrador o un agente necesita saber antes de crear documentos o enviar ficheros a la bandeja.

Parámetros globales aceptados: accept-version.

Respuesta: { content: CompanySettings }.

Bloques de content:

Notas:

• Es solo lectura. Activar el buzón, enlazar Google Drive, cambiar el modo borrador o dar de alta VeriFactu se hace desde la interfaz (webUrl).
• inbox.email.address es confidencial. Cualquier correo que llegue a esa dirección entra en la bandeja de la empresa sin verificar el remitente. Dásela al usuario de la empresa, no la publiques.
• inbox.email.autoScan indica si lo que llega por correo se escanea al momento. Si es false, los documentos quedan en la bandeja con status: pending hasta que un usuario los escanee.
• inbox.googleDrive.error distinto de null significa que la sincronización está parada (credenciales caducadas o carpeta borrada) y el usuario tiene que volver a enlazar la carpeta.
• company.sandbox marca los entornos de pruebas: sus documentos no tienen validez y no se envían a la AEAT ni a las diputaciones.
• Lo que modules marca como no disponible devuelve 403 o 409 en los endpoints que lo requieren.
• Esta configuración cambia con muy poca frecuencia: cachéala por empresa y refréscala al arrancar una sesión o si una llamada falla por un motivo de configuración.

Ejemplo de respuesta

{
  "content": {
    "company": {
      "id": "com_4d8f0a6e-1b2c-4c3d-9e8f-0a1b2c3d4e5f",
      "sandbox": false,
      "name": "Cafés Zamora SL",
      "surname": null,
      "brand": "Cafés Zamora",
      "taxCode": "B12345674",
      "email": "hola@cafeszamora.example",
      "phone": "980 000 000",
      "website": "https://cafeszamora.example",
      "address": { "details": "Pza Mayor, 4", "zipcode": "49004", "city": "Zamora", "province": "Zamora", "country": "ES" },
      "country": "ES",
      "businessType": "EM",
      "taxRegion": "ES_ES",
      "currency": "EUR",
      "creationDate": "2024-03-12T09:15:00.000Z"
    },
    "locale": { "timezone": "Europe/Madrid", "language": "es", "dateFormat": "DD-MM-YYYY", "timeFormat": "HH:mm", "dateTimeFormat": "DD-MM-YYYY HH:mm" },
    "sales": { "newInvoiceMode": "final", "taxCalculationMode": "total", "externalInvoicesEnabled": false },
    "expenses": { "newBillMode": "final", "taskToExpenseDefaultDate": "invoiceDateOrEmpty" },
    "taxes": { "defaultSales": "BC", "equivalenceSurcharge": false, "applyVatEUToFinalConsumer": false, "vatEU": "ESB12345674" },
    "numbering": { "zeros": 4, "position": "prefix" },
    "accounting": { "startDate": "2024-01-01", "lockDate": "2025-12-31" },
    "fiscal": {
      "verifactu": { "enabled": true, "environment": "verifactu_production", "mode": "mode_verifactu", "startDate": "2026-01-01", "endDate": null, "exemption": null },
      "ticketbai": { "enabled": false, "environment": null, "region": null, "startDate": null }
    },
    "email": { "from": ["facturas@cafeszamora.example"] },
    "clientPortal": { "includeLinkInEmails": true },
    "inbox": {
      "email": { "active": true, "address": "cafes_zamora-a1b2c3d4e5@inbox.facturadirecta.com", "autoScan": true },
      "googleDrive": { "linked": true, "folderId": "1AbCdEfGhIjKlMnOpQrStUvWxYz", "folderUrl": "https://drive.google.com/drive/folders/1AbCdEfGhIjKlMnOpQrStUvWxYz", "error": null }
    },
    "modules": {
      "accounting": true, "inventory": false, "stockControl": false, "inbox": true, "googleDrive": true,
      "payrollScanning": true, "multicurrency": false, "clientPortal": true, "recurringInvoices": true,
      "scans": { "period": "total", "limit": -1 }
    },
    "webUrl": "https://3.facturadirecta.com/company/com_4d8f0a6e-1b2c-4c3d-9e8f-0a1b2c3d4e5f/settings"
  }
}

Copy as cURL

curl -s -H "Authorization: Bearer $ACCESS_TOKEN" \
  "https://app.facturadirecta.com/api/$COMPANY_ID/settings/company"

Lista de series de numeración#

GET /{companyId}/settings/series/{documentType} devuelve las series de numeración disponibles para un tipo de documento.

Parámetro de path:

• documentType (obligatorio) — uno de:
  • invoice — facturas de venta.
  • estimate — presupuestos.
  • deliveryNote — albaranes.
  • clientOrder — pedidos de cliente.
  • purchaseOrder — órdenes de compra.

Parámetros globales aceptados: accept-version.

Respuesta: { items: SeriesItem[] } sin paginar.

Cada SeriesItem tiene:

Notas:

• Las series se configuran desde la interfaz; este endpoint solo las expone. La API pública no crea, modifica ni borra series.
• Las series de pedidos de cliente y de órdenes de compra solo existen si la empresa las ha configurado; si no, items es una lista vacía.
• Para series de facturas, invoiceType distingue los regímenes fiscales aplicables. El campo correction queda por compatibilidad pero no debe usarse en código nuevo.
• ##/#### en serie se sustituye por el año al guardar el documento. Ejemplo: serie "F-##-" con fecha 2026 produce números como F-26-1, F-26-2…
• Si una serie no tiene plantilla propia, theme contiene la predeterminada vigente de la empresa. No presupongas que siempre será thm_master.

Copy as cURL

curl -s -H "Authorization: Bearer $ACCESS_TOKEN" \
  "https://app.facturadirecta.com/api/$COMPANY_ID/settings/series/invoice"

Lista de plantillas#

GET /{companyId}/settings/themes devuelve las plantillas de impresión configuradas en la empresa.

Parámetros globales aceptados: accept-version.

Respuesta: { items: ThemeItem[] } sin paginar.

Cada ThemeItem tiene:

Notas:

• Las plantillas se configuran desde la interfaz; este endpoint solo las expone.
• Para aplicar una plantilla concreta a un documento, indica su id en content.main.theme al crear o actualizar el documento.
• Si omites content.main.theme al crear un documento, FacturaDirecta usa la plantilla de su serie y, si la serie no tiene una asociación específica, la predeterminada de la empresa. thm_master es la alternativa final cuando no hay una selección válida.

Copy as cURL

curl -s -H "Authorization: Bearer $ACCESS_TOKEN" \
  "https://app.facturadirecta.com/api/$COMPANY_ID/settings/themes"

Recomendaciones#

• Empieza por /settings/company al abrir una sesión con una empresa: te dice en qué modo trabaja, qué módulos tiene y por dónde puede recibir documentos, y evita llamadas que fallarían por configuración.
• Cachea el catálogo localmente por empresa. La ficha, las series, los themes y los impuestos cambian con muy baja frecuencia; consultarlos en cada llamada gasta cuota innecesariamente.
• Refresca al fallar: si una creación falla con 400 por theme o serie desconocido, refresca el catálogo: alguien puede haber cambiado la configuración desde la interfaz.

Referencia exhaustiva#

Esta página cubre los matices funcionales de company, series y themes. Para impuestos, la referencia funcional está en la guía de Impuestos. Para el contrato completo campo a campo, consulta el Swagger UI o el openapi crudo.

Endpoints#

Scopes#

• settings:read — Lectura de ajustes/datos de configuración.