Configuración de la empresa

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

Las 4 operaciones

Endpoint	Cubre
`GET /settings/taxes/sales`	Catálogo de impuestos para documentos de venta. Documentado en la guía de Impuestos.
`GET /settings/taxes/purchases`	Catálogo de impuestos para documentos de compra. Documentado en la guía de Impuestos.
`GET /settings/series/{documentType}`	Series de numeración configuradas en la empresa para un tipo de documento.
`GET /settings/themes`	Plantillas de impresión disponibles.

Las cuatro 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 solo documenta las dos operaciones restantes (series y themes).

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:

Campo	Tipo	Significado
`serie`	string	Valor de la serie. Puede contener `##` o `####`, que se sustituye por el año de la fecha del documento en el momento de guardar.
`reset`	`"never"` \| `"year"`	Si reinicia la numeración con el cambio de año (`year`) o si continúa desde el último número del año anterior (`never`).
`manual`	boolean	Si la serie acepta numeración manual desde la interfaz.
`notes`	string	Notas descriptivas.
`theme`	string	ID de plantilla por defecto que se aplica a documentos de esta serie.
`invoiceType`	enum	Solo en series de facturas. Valores: `complete`, `complete_correction`, `simplified`, `simplified_correction`, `external`.
`correction`	boolean	OBSOLETO — usar `invoiceType` en su lugar. Indica si la serie es para rectificativas.

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...

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:

Campo	Tipo	Significado
`id`	string	Identificador de la plantilla. Es lo que se usa en `content.main.theme` de los documentos.
`title`	string	Nombre legible.

Notas:

Las plantillas se configuran desde la interfaz; este endpoint solo las expone.
Para aplicar una plantilla a un documento, indica su id en content.main.theme al crear o actualizar el documento.

Copy as cURL

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

Recomendaciones

Cachea el catálogo localmente por empresa. Series, themes e 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 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

Método	Path	operationId	Scopes	Descripción
GET	`/{companyId}/settings/series/{documentType}`	`getSeries`	`settings:read`	Lista de series de numeración
GET	`/{companyId}/settings/taxes/purchases`	`getPurchasesTaxes`	`settings:read`	Lista de impuestos de compra disponibles
GET	`/{companyId}/settings/taxes/sales`	`getSalesTaxes`	`settings:read`	Lista de impuestos de venta disponibles
GET	`/{companyId}/settings/themes`	`getThemes`	`settings:read`	Lista de plantillas de documentos disponibles

Scopes

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