Descripción General
En Configuración del Espacio de Trabajo -> Empresa y Regional (/settings/workspace/general, /settings/workspace/company y /settings/workspace/regional), los administradores del espacio de trabajo configuran la identidad corporativa (Account Settings API), el perfil fiscal de facturación (PUT /api/v1/billing/settings y PUT /api/v1/billing/tax-profile) y los valores predeterminados de formato regional compartidos entre todas las plantillas de pases, portales públicos de descarga, resúmenes de series temporales de analíticas y facturas fiscales de Stripe.
Flujo de Configuración Regional y Metadatos del Espacio de Trabajo
Importante: Verifique y guarde siempre su Razón Social de la Empresa, Dirección de Facturación y NIF / Número de IVA (
PUT /api/v1/billing/settings) antes de ejecutar una mejora de plan de pago o una renovación. Las facturas fiscales en PDF generadas (GET /api/v1/billing/invoices/:id/download) son inmutables una vez finalizadas por el motor de facturación.
Perfil del Espacio de Trabajo (Account Settings API) y Perfil Fiscal (Billing API)
El recurso base del cliente (GET /api/v1/customer/:id y PUT /api/v1/customer/:id, validado estrictamente frente a request payload con forbidNonWhitelisted) gestiona la identidad principal del espacio de trabajo, mientras que PUT /api/v1/billing/settings almacena los metadatos de facturación fiscal e IVA (request payload):
| Campo | Endpoint (DTO) | Impacto Operativo | |
|---|---|---|---|
name / companyName | PUT /api/v1/customer/:id (request payload) | Nombre visible del espacio de trabajo y razón social corporativa impresa en los pases. | |
email / notificationEmails | PUT /api/v1/customer/:id | Correo electrónico de contacto principal del espacio de trabajo y lista de destinatarios de alertas operativas. | |
street, zipCode, city, state, country | PUT /api/v1/customer/:id | Campos de dirección del domicilio social (street2 opcional). | |
subdomain / domain / logo / icon | PUT /api/v1/customer/:id | Identificador corto del espacio de trabajo, vinculación de dominio personalizado y URL de logotipo/icono. | |
exportFormat (`'legacy' | 'new'`) | PUT /api/v1/customer/:id | Diseño de columnas CSV predeterminado para las exportaciones del espacio de trabajo. |
taxId, vatNumber, billingEmail, address | PUT /api/v1/billing/settings (request payload) | Número de IVA de la UE (por ejemplo, DE301928374), identificación fiscal y metadatos del destinatario impresos en las facturas PDF de Stripe. |
Actualización del Perfil del Espacio de Trabajo mediante la API (PUT /api/v1/customer/:id)
PUT /api/v1/customer/cus_89a12b34-56c7-4d89-9e01-23456789abcd HTTP/1.1
Host: api.passinstance.com
Authorization: Bearer <access_token>
Content-Type: application/json
{
"name": "Phenix Hospitality Europe",
"companyName": "Phenix Hospitality GmbH",
"email": "passes@phenix-hospitality.example.com",
"street": "Friedrichstrasse 114A",
"zipCode": "10117",
"city": "Berlin",
"country": "DE",
"exportFormat": "new"
}
Carga Útil de Respuesta (200 OK)
{
"id": "cus_89a12b34-56c7-4d89-9e01-23456789abcd",
"name": "Phenix Hospitality Europe",
"companyName": "Phenix Hospitality GmbH",
"email": "passes@phenix-hospitality.example.com",
"street": "Friedrichstrasse 114A",
"city": "Berlin",
"zipCode": "10117",
"country": "DE",
"exportFormat": "new",
"isActive": true,
"updatedAt": "2026-11-16T09:33:12.000Z"
}
Configuración Regional del Espacio de Trabajo (request payload)
Los ajustes regionales (GET /api/v1/customer/:customerId/regional-settings y PUT /api/v1/customer/:customerId/regional-settings) definen los valores predeterminados temporales, de moneda y de localización mediante request payload:
-
1
timezone(cadena IANA, máx. 50 caracteres): Determina los cortes de medianoche para los intervalos diarios de analíticas (GET /api/v1/analytics), las programaciones de flujos de trabajo y los reinicios de enfriamiento del escáner deOncePerDayRule. -
2
countryIso(ISO 3166-1 alfa-2, por ejemplo,"DE"): Jurisdicción del país principal para el espacio de trabajo. -
3
defaultCurrency(código ISO 4217 de 3 letras, por ejemplo,"EUR"): Denominación predeterminada para los libros mayores de valor almacenado dePREPAID_CARDy los canjes en puntos de venta minoristas (POST /v1/pos/redeem). -
4
defaultLocale(etiqueta BCP-47, por ejemplo,"de-DE"): Idioma de respaldo servido en las páginas públicas de descarga (/d/:slug,/s/:token) y en los correos electrónicos transaccionales. -
5
dataResidencyRegion(cadena opcional, por ejemplo,"eu-central-1"): Metadatos de residencia de datos del espacio de trabajo.
Actualización de la Configuración Regional mediante la API
PUT /api/v1/customer/cus_89a12b34-56c7-4d89-9e01-23456789abcd/regional-settings HTTP/1.1
Host: api.passinstance.com
Authorization: Bearer <access_token>
Content-Type: application/json
{
"timezone": "Europe/Berlin",
"countryIso": "DE",
"defaultCurrency": "EUR",
"defaultLocale": "de-DE",
"dataResidencyRegion": "eu-central-1"
}
{
"customerId": "cus_89a12b34-56c7-4d89-9e01-23456789abcd",
"timezone": "Europe/Berlin",
"countryIso": "DE",
"defaultCurrency": "EUR",
"defaultLocale": "de-DE",
"dataResidencyRegion": "eu-central-1",
"updatedAt": "2026-11-16T09:34:00.000Z"
}
Documentación Relacionada
-
Configure dominios personalizados (
CNAME) y remitentes de correo electrónico SMTP/DKIM con marca en Opciones de Marca Personalizada y Marca Blanca. -
Descargue facturas en PDF conformes con el IVA en Facturas e Historial de Facturación.
-
Gestione jerarquías de agencias con múltiples espacios de trabajo en Gestión Multicliente.
